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

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.js

@@ -28,8 +28,8 @@ 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 { 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 +56,7 @@ export class Backend {
     #options;
     #config;
     #queue;
-    #writeLog;
+    #rpcLog;
     #unknownMethodsSeen = new Set();
     #writer;
     #repair;
@@ -125,14 +125,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 +166,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 +213,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 +236,7 @@ export class Backend {
         }
         if (this.#sessions > 0) {
             if (previous === 0) {
-                void this.#resubscribe();
+                void runWithOrigin('background', () => this.#resubscribe());
             }
             return;
         }
@@ -246,7 +246,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 +279,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);
@@ -468,10 +470,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 +495,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 +518,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
                 ? {}
@@ -833,7 +844,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 +853,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 +891,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({
@@ -1282,7 +1296,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 +1324,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();
@@ -1630,8 +1644,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

@@ -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;

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

@@ -27,6 +27,12 @@ import { CallbackServers } from '../rpc/server.js';
 import { localIPv4Addresses, probePortState, 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;
+/**
+ * Task 48: the manager's own calls - `init`, de-init, `ping` - are the backend's business whatever
+ * asked for the connection, so they name their origin instead of inheriting a request's context
+ * (a `config.set` from the settings dialog is a UI action; the watchdog it starts is not).
+ */
+const BACKGROUND = { origin: 'background' };
 /** Where an interface process on this very box calls back (#144). */
 export const LOOPBACK_IP = '127.0.0.1';
 /** How long `stop()` waits for the de-registering `init(url, '')` calls. */
@@ -397,7 +403,7 @@ export class InterfaceManager {
         }
         const url = this.#callbackUrl(entry.target.resolved.protocol);
         try {
-            await withTimeout(entry.client.call('init', [url, '']), SHUTDOWN_TIMEOUT_MS, () => connectionError(`${entry.name}: de-registering timed out`));
+            await withTimeout(entry.client.call('init', [url, ''], BACKGROUND), SHUTDOWN_TIMEOUT_MS, () => connectionError(`${entry.name}: de-registering timed out`));
         }
         catch {
             // a CCU that is already gone cannot be told that we are going too
@@ -416,6 +422,7 @@ export class InterfaceManager {
             auth: target.auth,
             ...(this.#options.rpcTimeoutMs === undefined ? {} : { timeoutMs: this.#options.rpcTimeoutMs }),
             ...(this.#options.onCall === undefined ? {} : { onCall: this.#options.onCall }),
+            ...(this.#options.originOf === undefined ? {} : { originOf: this.#options.originOf }),
         };
         const client = (this.#options.createClient ?? ((clientOptions) => new RpcClient(clientOptions)))(options);
         return {
@@ -518,7 +525,7 @@ export class InterfaceManager {
         const url = this.#callbackUrl(resolved.protocol);
         this.#update(entry, { callbackUrl: url, callbackFailure: undefined });
         try {
-            await entry.client.call('init', [url, resolved.ident]);
+            await entry.client.call('init', [url, resolved.ident], BACKGROUND);
             entry.lastEvent = this.#now();
             const wasFailing = entry.failures > 0;
             entry.failures = 0;
@@ -578,7 +585,7 @@ export class InterfaceManager {
     }
     async #ping(entry) {
         try {
-            await entry.client.call('ping', ['hmm']);
+            await entry.client.call('ping', ['hmm'], BACKGROUND);
         }
         catch (error) {
             // the answer to a ping is an event, so a failing ping is only a hint; the re-init

package/node_modules/@homematic-manager/backend/dist/meta/service.js

@@ -220,7 +220,7 @@ export class MetaService {
     async assign(refs, nodePath, on) {
         const document = this.#provider.document();
         const entries = [];
-        for (const ref of refs) {
+        for (const ref of this.#provider.kind === 'rega' ? channelsOfDevices(refs, document) : refs) {
             const object = document.objects[ref];
             const current = object?.enums ?? [];
             const has = current.includes(nodePath);
@@ -363,6 +363,28 @@ export class MetaService {
     }
 }
 /** The ids already taken among the siblings a new node would join. */
+/**
+ * The refs an assignment on ReGa works on: a device is replaced by its channels, `:0` aside.
+ *
+ * ReGa files channels, so a device holds no path of its own, and the ReGa provider applies a
+ * device's membership list to each of its channels as their complete list. Handing it the device's
+ * empty list plus the one room took the channels out of every other room and function, and a
+ * removal through the device removed nothing (task 49). Channel by channel, each keeps its own list
+ * and only the one path changes. A device the document knows no channels of stays as it is.
+ */
+function channelsOfDevices(refs, document) {
+    const result = new Set();
+    for (const ref of refs) {
+        const parsed = parseRef(ref);
+        const channels = parsed === undefined || parsed.address.includes(':')
+            ? []
+            : Object.keys(document.objects).filter((key) => key.startsWith(`${ref}:`) && !key.endsWith(':0'));
+        for (const entry of channels.length === 0 ? [ref] : channels) {
+            result.add(entry);
+        }
+    }
+    return [...result];
+}
 function siblingIds(definition, parent, enumId) {
     if (parent === null || parent === undefined || parent === enumId) {
         return definition.tree.map((node) => node.id);

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

@@ -25,7 +25,7 @@
  * `unitLabel()` in the core still repairs. See the README for what remains broken in the libraries
  * (BIN-RPC decodes strings as UTF-8, and both request paths write UTF-8).
  */
-import type { ExplicitDouble, RpcProtocol, RpcValue } from '@homematic-manager/core';
+import type { ExplicitDouble, RpcOrigin, RpcProtocol, RpcValue } from '@homematic-manager/core';
 /**
  * What may be sent to an interface: everything an answer can carry, plus the explicit-double
  * wrapper both encoders understand. A paramset payload is full of them, and an interface that gets
@@ -34,7 +34,7 @@ import type { ExplicitDouble, RpcProtocol, RpcValue } from '@homematic-manager/c
 export type RpcOutValue = boolean | number | string | ExplicitDouble | RpcOutValue[] | {
     [key: string]: RpcOutValue;
 };
-/** What the write log and the RPC console record for one call. */
+/** What the RPC log records for one call - every call, task 48. */
 export interface RpcCallRecord {
     readonly interfaceName: string;
     readonly method: string;
@@ -45,6 +45,13 @@ export interface RpcCallRecord {
     readonly durationMs: number;
     /** Milliseconds since epoch. */
     readonly timestamp: number;
+    /** Who asked: the console, a UI action, or the backend on its own. */
+    readonly origin: RpcOrigin;
+}
+/** Per-call options of {@link RpcClient.call}. */
+export interface RpcCallOptions {
+    /** The origin of this call, when the caller knows it better than the client's resolver does. */
+    readonly origin?: RpcOrigin;
 }
 /** Anything that answers `methodCall`; the tests pass a fake instead of a socket. */
 export interface RpcTransport {
@@ -70,8 +77,13 @@ export interface RpcClientOptions {
     readonly encoding?: string;
     /** A CCU's TLS certificate is self-signed, so this is false by default. */
     readonly rejectUnauthorized?: boolean;
-    /** Called for every finished call - the write log and the console history hang off it. */
+    /** Called for every finished call - the RPC log hangs off it. */
     readonly onCall?: (record: RpcCallRecord) => void;
+    /**
+     * The origin of a call that names none: the backend answers from its request context (task
+     * 48). Without a resolver every call is `background`, which is right for a client on its own.
+     */
+    readonly originOf?: () => RpcOrigin;
     /** Injected by the tests in place of the real libraries. */
     readonly createTransport?: (options: RpcClientOptions) => RpcTransport;
 }
@@ -90,9 +102,10 @@ export declare class RpcClient {
     get description(): string;
     /**
      * Calls a method. Rejects with a `BackendError`: `kind: 'rpc'` for a fault the interface
-     * answered, `kind: 'connection'` for a timeout or a socket problem.
+     * answered, `kind: 'connection'` for a timeout or a socket problem. Every call, however it
+     * ends, is reported through `onCall` with its origin - the one given here, or the resolver's.
      */
-    call(method: string, params?: readonly RpcOutValue[]): Promise<RpcValue>;
+    call(method: string, params?: readonly RpcOutValue[], options?: RpcCallOptions): Promise<RpcValue>;
     /** Closes the underlying socket, if the library has one. */
     close(): void;
     get closed(): boolean;

package/node_modules/@homematic-manager/backend/dist/rpc/client.js

@@ -113,6 +113,7 @@ export class RpcClient {
     #transport;
     #timeoutMs;
     #onCall;
+    #originOf;
     #closed = false;
     constructor(options) {
         this.name = options.name;
@@ -121,6 +122,7 @@ export class RpcClient {
         this.protocol = options.protocol;
         this.#timeoutMs = options.timeoutMs ?? DEFAULT_RPC_TIMEOUT_MS;
         this.#onCall = options.onCall ?? (() => undefined);
+        this.#originOf = options.originOf ?? (() => 'background');
         this.#transport = (options.createTransport ?? createTransport)(options);
     }
     /** A short description for error messages: `HmIP-RF (ccu.lan:2010, xmlrpc)`. */
@@ -129,21 +131,24 @@ export class RpcClient {
     }
     /**
      * Calls a method. Rejects with a `BackendError`: `kind: 'rpc'` for a fault the interface
-     * answered, `kind: 'connection'` for a timeout or a socket problem.
+     * answered, `kind: 'connection'` for a timeout or a socket problem. Every call, however it
+     * ends, is reported through `onCall` with its origin - the one given here, or the resolver's.
      */
-    async call(method, params = []) {
+    async call(method, params = [], options = {}) {
         if (this.#closed) {
             throw connectionError(`${this.description}: the client is closed`);
         }
+        // resolved before the first await: the context that asked is the one that counts
+        const origin = options.origin ?? this.#originOf();
         const started = Date.now();
         try {
             const result = await withTimeout(this.#invoke(method, [...params]), this.#timeoutMs, () => connectionError(`${this.description}: ${method} timed out after ${String(this.#timeoutMs)} ms`));
-            this.#record(method, params, started, { ok: true, result });
+            this.#record(method, params, started, origin, { ok: true, result });
             return result;
         }
         catch (error) {
             const failure = this.#asBackendError(method, error);
-            this.#record(method, params, started, { ok: false, error: failure.message });
+            this.#record(method, params, started, origin, { ok: false, error: failure.message });
             throw failure;
         }
     }
@@ -186,7 +191,7 @@ export class RpcClient {
         const message = error instanceof Error ? error.message : String(error);
         return connectionError(`${this.description}: ${method} failed: ${message}`, error);
     }
-    #record(method, params, started, outcome) {
+    #record(method, params, started, origin, outcome) {
         this.#onCall({
             interfaceName: this.name,
             method,
@@ -196,6 +201,7 @@ export class RpcClient {
             ...(outcome.error === undefined ? {} : { error: outcome.error }),
             durationMs: Date.now() - started,
             timestamp: started,
+            origin,
         });
     }
 }