homematic-manager 3.0.0-beta.2 → 3.0.0-beta.21

package/dist/server.js

@@ -24,11 +24,12 @@
 import fs from 'node:fs/promises';
 import http from 'node:http';
 import path from 'node:path';
-import { ApiWebSocketServer, Backend, RegaAuthenticator } from '@homematic-manager/backend';
-import { applyCookieToken, applySessionToken, clearedSessionCookie, createToken, isLoopbackHost, readCookie, SESSION_COOKIE, sessionCookie, TOKEN_COOKIE, tokenCookie, } from './auth.js';
+import { ApiWebSocketServer, Backend, RegaAuthenticator, } from '@homematic-manager/backend';
+import { applyCookieToken, applySessionToken, clearedSessionCookie, createToken, hasTokenQuery, isLoopbackHost, readCookie, SESSION_COOKIE, sessionCookie, TOKEN_COOKIE, tokenCookie, withTokenQuery, } from './auth.js';
 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, sidCanBeSession, } from './occulite.js';
 import { defaultDataDir, defaultMetadataDir, defaultUiDir, packageVersion } from './paths.js';
 import { proxyRequest, proxyUpgrade } from './proxy.js';
 import { RateLimiter, SessionStore } from './sessions.js';
@@ -39,6 +40,12 @@ export const DEFAULT_PORT = 8090;
 export const DEFAULT_HOST = '127.0.0.1';
 /** How long `close()` waits for `backend.stop()` before it gives up and exits anyway. */
 export const SHUTDOWN_TIMEOUT_MS = 5000;
+/**
+ * B-94, D-65: how long the box's answer about an `X-Occulite-Session` is believed without asking
+ * again. The addon contract says to cache it briefly, if at all; a minute covers the burst of
+ * assets and the socket of one page load.
+ */
+export const GATE_RECHECK_MS = 60_000;
 /**
  * How often an idle API socket is pinged. Below lighttpd's `server.max-read-idle` /
  * `max-write-idle` default of 60 s, which is what would otherwise cut the proxied socket of the
@@ -77,8 +84,8 @@ export async function createWebHost(options = {}) {
     const apiPath = `${base}api`;
     const authMode = options.authMode ?? 'token';
     requireLocalForRega(authMode, options, auth);
-    // D-32: everything the login needs, and nothing at all in `token` mode
-    const sessions = authMode === 'rega' ? new SessionStore(sessionStoreOptions(options)) : undefined;
+    // D-32/D-40: everything a login needs, and nothing at all in `token` mode
+    const sessions = authMode === 'token' ? undefined : new SessionStore(sessionStoreOptions(options));
     const loginLimit = authMode === 'rega' ? new RateLimiter() : undefined;
     const credentials = authMode === 'rega'
         ? (options.authenticator ??
@@ -86,10 +93,33 @@ export async function createWebHost(options = {}) {
                 onNotice: (level, message) => log[level](`login: ${message}`),
             }))
         : undefined;
+    // D-40: the box that issued the session the shell hands over
+    const occuliteUrl = (options.occuliteUrl ?? 'http://127.0.0.1').replace(/\/$/, '');
+    const boxSessions = authMode === 'occulite'
+        ? (options.sessionChecker ??
+            new OcculiteAuthenticator({
+                baseUrl: occuliteUrl,
+                onNotice: (level, message) => log[level](`login: ${message}`),
+            }))
+        : undefined;
     let connection;
     let backend;
     if (!demo) {
         await ensureDataDir(dataDir);
+        const defaultCallbackPorts = callbackDefaults(options);
+        if (defaultCallbackPorts !== undefined) {
+            log.info(`callback: default ports xmlrpc=${String(defaultCallbackPorts.xmlrpc)} binrpc=${String(defaultCallbackPorts.binrpc)} while the configuration says 0`);
+        }
+        const pinnedCallback = callbackPins(options);
+        if (pinnedCallback !== undefined) {
+            const { ip, xmlrpcPort, binrpcPort } = pinnedCallback;
+            const parts = [
+                ...(ip === undefined ? [] : [`ip=${ip}`]),
+                ...(xmlrpcPort === undefined ? [] : [`xmlrpc=${String(xmlrpcPort)}`]),
+                ...(binrpcPort === undefined ? [] : [`binrpc=${String(binrpcPort)}`]),
+            ];
+            log.info(`callback: ${parts.join(' ')} set at start, read-only in the settings dialog`);
+        }
         backend = await Backend.open({
             dataDir,
             version: options.version ?? packageVersion(),
@@ -98,6 +128,9 @@ export async function createWebHost(options = {}) {
             // reports them, and Electron's in-process transport reports none - so an Electron
             // window can never be idled out however the backend is configured.
             ...(options.idleUnsubscribeMs === undefined ? {} : { idleUnsubscribeMs: options.idleUnsubscribeMs }),
+            ...(defaultCallbackPorts === undefined ? {} : { defaultCallbackPorts }),
+            ...(pinnedCallback === undefined ? {} : { pinnedCallback }),
+            ...(options.inContainer === true ? { inContainer: true } : {}),
             ...options.backendOptions,
         });
         backend.on('notice', (notice) => {
@@ -146,6 +179,36 @@ export async function createWebHost(options = {}) {
             return;
         }
         const rest = pathname.slice(base.length);
+        // D-40: the hand-over from openccu-lite's shell. It opens an addon page with the user's
+        // session on the URL (`?sid=@xxxxxxxxxx@`), the same convention the CCU's WebUI uses; the
+        // 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 = 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;
+            }
+        }
         // D-32: the login is the one route that takes a POST, and the one route that is reachable
         // without a session - it is what hands one out
         if (sessions && rest === 'login') {
@@ -168,7 +231,9 @@ export async function createWebHost(options = {}) {
             if (rest === 'logout') {
                 sessions.remove(readCookie(request.headers.cookie, SESSION_COOKIE));
                 response.writeHead(302, {
-                    Location: `${base}login`,
+                    // D-40: on openccu-lite the login is the box's, not ours, so this is where a
+                    // logout goes; the box's own session stays valid until it is ended there
+                    Location: authMode === 'occulite' ? '/' : `${base}login`,
                     'Set-Cookie': clearedSessionCookie(base, isHttps(request)),
                     'Cache-Control': 'no-store',
                 });
@@ -176,13 +241,30 @@ export async function createWebHost(options = {}) {
                 return;
             }
             session = sessions.get(readCookie(request.headers.cookie, SESSION_COOKIE));
+            // B-94, D-65: on openccu-lite the gate names the session it let through. It is checked
+            // with the box like the `?sid=` hand-over, and ignored when the box does not confirm it.
+            session = await sessionFromGate(request, session);
+            if (session?.credential !== undefined) {
+                // D-40: writes to the box go out as the session of whoever is looking at the page
+                backend?.noteMetaSession(session.credential);
+            }
             if (!session && !hasValidToken(request)) {
                 // the page itself becomes the login form; anything else - assets, metadata, images -
                 // is answered with a plain 401, because a login page in place of a stylesheet only
                 // confuses a browser. The `settings.cgi` hand-over of task 13 never lands here: its
                 // token cookie is accepted above, and the WebUI session it checked is why.
                 if (rest === '' || rest === 'index.html') {
-                    sendLoginPage(request, response, 200);
+                    if (authMode === 'occulite') {
+                        // D-40: there is no form to show - openccu-lite's users are the box's, and
+                        // lighttpd's own gate sends an unauthenticated request to the box's login
+                        // long before it reaches this process. Landing there is the honest answer
+                        // to a bookmark that was opened without a session.
+                        response.writeHead(302, { Location: '/', 'Cache-Control': 'no-store' });
+                        response.end();
+                    }
+                    else {
+                        sendLoginPage(request, response, 200);
+                    }
                 }
                 else {
                     unauthorised(response);
@@ -277,6 +359,107 @@ export async function createWebHost(options = {}) {
         });
         response.end();
     }
+    /**
+     * D-40: `?sid=@…@` from openccu-lite's shell into a session of this host.
+     *
+     * One check against the box and one redirect. A session that the box does not know goes back to
+     * the box's login rather than to a form here, and the failure is not counted or rate-limited:
+     * the id was not guessed at, it was handed over, and the only way to get a wrong one is for it
+     * to have expired.
+     */
+    async function handleHandover(request, response, offered, url, rest) {
+        const checked = await boxSessions?.check(offered);
+        if (!checked) {
+            log.warn(`login: openccu-lite refused the session offered from ${clientAddress(request)}`);
+            response.writeHead(302, { Location: '/', 'Cache-Control': 'no-store' });
+            response.end();
+            return;
+        }
+        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`);
+        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, sessions.ttlMs / 1000, isHttps(request)),
+            'Cache-Control': 'no-store',
+        });
+        response.end();
+    }
+    /**
+     * B-94, D-65: the sessions made from the gate's `X-Occulite-Session`, by the box's session id,
+     * with the time the box confirmed it. A request of the same page load that has no cookie of ours
+     * yet - an asset, the socket - finds its session here instead of asking the box again.
+     */
+    const gateSessions = new Map();
+    let lastGateWarning = 0;
+    /** The session id the gate put on a request; `undefined` outside `occulite` mode and for a malformed one. */
+    function gateSid(request) {
+        if (!boxSessions) {
+            return undefined;
+        }
+        const value = request.headers[OCCULITE_SESSION_HEADER];
+        // two copies are joined with a comma by Node, which no session id contains: refused
+        return parseSid(Array.isArray(value) ? value.join(', ') : value);
+    }
+    /** A session made from this box session and confirmed less than `GATE_RECHECK_MS` ago. */
+    function cachedGateSession(sid) {
+        const entry = gateSessions.get(sid);
+        if (!entry) {
+            return undefined;
+        }
+        const session = sessions?.get(entry.id);
+        if (!session || Date.now() - entry.checkedAt > GATE_RECHECK_MS) {
+            gateSessions.delete(sid);
+            return undefined;
+        }
+        return session;
+    }
+    /**
+     * B-94, D-65: the session of a request that came through openccu-lite's gate.
+     *
+     * 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.
+     */
+    async function sessionFromGate(request, current) {
+        const offered = gateSid(request);
+        if (!boxSessions || !sessions || offered === undefined || current?.credential === offered) {
+            return current;
+        }
+        const cached = cachedGateSession(offered);
+        if (cached) {
+            return cached;
+        }
+        const checked = await boxSessions.check(offered, { requireState: true });
+        if (!checked) {
+            // a header the box does not confirm counts as no header: the cookie, the token and the
+            // redirect to the box decide, as they did before there was a header
+            if (Date.now() - lastGateWarning > GATE_RECHECK_MS) {
+                lastGateWarning = Date.now();
+                log.warn(`login: openccu-lite did not confirm the X-Occulite-Session from ${clientAddress(request)}`);
+            }
+            return current;
+        }
+        const now = Date.now();
+        for (const [sid, entry] of gateSessions) {
+            if (now - entry.checkedAt > GATE_RECHECK_MS) {
+                gateSessions.delete(sid);
+            }
+        }
+        const session = sessions.create(checked.name, checked.level, checked.sid);
+        gateSessions.set(checked.sid, { id: session.id, checkedAt: now });
+        log.info(`login: ${checked.name} (level ${String(checked.level)}) through the openccu-lite gate`);
+        return session;
+    }
     /** The token cookie of task 13 - `settings.cgi`'s hand-over still opens every door. */
     function hasValidToken(request) {
         return token !== undefined && readCookie(request.headers.cookie, TOKEN_COOKIE) === token;
@@ -348,6 +531,14 @@ export async function createWebHost(options = {}) {
             // D-32: and a login session opens the same socket, in the same way
             if (sessions) {
                 applySessionToken(request, token, (id) => sessions.get(id) !== undefined);
+                // B-94: the socket of a page that came in through the gate, before our cookie is there
+                const gate = gateSid(request);
+                if (token !== undefined &&
+                    gate !== undefined &&
+                    !hasTokenQuery(request.url) &&
+                    cachedGateSession(gate)) {
+                    request.url = withTokenQuery(request.url, token);
+                }
             }
             api.handleUpgrade(request, socket, head);
             return;
@@ -397,6 +588,7 @@ export async function createWebHost(options = {}) {
         port,
         base,
         token,
+        issueCookie,
         authMode,
         sessions,
         close,
@@ -416,6 +608,16 @@ export async function ensureDataDir(dataDir) {
  * says why is the only useful answer.
  */
 export function requireLocalForRega(authMode, options, auth) {
+    if (authMode === 'occulite') {
+        // D-40: no `--local` requirement - the box is reached over HTTP and may be named with
+        // `--occulite-url` - but the same rule about the token holds: without one the socket lets
+        // everybody in and checking the session would guard nothing.
+        if (!auth) {
+            throw new Error('--auth-mode occulite cannot be combined with --no-auth: without a token the api socket lets ' +
+                'everyone in anyway, and the session check would guard nothing.');
+        }
+        return;
+    }
     if (authMode !== 'rega') {
         return;
     }
@@ -466,17 +668,36 @@ function upstreamOf(connection) {
         ...(connection.auth ? { auth: connection.auth } : {}),
     };
 }
-/** `--ccu`, `--local` and the callback options win over what `config.json` holds. */
+/** Task 35: the default pair, or nothing when neither port is set to anything but `0`. */
+function callbackDefaults(options) {
+    const xmlrpc = options.callbackXmlrpcDefaultPort ?? 0;
+    const binrpc = options.callbackBinrpcDefaultPort ?? 0;
+    return xmlrpc === 0 && binrpc === 0 ? undefined : { xmlrpc, binrpc };
+}
+/**
+ * Task 38: the callback fields given at start, or nothing. An empty address and a port of `0` are
+ * "not configured" in the connection model and pin nothing.
+ */
+function callbackPins(options) {
+    const pins = {
+        ...(options.callbackIp === undefined || options.callbackIp === '' ? {} : { ip: options.callbackIp }),
+        ...(options.callbackXmlrpcPort === undefined || options.callbackXmlrpcPort === 0
+            ? {}
+            : { xmlrpcPort: options.callbackXmlrpcPort }),
+        ...(options.callbackBinrpcPort === undefined || options.callbackBinrpcPort === 0
+            ? {}
+            : { binrpcPort: options.callbackBinrpcPort }),
+    };
+    return Object.keys(pins).length === 0 ? undefined : pins;
+}
+/**
+ * `--ccu` and `--local` win over what `config.json` holds, and are written to it. The callback
+ * options are not: since task 38 the backend lays them over the profile (`pinnedCallback`).
+ */
 async function applyConnectionOptions(backend, options, log) {
     const wantsHost = options.ccu !== undefined && options.ccu !== '';
     const wantsLocal = options.local !== undefined;
-    const callback = {
-        ...(options.callbackIp === undefined ? {} : { ip: options.callbackIp }),
-        ...(options.callbackXmlrpcPort === undefined ? {} : { xmlrpcPort: options.callbackXmlrpcPort }),
-        ...(options.callbackBinrpcPort === undefined ? {} : { binrpcPort: options.callbackBinrpcPort }),
-    };
-    const wantsCallback = Object.keys(callback).length > 0;
-    if (!wantsHost && !wantsLocal && !wantsCallback) {
+    if (!wantsHost && !wantsLocal) {
         return;
     }
     const config = await backend.request('config.get');
@@ -484,22 +705,11 @@ async function applyConnectionOptions(backend, options, log) {
         ...config.connection,
         ...(wantsHost ? { host: options.ccu } : {}),
         ...(wantsLocal ? { local: options.local } : {}),
-        callback: { ...config.connection.callback, ...callback },
     };
-    if (connection.host === config.connection.host &&
-        connection.local === config.connection.local &&
-        connection.callback.ip === config.connection.callback.ip &&
-        connection.callback.xmlrpcPort === config.connection.callback.xmlrpcPort &&
-        connection.callback.binrpcPort === config.connection.callback.binrpcPort) {
+    if (connection.host === config.connection.host && connection.local === config.connection.local) {
         return;
     }
-    if (wantsHost || wantsLocal) {
-        log.info(`connection: host=${connection.host}${connection.local === true ? ' (local)' : ''}`);
-    }
-    if (wantsCallback) {
-        const { ip, xmlrpcPort, binrpcPort } = connection.callback;
-        log.info(`callback: ${ip === '' ? 'auto' : ip} xmlrpc=${String(xmlrpcPort)} binrpc=${String(binrpcPort)}`);
-    }
+    log.info(`connection: host=${connection.host}${connection.local === true ? ' (local)' : ''}`);
     await backend.request('config.set', connection);
 }
 async function withTimeout(work, ms, onTimeout) {

package/dist/sessions.d.ts

@@ -22,6 +22,14 @@ export interface Session {
     readonly user: string;
     /** ReGa `UserLevel()`: 8 admin, 2 user, 1 guest. */
     readonly level: number;
+    /**
+     * D-40: the credential the box gave this user - their `?sid=@…@`.
+     *
+     * Kept because on openccu-lite it is not only proof of a login: it is what a write to the box's
+     * metadata store goes out with, so that a rename is attributed to the person who asked for it
+     * rather than to the addon. Absent in every other mode, where nothing downstream needs one.
+     */
+    readonly credential?: string;
     /** Epoch milliseconds; pushed out by every request that uses the session. */
     expiresAt: number;
 }
@@ -41,7 +49,7 @@ export declare class SessionStore {
     constructor(options?: SessionStoreOptions);
     get size(): number;
     /** A new session for a user who has just proved who they are. */
-    create(user: string, level: number): Session;
+    create(user: string, level: number, credential?: string): Session;
     /**
      * The session behind an id, expiry slid forward - or `undefined` when there is none, which is
      * the answer for an unknown, a forged and an expired id alike.

package/dist/sessions.js

@@ -37,9 +37,15 @@ export class SessionStore {
         return this.#sessions.size;
     }
     /** A new session for a user who has just proved who they are. */
-    create(user, level) {
+    create(user, level, credential) {
         this.sweep();
-        const session = { id: this.#createId(), user, level, expiresAt: this.#now() + this.ttlMs };
+        const session = {
+            id: this.#createId(),
+            user,
+            level,
+            ...(credential === undefined ? {} : { credential }),
+            expiresAt: this.#now() + this.ttlMs,
+        };
         this.#sessions.set(session.id, session);
         return session;
     }

package/dist/testSupport.js

@@ -183,7 +183,14 @@ export async function startForTest(options = {}) {
         }
     }
     const ports = simulator
-        ? { 'BidCos-RF': simulator.ports.rfd, 'HmIP-RF': simulator.ports.hmip }
+        ? {
+            'BidCos-RF': simulator.ports.rfd,
+            'HmIP-RF': simulator.ports.hmip,
+            // only when the simulator was given a `virtualListenPort` (the CCU's group process)
+            ...(typeof simulator.ports.virtual === 'number'
+                ? { VirtualDevices: simulator.ports.virtual }
+                : {}),
+        }
         : {};
     const host = await createWebHost({
         port: 0,
@@ -206,7 +213,7 @@ export async function startForTest(options = {}) {
     if (simulator && host.backend) {
         const connection = {
             host: '127.0.0.1',
-            interfaces: ['BidCos-RF', 'HmIP-RF'],
+            interfaces: ['BidCos-RF', 'HmIP-RF', ...(ports['VirtualDevices'] === undefined ? [] : ['VirtualDevices'])],
             autoDetect: false,
             extraInterfaces: [],
             tls: false,

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

@@ -17,8 +17,10 @@ import { maintenanceAddress, type AppConfig, type ApiEventName, type ApiEvents,
 import { type ConfigStoreOptions } from '../config/store.js';
 import { type DiscoverOptions } from '../discovery/discover.js';
 import { InterfaceManager, type InterfaceManagerOptions } from '../interfaces/manager.js';
+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. */
@@ -29,6 +31,26 @@ export interface BackendOptions extends Omit<ConfigStoreOptions, 'version'> {
     /** Roots `data.file` may read from, keyed by the prefix the UI uses. */
     readonly fileRoots?: Readonly<Record<string, string>>;
     readonly callbackHost?: string;
+    /**
+     * Task 35 (D-43): the callback ports taken while the connection's are `0` - the CCU addon's fixed
+     * pair. A property of the host, not of the profile: it is never written to `config.json`, and
+     * `AppConfig.callbackDefaultPorts` reports it so the settings dialog can say what `0` means.
+     */
+    readonly defaultCallbackPorts?: {
+        readonly xmlrpc: number;
+        readonly binrpc: number;
+    };
+    /**
+     * Task 38: the host runs in a container (the image sets `HMM_IN_CONTAINER`). Where its callback
+     * servers listen beyond the loopback, `AppConfig.publishCallbackPorts` tells the interface
+     * 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;
@@ -48,6 +70,8 @@ export interface BackendOptions extends Omit<ConfigStoreOptions, 'version'> {
     /** Injected by the tests in place of the real world. */
     readonly createInterfaceManager?: (options: InterfaceManagerOptions) => InterfaceManager;
     readonly createRega?: (options: RegaServiceOptions) => RegaService;
+    /** D-40: injected by the tests, and by the integration test that runs a real occulited. */
+    readonly metaOptions?: Partial<MetaServiceOptions>;
     readonly discover?: (options: DiscoverOptions) => Promise<AppConfig['discovered']>;
     readonly interfaceManagerOptions?: Partial<InterfaceManagerOptions>;
     readonly regaOptions?: Partial<RegaServiceOptions>;
@@ -82,6 +106,15 @@ export declare class Backend {
      * on the wire unchanged.
      */
     request<M extends ApiMethodName>(method: M, ...params: ApiParams<M>): Promise<ApiResult<M>>;
+    /**
+     * D-40: the session of the person looking at the page, for the writes to an openccu-lite box.
+     *
+     * The shell of the box hands an addon page the user's session as `?sid=@xxxxxxxxxx@`, and that
+     * session is a valid credential for the metadata API. The addon reads with the box's local
+     * token, which is read-only by design, and writes as the user - so nothing renames a device
+     * unless a person asked for it. Hosts without a login never call this.
+     */
+    noteMetaSession(sid: string | undefined): void;
     /** One polling round; public so a test does not have to wait five minutes. */
     pollServiceMessages(): Promise<void>;
     /** One sweep; public so a test can run it without the timer. */