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

package/dist/cli.js

@@ -10,6 +10,7 @@
  */
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
+import { isLoopbackHost } from './auth.js';
 import { createWebHost } from './server.js';
 import { installService, uninstallService } from './install.js';
 import { createLogger } from './log.js';
@@ -93,11 +94,26 @@ export async function runCli(options = {}) {
         log.debug(`token ${host.token}`);
     }
     log.debug(`a client without a cookie can use ${host.url}?token=${host.token}`);
+    if (host.token !== undefined && host.issueCookie && !isLoopbackHost(parsed.host)) {
+        // D-41: the Docker image binds 0.0.0.0 and issues the cookie so that the UI works out of
+        // the box - which means whoever reaches the port is in. Said once, at start, with the ways
+        // out; the host cannot see a proxy or TLS in front of it, so it says this whenever it is
+        // in that position
+        log.warn(`the token cookie is handed to every browser that loads the page on ${parsed.host}: whoever reaches this port is in;` +
+            ' put a proxy with authentication and TLS in front, publish the port on the loopback only,' +
+            ' or set HMM_ISSUE_COOKIE=false and open the UI once with ?token=');
+    }
     if (parsed.authMode === 'rega') {
         // D-32: the token still works and `settings.cgi` still hands it out - the login is a second
         // 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,11 +163,19 @@ 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 }),
         ...(values.callbackXmlrpcPort === undefined ? {} : { callbackXmlrpcPort: values.callbackXmlrpcPort }),
         ...(values.callbackBinrpcPort === undefined ? {} : { callbackBinrpcPort: values.callbackBinrpcPort }),
+        ...(values.inContainer ? { inContainer: true } : {}),
+        ...(values.callbackXmlrpcDefaultPort === undefined
+            ? {}
+            : { callbackXmlrpcDefaultPort: values.callbackXmlrpcDefaultPort }),
+        ...(values.callbackBinrpcDefaultPort === undefined
+            ? {}
+            : { callbackBinrpcDefaultPort: values.callbackBinrpcDefaultPort }),
         idleUnsubscribeMs: values.idleUnsubscribeMs,
     });
 }

package/dist/occulite.d.ts

@@ -0,0 +1,86 @@
+/**
+ * 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. 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
+ * ```
+ *
+ * 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;
+/**
+ * B-94, D-65: the header openccu-lite's lighttpd gate sets on every request it lets through under
+ * `/addons/`, to the bare id of the session it found (from either session cookie or `?sid=`). The
+ * gate removes a copy the client sent first. A CCU has no gate and passes a client's header through,
+ * an older openccu-lite image does the same, and the backend's port is open to every process on the
+ * box - so the header is only a claim, and the box is asked about it like about any other session.
+ */
+export declare const OCCULITE_SESSION_HEADER = "x-occulite-session";
+export interface OcculiteCheckOptions {
+    /**
+     * The addon contract's validation (openccu-lite `docs/PORTING-PROMPT.md`): the session only
+     * counts when `GET /api/auth/v1/state` confirms it. The `?sid=` hand-over keeps the D-40 check,
+     * where that second answer only supplies the name.
+     */
+    readonly requireState?: boolean;
+}
+/** 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;
+    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, options?: OcculiteCheckOptions): Promise<OcculiteSession | undefined>;
+}
+//# sourceMappingURL=occulite.d.ts.map

package/dist/occulite.js

@@ -0,0 +1,140 @@
+/**
+ * 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. 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
+ * ```
+ *
+ * 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;
+/**
+ * B-94, D-65: the header openccu-lite's lighttpd gate sets on every request it lets through under
+ * `/addons/`, to the bare id of the session it found (from either session cookie or `?sid=`). The
+ * gate removes a copy the client sent first. A CCU has no gate and passes a client's header through,
+ * an older openccu-lite image does the same, and the backend's port is open to every process on the
+ * 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';
+/**
+ * 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 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 {
+    #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, options = {}) {
+        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);
+        if (who === undefined && options.requireState === true) {
+            this.#options.onNotice?.('warn', 'the box did not confirm the session of the X-Occulite-Session header');
+            return undefined;
+        }
+        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: {
@@ -135,6 +144,21 @@ export declare const OPTIONS: {
         readonly describe: "fixed port for the binrpc callback server; must differ from the xmlrpc one";
         readonly defaultDescription: "0, a free port";
     };
+    readonly 'callback-xmlrpc-default-port': {
+        readonly type: "number";
+        readonly describe: "xmlrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2031)";
+        readonly defaultDescription: "none, a free port";
+    };
+    readonly 'callback-binrpc-default-port': {
+        readonly type: "number";
+        readonly describe: "binrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2032)";
+        readonly defaultDescription: "none, a free port";
+    };
+    readonly 'in-container': {
+        readonly type: "boolean";
+        readonly describe: "we run in a container (the image sets it): the interface popup says to publish the callback ports unchanged";
+        readonly default: false;
+    };
     readonly 'idle-unsubscribe': {
         readonly type: "string";
         readonly describe: "drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)";
@@ -203,6 +227,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;
@@ -210,6 +236,11 @@ export interface WebOptions {
     readonly callbackIp: string | undefined;
     readonly callbackXmlrpcPort: number | undefined;
     readonly callbackBinrpcPort: number | undefined;
+    /** Task 35 (D-43): the CCU addon's fixed callback ports, taken while the configured ones are `0`. */
+    readonly callbackXmlrpcDefaultPort: number | undefined;
+    readonly callbackBinrpcDefaultPort: number | undefined;
+    /** Task 38: set by the image's `HMM_IN_CONTAINER`. */
+    readonly inContainer: boolean;
     readonly demo: boolean;
     /** D-31, in milliseconds; `0` disables the idle unsubscribe. */
     readonly idleUnsubscribeMs: number;

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: {
@@ -134,6 +144,21 @@ export const OPTIONS = {
         describe: 'fixed port for the binrpc callback server; must differ from the xmlrpc one',
         defaultDescription: '0, a free port',
     },
+    'callback-xmlrpc-default-port': {
+        type: 'number',
+        describe: 'xmlrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2031)',
+        defaultDescription: 'none, a free port',
+    },
+    'callback-binrpc-default-port': {
+        type: 'number',
+        describe: 'binrpc callback port while the configured one is 0; a free port when it is taken (the CCU addon sets 2032)',
+        defaultDescription: 'none, a free port',
+    },
+    'in-container': {
+        type: 'boolean',
+        describe: 'we run in a container (the image sets it): the interface popup says to publish the callback ports unchanged',
+        default: false,
+    },
     'idle-unsubscribe': {
         type: 'string',
         describe: 'drop the event subscriptions after this long with no page open (5m, 300s, 0 to disable)',
@@ -282,6 +307,20 @@ export function parseOptions(argv, env = process.env) {
         const value = raw[name] ?? OPTIONS[name].default;
         return value === undefined ? undefined : Number(value);
     };
+    const port = (name) => {
+        const value = number(name);
+        if (value !== undefined && !(Number.isInteger(value) && value >= 0 && value <= 65535)) {
+            throw new CliError(`--${name}: "${String(value)}" is not a port`);
+        }
+        return value;
+    };
+    const callbackXmlrpcDefaultPort = port('callback-xmlrpc-default-port');
+    const callbackBinrpcDefaultPort = port('callback-binrpc-default-port');
+    if (callbackXmlrpcDefaultPort !== undefined && callbackXmlrpcDefaultPort !== 0) {
+        if (callbackXmlrpcDefaultPort === callbackBinrpcDefaultPort) {
+            throw new CliError('--callback-xmlrpc-default-port and --callback-binrpc-default-port must differ');
+        }
+    }
     const logLevel = string('log-level');
     return {
         port: Number(raw['port'] ?? OPTIONS.port.default),
@@ -295,12 +334,16 @@ 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'),
         callbackIp: string('callback-ip'),
         callbackXmlrpcPort: number('callback-xmlrpc-port'),
         callbackBinrpcPort: number('callback-binrpc-port'),
+        callbackXmlrpcDefaultPort,
+        callbackBinrpcDefaultPort,
+        inContainer: boolean('in-container') ?? false,
         demo: boolean('demo'),
         idleUnsubscribeMs: parseDuration(string('idle-unsubscribe'), '--idle-unsubscribe'),
         logLevel: isLogLevel(logLevel) ? logLevel : 'info',

package/dist/server.d.ts

@@ -26,6 +26,7 @@ import type { SessionInfo } from '@homematic-manager/core';
 import { ApiWebSocketServer, Backend, type BackendOptions } from '@homematic-manager/backend';
 import { DeviceImageService } from './images.js';
 import { type Logger, type LogLevel } from './log.js';
+import { type OcculiteCheckOptions } from './occulite.js';
 import { SessionStore } from './sessions.js';
 /** The port the CLI binds by default - 8090, next to nothing else a Homematic user runs. */
 export declare const DEFAULT_PORT = 8090;
@@ -33,6 +34,12 @@ export declare const DEFAULT_PORT = 8090;
 export declare const DEFAULT_HOST = "127.0.0.1";
 /** How long `close()` waits for `backend.stop()` before it gives up and exits anyway. */
 export declare 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 declare const GATE_RECHECK_MS = 60000;
 /**
  * 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
@@ -46,8 +53,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 +68,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, options?: OcculiteCheckOptions): Promise<{
+        name: string;
+        level: number;
+        sid: string;
+    } | undefined>;
+}
 export interface WebHostOptions {
     readonly port?: number;
     readonly host?: string;
@@ -85,6 +106,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. */
@@ -92,14 +117,30 @@ export interface WebHostOptions {
     /** Written to `ConnectionConfig.local` - the addon's "we run on the CCU" mode. */
     readonly local?: boolean | undefined;
     /**
-     * Written to `ConnectionConfig.callback`. A host that cannot see the address the CCU reaches it
+     * Laid over `ConnectionConfig.callback`. A host that cannot see the address the CCU reaches it
      * on has to be told: a container on a bridge network sees `172.17.0.x`, and an `init` that
      * announces that address gets no events at all. With `--network host` none of this is needed.
+     *
+     * Task 38: these three are pinned, not written. They win over `config.json` for as long as the
+     * host runs with them, the settings dialog shows them read-only, and the file keeps what the
+     * user saved. An empty address and a port of `0` pin nothing.
      */
     readonly callbackIp?: string | undefined;
-    /** Fixed callback ports, so a container can publish them. `0` picks a free one. */
+    /** Fixed callback ports, so a container can publish them. `0` pins nothing. */
     readonly callbackXmlrpcPort?: number | undefined;
     readonly callbackBinrpcPort?: number | undefined;
+    /**
+     * Task 38: the host runs in a container (`HMM_IN_CONTAINER`, set by the image). The interface
+     * popup then says beside each callback URL that its port must be published unchanged.
+     */
+    readonly inContainer?: boolean | undefined;
+    /**
+     * Task 35 (D-43): the callback ports taken while the configuration says `0` - the CCU addon's
+     * fixed pair. Handed to the backend and never written to `config.json`, so a port the user set
+     * in the settings dialog always wins and no update of the addon can overwrite it.
+     */
+    readonly callbackXmlrpcDefaultPort?: number | undefined;
+    readonly callbackBinrpcDefaultPort?: number | undefined;
     /** How long `close()` waits for `backend.stop()`. */
     readonly shutdownTimeoutMs?: number;
     /** How often an idle api socket is pinged; `0` turns the heartbeat off. */
@@ -124,9 +165,11 @@ export interface WebHost {
     readonly base: string;
     /** `undefined` when auth is off. */
     readonly token: string | undefined;
+    /** Whether the page load hands the token to the browser as a cookie (D-41 says when to warn). */
+    readonly issueCookie: boolean;
     /** 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>;
 }