homematic-manager 3.0.0-beta.0 → 3.0.0-beta.4

package/dist/cli.js

@@ -98,6 +98,12 @@ export async function runCli(options = {}) {
         // door, not a replacement, and saying so keeps the addon's two paths straight in the log
         log.info(`login: CCU credentials required (ReGa), sessions last ${String(Math.round(parsed.sessionTtlMs / 3_600_000))} h of inactivity; the token cookie of settings.cgi is still accepted`);
     }
+    if (parsed.authMode === 'occulite') {
+        // D-40: no form, no CCU users - the box decides who may in, and this host only checks that
+        // the session it was handed is one the box still knows
+        log.info(`login: the session openccu-lite hands over is checked against ${parsed.occuliteUrl ?? 'http://127.0.0.1'};` +
+            ' the token cookie of settings.cgi is still accepted');
+    }
     if (parsed.uiDevServer !== undefined) {
         log.info(`development mode: everything but the api is proxied to ${parsed.uiDevServer}`);
     }
@@ -147,6 +153,7 @@ function startHost(values, log, version) {
         ...(values.issueCookie === undefined ? {} : { issueCookie: values.issueCookie }),
         authMode: values.authMode,
         sessionTtlMs: values.sessionTtlMs,
+        ...(values.occuliteUrl === undefined ? {} : { occuliteUrl: values.occuliteUrl }),
         ...(values.ccu === undefined ? {} : { ccu: values.ccu }),
         ...(values.local === undefined ? {} : { local: values.local }),
         ...(values.callbackIp === undefined ? {} : { callbackIp: values.callbackIp }),

package/dist/occulite.d.ts

@@ -0,0 +1,59 @@
+/**
+ * D-40: the login of the addon when it runs on openccu-lite.
+ *
+ * The CCU case (D-32, task 18) is unchanged and untouched: a user name and a password, checked
+ * against ReGa's user list and the CCU's authentication daemon on UDP 1998, both loopback-only.
+ * openccu-lite has neither - there is no ReGaHSS, and its own users live in `occulited` - so the
+ * question is a different one, and so is the answer.
+ *
+ * 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:
+ *
+ * ```
+ * GET /api/meta/v1/enums   Authorization: Bearer <sid>   ->  200 valid, 401 not
+ * ```
+ *
+ * and nothing else is believed. The name of the user behind it comes from `/api/auth/v1/state`
+ * afterwards, best effort, only so that the UI can show who is logged in - a box that answers the
+ * first call and not the second still lets the session in.
+ *
+ * The metadata API and not the auth API for the decision, on purpose: it is the one openccu-lite
+ * declares normative (their D-16), it is the API this application depends on anyway, and a session
+ * that cannot read the metadata store is of no use to a device manager whatever else it can do.
+ */
+/** What the check answers with: who it is, in the shape the rest of the host already speaks. */
+export interface OcculiteSession {
+    readonly name: string;
+    /**
+     * ReGa's `UserLevel()`, so that `SessionInfo` keeps one meaning across the two boxes: 8 for an
+     * administrator, 2 for a user. openccu-lite has exactly those two roles.
+     */
+    readonly level: number;
+    /** The session id, which is also the credential every write to the box goes out with. */
+    readonly sid: string;
+}
+export interface OcculiteAuthOptions {
+    /** `http://127.0.0.1` on the box; a test points it at its own server. */
+    readonly baseUrl: string;
+    readonly timeoutMs?: number;
+    readonly fetch?: typeof globalThis.fetch;
+    readonly onNotice?: (level: 'info' | 'warn' | 'error', message: string) => void;
+}
+export declare const OCCULITE_TIMEOUT_MS = 5000;
+/** A session id as the shell hands it over, `@…@` and all, or `undefined` when it is not one. */
+export declare function parseSid(value: string | null | undefined): string | undefined;
+/** Checks a session id against the box that issued it. */
+export declare class OcculiteAuthenticator {
+    #private;
+    constructor(options: OcculiteAuthOptions);
+    get baseUrl(): string;
+    /**
+     * The session, or `undefined` - which is the answer for an unknown id, an expired one and a box
+     * that cannot be asked alike. A caller cannot tell them apart, and therefore cannot use this to
+     * find out whether a session exists.
+     */
+    check(rawSid: string | null | undefined): Promise<OcculiteSession | undefined>;
+}
+//# sourceMappingURL=occulite.d.ts.map

package/dist/occulite.js

@@ -0,0 +1,97 @@
+/**
+ * D-40: the login of the addon when it runs on openccu-lite.
+ *
+ * The CCU case (D-32, task 18) is unchanged and untouched: a user name and a password, checked
+ * against ReGa's user list and the CCU's authentication daemon on UDP 1998, both loopback-only.
+ * openccu-lite has neither - there is no ReGaHSS, and its own users live in `occulited` - so the
+ * question is a different one, and so is the answer.
+ *
+ * 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:
+ *
+ * ```
+ * GET /api/meta/v1/enums   Authorization: Bearer <sid>   ->  200 valid, 401 not
+ * ```
+ *
+ * and nothing else is believed. The name of the user behind it comes from `/api/auth/v1/state`
+ * afterwards, best effort, only so that the UI can show who is logged in - a box that answers the
+ * first call and not the second still lets the session in.
+ *
+ * The metadata API and not the auth API for the decision, on purpose: it is the one openccu-lite
+ * declares normative (their D-16), it is the API this application depends on anyway, and a session
+ * that cannot read the metadata store is of no use to a device manager whatever else it can do.
+ */
+export const OCCULITE_TIMEOUT_MS = 5000;
+/** A session id as the shell 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;
+}
+/** Checks a session id against the box that issued it. */
+export class OcculiteAuthenticator {
+    #options;
+    #fetch;
+    constructor(options) {
+        this.#options = options;
+        this.#fetch = options.fetch ?? globalThis.fetch;
+    }
+    get baseUrl() {
+        return this.#options.baseUrl.replace(/\/$/, '');
+    }
+    /**
+     * The session, or `undefined` - which is the answer for an unknown id, an expired one and a box
+     * that cannot be asked alike. A caller cannot tell them apart, and therefore cannot use this to
+     * find out whether a session exists.
+     */
+    async check(rawSid) {
+        const sid = parseSid(rawSid);
+        if (sid === undefined) {
+            return undefined;
+        }
+        try {
+            const response = await this.#fetch(`${this.baseUrl}/api/meta/v1/enums`, {
+                signal: AbortSignal.timeout(this.#options.timeoutMs ?? OCCULITE_TIMEOUT_MS),
+                headers: { Authorization: `Bearer ${sid}`, Accept: 'application/json' },
+            });
+            if (response.status === 401 || response.status === 403) {
+                return undefined;
+            }
+            if (!response.ok) {
+                this.#options.onNotice?.('warn', `the box answered ${String(response.status)} for a session check`);
+                return undefined;
+            }
+        }
+        catch (error) {
+            this.#options.onNotice?.('warn', `the box could not be asked about a session: ${String(error)}`);
+            return undefined;
+        }
+        const who = await this.#who(sid);
+        return { sid, name: who?.name ?? 'openccu-lite', level: who?.level ?? 2 };
+    }
+    /**
+     * Who the session belongs to. Best effort: the session is already valid at this point, and a
+     * name that could not be read costs a label in the header and nothing else.
+     */
+    async #who(sid) {
+        try {
+            const response = await this.#fetch(`${this.baseUrl}/api/auth/v1/state`, {
+                signal: AbortSignal.timeout(this.#options.timeoutMs ?? OCCULITE_TIMEOUT_MS),
+                headers: { Authorization: `Bearer ${sid}`, Accept: 'application/json' },
+            });
+            if (!response.ok) {
+                return undefined;
+            }
+            const body = (await response.json());
+            if (body.authenticated !== true || typeof body.user !== 'string') {
+                return undefined;
+            }
+            return { name: body.user, level: body.role === 'admin' ? 8 : 2 };
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+//# sourceMappingURL=occulite.js.map

package/dist/options.d.ts

@@ -19,11 +19,15 @@ export declare const ENV_PREFIX = "HMM";
  */
 export declare const DEFAULT_IDLE_UNSUBSCRIBE = "5m";
 /**
- * D-32: how a browser is let in. `token` is what every install type but the CCU addon uses, and
+ * D-32/D-40: how a browser is let in. `token` is what every install type but the CCU addon uses, and
  * stays the default there too - the addon's `settings.cgi` hand-over is the primary path and the
  * login is switched on by hand in `etc/hmm.env` or from the addon's settings page.
+ *
+ * `occulite` is the openccu-lite form of the same idea: no form of our own, the box's shell hands
+ * the session over on the URL and the host checks it against the box. The addon's `update_script`
+ * sets it by itself when it is installed on a box (`VARIANT=lite` in `/VERSION`).
  */
-export declare const AUTH_MODES: readonly ["token", "rega"];
+export declare const AUTH_MODES: readonly ["token", "rega", "occulite"];
 /** D-32: a login lasts a day of not being used. Sliding, so a tab in use never expires. */
 export declare const DEFAULT_SESSION_TTL = "24h";
 /**
@@ -34,7 +38,7 @@ export declare const DEFAULT_SESSION_TTL = "24h";
  * rather than a silently disabled feature.
  */
 export declare function parseDuration(value: string, option: string): number;
-/** Is this one of the two modes? `parseRaw` has already refused everything else. */
+/** Is this one of the three modes? `parseRaw` has already refused everything else. */
 export declare function isAuthMode(value: string | undefined): value is AuthMode;
 export type OptionType = 'string' | 'number' | 'boolean';
 export interface OptionDefinition {
@@ -102,13 +106,18 @@ export declare const OPTIONS: {
     };
     readonly 'auth-mode': {
         readonly type: "string";
-        readonly describe: "token: the token guards the api. rega: ask for a CCU login first (addon only, needs --local)";
-        readonly choices: readonly ["token", "rega"];
+        readonly describe: string;
+        readonly choices: readonly ["token", "rega", "occulite"];
         readonly default: "token";
     };
+    readonly 'occulite-url': {
+        readonly type: "string";
+        readonly describe: "with --auth-mode occulite: the box that issued the session";
+        readonly defaultDescription: "http://127.0.0.1";
+    };
     readonly 'session-ttl': {
         readonly type: "string";
-        readonly describe: "with --auth-mode rega: how long a login lasts without being used (24h, 90m, ...)";
+        readonly describe: "with --auth-mode rega or occulite: how long a login lasts without being used (24h, 90m, ...)";
         readonly default: "24h";
     };
     readonly ccu: {
@@ -203,6 +212,8 @@ export interface WebOptions {
     readonly issueCookie: boolean | undefined;
     /** D-32: `token` or `rega`. */
     readonly authMode: AuthMode;
+    /** D-40: the box `--auth-mode occulite` checks a handed-over session against. */
+    readonly occuliteUrl: string | undefined;
     /** D-32, in milliseconds. */
     readonly sessionTtlMs: number;
     readonly ccu: string | undefined;

package/dist/options.js

@@ -20,11 +20,15 @@ export const ENV_PREFIX = 'HMM';
  */
 export const DEFAULT_IDLE_UNSUBSCRIBE = '5m';
 /**
- * D-32: how a browser is let in. `token` is what every install type but the CCU addon uses, and
+ * D-32/D-40: how a browser is let in. `token` is what every install type but the CCU addon uses, and
  * stays the default there too - the addon's `settings.cgi` hand-over is the primary path and the
  * login is switched on by hand in `etc/hmm.env` or from the addon's settings page.
+ *
+ * `occulite` is the openccu-lite form of the same idea: no form of our own, the box's shell hands
+ * the session over on the URL and the host checks it against the box. The addon's `update_script`
+ * sets it by itself when it is installed on a box (`VARIANT=lite` in `/VERSION`).
  */
-export const AUTH_MODES = ['token', 'rega'];
+export const AUTH_MODES = ['token', 'rega', 'occulite'];
 /** D-32: a login lasts a day of not being used. Sliding, so a tab in use never expires. */
 export const DEFAULT_SESSION_TTL = '24h';
 /**
@@ -43,9 +47,9 @@ export function parseDuration(value, option) {
     const factor = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 }[match[2] ?? 's'] ?? 1000;
     return amount * factor;
 }
-/** Is this one of the two modes? `parseRaw` has already refused everything else. */
+/** Is this one of the three modes? `parseRaw` has already refused everything else. */
 export function isAuthMode(value) {
-    return value === 'token' || value === 'rega';
+    return value === 'token' || value === 'rega' || value === 'occulite';
 }
 export const OPTIONS = {
     port: {
@@ -101,13 +105,19 @@ export const OPTIONS = {
     },
     'auth-mode': {
         type: 'string',
-        describe: 'token: the token guards the api. rega: ask for a CCU login first (addon only, needs --local)',
+        describe: 'token: the token guards the api. rega: ask for a CCU login first (addon only, needs --local). ' +
+            'occulite: take the session openccu-lite hands over',
         choices: AUTH_MODES,
         default: 'token',
     },
+    'occulite-url': {
+        type: 'string',
+        describe: 'with --auth-mode occulite: the box that issued the session',
+        defaultDescription: 'http://127.0.0.1',
+    },
     'session-ttl': {
         type: 'string',
-        describe: 'with --auth-mode rega: how long a login lasts without being used (24h, 90m, ...)',
+        describe: 'with --auth-mode rega or occulite: how long a login lasts without being used (24h, 90m, ...)',
         default: DEFAULT_SESSION_TTL,
     },
     ccu: {
@@ -295,6 +305,7 @@ export function parseOptions(argv, env = process.env) {
         auth: boolean('auth'),
         issueCookie: boolean('issue-cookie'),
         authMode: isAuthMode(string('auth-mode')) ? string('auth-mode') : 'token',
+        occuliteUrl: string('occulite-url'),
         sessionTtlMs: parseDuration(string('session-ttl'), '--session-ttl'),
         ccu: string('ccu'),
         local: boolean('local'),

package/dist/server.d.ts

@@ -46,8 +46,14 @@ export declare const KEEPALIVE_INTERVAL_MS = 25000;
  * command line, the environment or the addon's session-checked `settings.cgi`. `rega` puts a login
  * page in front of the UI and checks the credentials against the CCU itself - which only works
  * *on* the CCU, because both services it asks are loopback-only.
+ *
+ * D-40 adds `occulite`, for the addon on an openccu-lite box. There is no login page in that mode:
+ * the box's shell has already authenticated the user and opens the addon with the session on the
+ * URL (`?sid=@xxxxxxxxxx@`), and the host checks that session against the box's metadata API. A
+ * request without one is sent to the box's own login rather than shown a form this application
+ * could not answer - openccu-lite's users are the box's, not the CCU's.
  */
-export type AuthMode = 'token' | 'rega';
+export type AuthMode = 'token' | 'rega' | 'occulite';
 /** What the login endpoint asks. `RegaAuthenticator` is the real one; a test passes a fake. */
 export interface CredentialChecker {
     authenticate(user: string, password: string): Promise<{
@@ -55,6 +61,14 @@ export interface CredentialChecker {
         level: number;
     } | undefined>;
 }
+/** D-40: what the `occulite` hand-over asks. `OcculiteAuthenticator` is the real one. */
+export interface SessionChecker {
+    check(sid: string | null | undefined): Promise<{
+        name: string;
+        level: number;
+        sid: string;
+    } | undefined>;
+}
 export interface WebHostOptions {
     readonly port?: number;
     readonly host?: string;
@@ -85,6 +99,10 @@ export interface WebHostOptions {
     readonly sessionTtlMs?: number | undefined;
     /** D-32: injected by the tests in place of the real ReGa and UDP check. */
     readonly authenticator?: CredentialChecker | undefined;
+    /** D-40: the box the `occulite` mode checks sessions against. `http://127.0.0.1` by default. */
+    readonly occuliteUrl?: string | undefined;
+    /** D-40: injected by the tests in place of the real box. */
+    readonly sessionChecker?: SessionChecker | undefined;
     /** Serve the UI in demo mode and start no backend at all. */
     readonly demo?: boolean;
     /** Written to `ConnectionConfig.host` when it differs from what is configured. */
@@ -126,7 +144,7 @@ export interface WebHost {
     readonly token: string | undefined;
     /** D-32: how a browser is let in. */
     readonly authMode: AuthMode;
-    /** D-32: the login sessions; `undefined` in `token` mode, where there are none. */
+    /** D-32/D-40: the login sessions; `undefined` in `token` mode, where there are none. */
     readonly sessions: SessionStore | undefined;
     close(): Promise<void>;
 }

package/dist/server.js

@@ -29,6 +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 { OcculiteAuthenticator, parseSid } from './occulite.js';
 import { defaultDataDir, defaultMetadataDir, defaultUiDir, packageVersion } from './paths.js';
 import { proxyRequest, proxyUpgrade } from './proxy.js';
 import { RateLimiter, SessionStore } from './sessions.js';
@@ -77,8 +78,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,6 +87,15 @@ 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) {
@@ -146,6 +156,17 @@ 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 = url.searchParams.get('sid');
+            if (parseSid(offered) !== undefined) {
+                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 +189,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 +199,27 @@ export async function createWebHost(options = {}) {
                 return;
             }
             session = sessions.get(readCookie(request.headers.cookie, SESSION_COOKIE));
+            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 +314,37 @@ 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 store = sessions;
+        const session = store.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
+        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)),
+            'Cache-Control': 'no-store',
+        });
+        response.end();
+    }
     /** 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;
@@ -416,6 +484,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;
     }

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/node_modules/@homematic-manager/backend/dist/api/backend.d.ts

@@ -17,6 +17,7 @@ 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';
 /** How often the BidCos service messages are polled while the connection is up. */
@@ -48,6 +49,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 +85,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. */