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

package/README.md

@@ -63,8 +63,9 @@ hard-coding it.
 | `--issue-cookie` | loopback binds only | hand the token to the browser on the page load |
 | `-a, --ccu` | - | CCU address; written to the configuration when it differs |
 | `--local` | - | we run on the CCU itself: talk to the interface processes directly |
-| `--callback-ip` | auto | address the interfaces call back to; needed where this host cannot see it (Docker) |
+| `--callback-ip` | auto | address the interfaces call back to; needed where this host cannot see it (Docker). Auto is this host's address in the CCU's network, else the one on the route to the CCU |
 | `--callback-xmlrpc-port`, `--callback-binrpc-port` | free ports | fixed callback ports, so a container can publish them |
+| `--callback-xmlrpc-default-port`, `--callback-binrpc-default-port` | - | callback ports while the configured ones are 0, a free port when one is taken (the CCU addon: 2031, 2032; never written to the configuration) |
 | `--demo` | off | serve the UI on its demo fixture and start no backend |
 | `--log-level` | `info` | `error`, `warn`, `info`, `debug` |
 | `--install` / `--uninstall` | - | systemd service; `--purge` also deletes the state |

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