feat(auth): pin the ioBroker TLS certificate on first use

`allowSelfSigned` exists because ioBroker refuses passwords over plain HTTP, so
an authenticated instance is forced onto HTTPS and a home instance signs its own
certificate. But switching off CA validation removed the only proof of who the
server is: the tool would hand the stored password to anything answering on that
address. CodeQL flagged the symptom (js/disabling-certificate-validation on
socket.ts) — SECURITY.md already conceded the cause.

Identity now comes from a pinned SHA-256 fingerprint instead. It is recorded on
the first connection, verified on every one after that, and a change stops the
command *before* anything is sent. Interactively the user is asked; without a
TTY it fails and names `iob-sync trust`. This is what ssh does, including the
residual weakness: the very first connection is still trusted blindly.

Two layers, both needed. `probeCertificate` reads the certificate over a bare
TLS connection without sending an HTTP request, a cookie or a password, which is
what makes it possible to ask the user while the answer still matters. The
pinned https.Agent re-checks on every connection, because an attacker in the
path can relay the probe untouched and interfere only with the connection that
carries the credentials.

`rejectUnauthorized` is no longer assigned a literal `false` anywhere: it is
always `!allowSelfSigned`. The value is the user's decision, not a constant, and
writing it as one both misreports what the code does and is the shape CodeQL
matches on.

`certFingerprint` is optional, so every config written before this keeps
loading.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: mschmicking

AGENTS.md

@@ -190,9 +190,23 @@ enabled is also on HTTPS — usually with a self-signed certificate. `allowSelfS
 used to be honoured only on the websocket; the HTTP login path used global `fetch`,
 which cannot accept an untrusted certificate without an `undici` Agent, so login died
 at the handshake before sending anything. `client/auth.ts` therefore uses `node:https`
-directly rather than `fetch`. `test/fixtures/` holds a committed throwaway certificate
+directly rather than `fetch`. `test/fixtures/` holds a generated throwaway certificate
 so this path is tested against a real handshake.
 
+Because `allowSelfSigned` removes the only proof of who the server is, identity comes
+from a pinned SHA-256 fingerprint instead (`client/tls.ts`, `certFingerprint` in the
+config): recorded on first use, checked on every connection, and a mismatch stops the
+command **before** credentials are sent. Two layers, both needed — `probeCertificate`
+reads the certificate without sending anything, which is what makes it possible to ask
+the user at a point where the answer still matters; the pinned `https.Agent` re-checks
+on every connection, because an attacker can relay the probe untouched and interfere
+only with the connection carrying the password.
+
+`rejectUnauthorized` is never assigned a literal `false` anywhere in `src/`. It is
+always `!allowSelfSigned` — the value is the user's decision, not a constant, and
+writing it as one both misreports what the code does and trips CodeQL's
+`js/disabling-certificate-validation`.
+
 ### Two bugs the watch tests caught
 
 Both were live in working code, and both are the kind that only show up under a test

README.md

@@ -113,6 +113,7 @@ If `logs` shows nothing, that is usually the adapter's own log level rather than
 | `init`             | Write `.iobroker-sync.json`, verify the connection, create the script folder. Asks interactively when run without flags. `--types` also sets up TypeScript definitions. |
 | `types`            | Set up editor intellisense (`log`, `schedule`, ...). `--force`, `--offline`.                                                                                            |
 | `login` / `logout` | Save or remove the password for this instance. Never stored in the project.                                                                                             |
+| `trust`            | Accept the instance's current TLS certificate. Only needed after it changes. `--yes` skips the prompt.                                                                  |
 | `pull [pattern]`   | Download scripts to disk. Never deletes or overwrites local files.                                                                                                      |
 | `push [pattern]`   | Upload locally modified scripts. Never deletes remote objects.                                                                                                          |
 | `status`           | Show what changed, locally and remotely.                                                                                                                                |
@@ -189,8 +190,9 @@ test -z "$(iob-sync --json status | jq -rc 'select(.state != "in-sync")')"
 
 - **Verified against Admin 7.x only.** Older versions are likely to work — the legacy
   login path exists for them — but the wire protocol has not been checked against them.
-- **Self-signed certificates** are accepted only when `allowSelfSigned` is set, and any
-  certificate is accepted; there is no pinning.
+- **Self-signed certificates** are accepted only when `allowSelfSigned` is set. The
+  certificate is then pinned on first connection and verified on every one after that,
+  so a change is caught — but the first connection itself is trusted blindly.
 - **`Blockly` and `Rules` scripts** are pulled for completeness, but their sources are
   generated and editing them by hand is not supported.
 

SECURITY.md

@@ -38,6 +38,9 @@ If you are looking for somewhere to start:
 - **`src/sync/safe-path.ts`** — server-controlled ioBroker ids become local file paths.
   Guards against traversal, symlinked files and symlinked directories.
 - **`src/client/auth.ts`** — OAuth2 and legacy login, TLS handling.
+- **`src/client/tls.ts`** — certificate pinning. The check that replaces CA validation
+  when `allowSelfSigned` is on, and the thing standing between the stored password and
+  whatever is answering on that address.
 - **`src/commands/backup.ts`** — snapshots contain whatever secrets the live scripts do,
   and land under the gitignored `.iobroker-sync/`.
 
@@ -52,10 +55,14 @@ These are known trade-offs, documented so they need not be re-reported:
 - **There is no `--password` flag.** `argv` is readable by any local process via `ps` and
   is recorded in shell history. Use `--password-stdin`, `IOBROKER_PASSWORD`, the saved
   credential, or the interactive prompt.
-- **`allowSelfSigned` accepts any certificate.** It exists because ioBroker refuses
-  passwords over plain HTTP, so authenticated instances are HTTPS with a self-signed
-  certificate. There is no certificate pinning; on an untrusted network, that is a
-  meaningful limitation.
+- **`allowSelfSigned` turns off CA validation, and the first connection is trusted
+  blindly.** The flag exists because ioBroker refuses passwords over plain HTTP, so
+  authenticated instances are HTTPS with a self-signed certificate. Identity then comes
+  from the pinned fingerprint in `certFingerprint` instead (`src/client/tls.ts`):
+  recorded on first use, verified on every connection afterwards, and a change stops the
+  command before anything is sent. The residual weakness is the same one `ssh` has —
+  an attacker already in position for the _very first_ connection is trusted and pinned.
+  Verify the fingerprint out of band if that matters to you.
 - **`push` cannot disable a script or move it between javascript instances.** It sends
   only `common.source` and `common.engineType`, enforced by the type of
   `ObjectsApi.extendScript`. This is a safety property, not an oversight.
@@ -71,3 +78,5 @@ These are known trade-offs, documented so they need not be re-reported:
   `common.engineType`.
 - Anything that lets a malicious ioBroker server cause local code execution or
   arbitrary file writes.
+- Any way to reach the network with credentials that skips the fingerprint check in
+  `src/client/tls.ts`, or to make a mismatch continue rather than stop.

docs/AUTHENTICATION.md

@@ -63,6 +63,29 @@ Admin authenticates via OAuth2.
 Connect to the **admin adapter** port, usually 8081 — not the socket.io adapter port
 (8084), which lacks the permissions this tool needs.
 
-`allowSelfSigned` applies to both the HTTPS login and the websocket. It accepts any
-certificate; there is no way to pin a specific one. Without it, an untrusted certificate
-fails before any credential is sent, and the error names the setting that fixes it.
+`allowSelfSigned` applies to both the HTTPS login and the websocket. Without it, an
+untrusted certificate fails before any credential is sent, and the error names the
+setting that fixes it.
+
+### The certificate is pinned
+
+Switching off certificate validation would otherwise mean the tool sends your password
+to anything answering on that address. So the certificate is remembered instead:
+
+1. On the first connection its SHA-256 fingerprint is written to `certFingerprint` in
+   `.iobroker-sync.json` and reported once. Nothing to type, nothing to look up.
+2. Every connection after that must present the same certificate.
+3. If it changes, you are asked before anything is sent — and in a script or CI job,
+   where there is nobody to ask, the command fails instead.
+
+This is what `ssh` does with `known_hosts`, including the weak spot: the _first_
+connection is trusted blindly. On a network you do not trust, verify the fingerprint
+against the server before the first run.
+
+A certificate normally changes only because ioBroker was reinstalled or its certificate
+regenerated. To accept the new one:
+
+```bash
+iob-sync trust          # shows the fingerprint and asks
+iob-sync trust --yes    # no prompt, for unattended use
+```

docs/CONFIGURATION.md

@@ -24,16 +24,21 @@ somewhere else.
 
 ## `.iobroker-sync.json`
 
-| Field             | Meaning                                                            |
-| ----------------- | ------------------------------------------------------------------ |
-| `url`             | Admin base URL including scheme and port, e.g. `https://host:8081` |
-| `scriptRoot`      | Folder for synced scripts, relative to the project root            |
-| `allowSelfSigned` | Accept an untrusted TLS certificate                                |
-| `username`        | Admin username, or `null` when authentication is disabled          |
-| `defaultInstance` | javascript instance assigned to newly created scripts              |
+| Field             | Meaning                                                               |
+| ----------------- | --------------------------------------------------------------------- |
+| `url`             | Admin base URL including scheme and port, e.g. `https://host:8081`    |
+| `scriptRoot`      | Folder for synced scripts, relative to the project root               |
+| `allowSelfSigned` | Accept an untrusted TLS certificate                                   |
+| `certFingerprint` | Optional. SHA-256 of the certificate to expect; recorded on first use |
+| `username`        | Admin username, or `null` when authentication is disabled             |
+| `defaultInstance` | javascript instance assigned to newly created scripts                 |
 
 Commit this file — it holds no password. Credentials live outside the project entirely;
-see [AUTHENTICATION.md](AUTHENTICATION.md).
+see [AUTHENTICATION.md](AUTHENTICATION.md). A certificate fingerprint is public
+information, not a secret, so committing it is fine and makes the pin reviewable.
+
+`certFingerprint` is written for you the first time you connect to an `allowSelfSigned`
+instance; you never need to type it. Configs written before it existed keep working.
 
 ## `scriptRoot` cannot escape the project
 

docs/TROUBLESHOOTING.md

@@ -69,3 +69,15 @@ credential is sent.
 
 Also check you are on the **admin** adapter port (usually 8081), not the socket.io port
 (8084).
+
+## "The TLS certificate has changed"
+
+Commands stop before sending anything, and print the pinned fingerprint next to the one
+the server presented.
+
+If you reinstalled ioBroker or regenerated its certificate, this is expected — run
+`iob-sync trust` to accept the new one (`--yes` when unattended). If you did **not**
+change anything on the server, do not accept it: something is answering in its place.
+
+To start over from scratch, delete the `certFingerprint` line from
+`.iobroker-sync.json`; the next connection records whatever it finds.

src/cli.ts

@@ -15,6 +15,7 @@ import { loadConfig } from './config';
 import { AdminSocketClient } from './client/socket';
 import { AdminObjectsApi } from './client/objects';
 import { getAuthCookie } from './client/auth';
+import { ensureTrustedCertificate } from './client/tls';
 
 import { runInit } from './commands/init';
 import { pull } from './commands/pull';
@@ -32,6 +33,7 @@ import { rename } from './commands/rename';
 import { move } from './commands/move';
 import { remove } from './commands/remove';
 import { login, logout } from './commands/login';
+import { trust } from './commands/trust';
 import { setupTypes } from './commands/types';
 
 /**
@@ -124,7 +126,17 @@ async function withContext(
   const startDir = globals.cwd ? path.resolve(globals.cwd) : process.cwd();
   const { root, config } = await loadConfig(startDir);
 
-  const cookie = await getAuthCookie(config.url, config.username, config.allowSelfSigned, {
+  // Before anything is sent. `ensureTrustedCertificate` may update `config` in place
+  // (trust on first use, or an accepted certificate change), so it must run ahead of
+  // getAuthCookie — that is the call that carries the password.
+  await ensureTrustedCertificate(root, config, { log: logger });
+
+  const tlsConfig = {
+    allowSelfSigned: config.allowSelfSigned,
+    certFingerprint: config.certFingerprint,
+  };
+
+  const cookie = await getAuthCookie(config.url, config.username, tlsConfig, {
     passwordStdin: globals.passwordStdin,
     warn: (msg) => logger.warn(msg),
     info: (msg) => logger.info(msg),
@@ -133,7 +145,7 @@ async function withContext(
   const socket = new AdminSocketClient({
     url: config.url,
     cookie,
-    allowSelfSigned: config.allowSelfSigned,
+    ...tlsConfig,
   });
 
   await socket.connect();
@@ -242,7 +254,10 @@ program
   .action(function (this: Command) {
     return action(async () => {
       const startDir = resolveCwd();
-      const { config } = await loadConfig(startDir);
+      const { root, config } = await loadConfig(startDir);
+      // `login` does not go through withContext, so the certificate check has to
+      // happen here — before a password is collected, let alone sent.
+      await ensureTrustedCertificate(root, config, { log: logger });
       await login(config, { passwordStdin: globals().passwordStdin }, logger);
     })();
   });
@@ -265,6 +280,18 @@ program
     })();
   });
 
+program
+  .command('trust')
+  .description("record the instance's current TLS certificate as the expected one")
+  .option('-y, --yes', 'skip the confirmation prompt')
+  .action(function (this: Command) {
+    const opts = this.opts();
+    return action(async () => {
+      const { root, config } = await loadConfig(resolveCwd());
+      await trust(root, config, { yes: Boolean(opts.yes) }, logger);
+    })();
+  });
+
 program
   .command('logout')
   .description('remove the stored password for this instance')

src/client/auth.ts

@@ -12,6 +12,11 @@
  * usually also on HTTPS with a self-signed certificate — so honouring
  * `allowSelfSigned` here is not optional. The websocket path already honours it.
  *
+ * When a certificate is pinned, these requests go through the agent from
+ * `src/client/tls.ts`, which drops the connection before the request is written if
+ * the certificate is not the expected one. That check matters most here: this is the
+ * module that sends the password.
+ *
  * The password is never logged, never placed in argv, and never written to the
  * project config. See `src/credentials.ts`.
  */
@@ -22,6 +27,7 @@ import * as https from 'node:https';
 import { UserError } from '../types';
 import { readStoredPassword, saveStoredPassword } from '../credentials';
 import { isInteractive, promptPassword, promptYesNo, readPasswordFromStdin } from '../prompt';
+import { TlsConfig, createPinnedAgent, describePinFailure } from './tls';
 
 export interface AuthOptions {
   /** Read the password from stdin (`--password-stdin`) instead of env/store/prompt. */
@@ -57,7 +63,7 @@ function trimTrailingSlash(url: string): string {
  */
 function request(
   target: string,
-  opts: { method: string; body?: string; allowSelfSigned: boolean },
+  opts: { method: string; body?: string; tls: TlsConfig },
 ): Promise<HttpResponse> {
   return new Promise((resolve, reject) => {
     let parsed: URL;
@@ -85,7 +91,10 @@ function request(
             }
           : {},
         // Only meaningful for https; ignored otherwise.
-        rejectUnauthorized: !opts.allowSelfSigned,
+        rejectUnauthorized: !opts.tls.allowSelfSigned,
+        // Undefined unless a certificate is pinned, in which case this is what
+        // enforces it. Node falls back to its global agent when it is absent.
+        agent: createPinnedAgent(target, opts.tls),
       },
       (res) => {
         // The body is not needed for any of these endpoints, but it must be drained
@@ -157,18 +166,22 @@ async function resolvePassword(
 export async function getAuthCookie(
   url: string,
   username: string | null,
-  allowSelfSigned: boolean,
+  tlsConfig: TlsConfig,
   opts: AuthOptions = {},
 ): Promise<string | undefined> {
   const base = trimTrailingSlash(url);
 
   let loginProbe: HttpResponse;
   try {
-    loginProbe = await request(`${base}/login`, { method: 'GET', allowSelfSigned });
+    loginProbe = await request(`${base}/login`, { method: 'GET', tls: tlsConfig });
   } catch (err) {
+    // A pin mismatch is not a reachability problem and must not be reported as one.
+    const pinFailure = describePinFailure(err);
+    if (pinFailure) throw pinFailure;
+
     const message = (err as Error).message;
     const selfSignedHint =
-      /self.signed|unable to verify|CERT_/i.test(message) && !allowSelfSigned
+      /self.signed|unable to verify|CERT_/i.test(message) && !tlsConfig.allowSelfSigned
         ? 'The certificate is not trusted. Set "allowSelfSigned": true in .iobroker-sync.json.'
         : 'Check that the URL in your config is correct and the instance is reachable.';
     throw new UserError(`Could not reach ioBroker Admin at ${base}: ${message}`, selfSignedHint);
@@ -196,7 +209,7 @@ export async function getAuthCookie(
   try {
     const oauthRes = await request(`${base}/oauth/token`, {
       method: 'POST',
-      allowSelfSigned,
+      tls: tlsConfig,
       body: new URLSearchParams({
         grant_type: 'password',
         username: user,
@@ -213,24 +226,30 @@ export async function getAuthCookie(
         return cookie;
       }
     }
-  } catch {
-    // Fall through to legacy login below.
+  } catch (err) {
+    // Fall through to legacy login below — unless the certificate was wrong, which
+    // no amount of retrying on another endpoint will fix.
+    const pinFailure = describePinFailure(err);
+    if (pinFailure) throw pinFailure;
   }
 
   // Fall back to legacy session-cookie login.
   let legacyRes: HttpResponse;
   try {
     legacyRes = await request(`${base}/login`, {
       method: 'POST',
-      allowSelfSigned,
+      tls: tlsConfig,
       body: new URLSearchParams({
         username: user,
         password,
         stayloggedin: 'on',
       }).toString(),
     });
   } catch (err) {
-    throw new UserError(`Login request to ${base}/login failed: ${(err as Error).message}`);
+    throw (
+      describePinFailure(err) ??
+      new UserError(`Login request to ${base}/login failed: ${(err as Error).message}`)
+    );
   }
 
   const legacyCookie = extractCookie(legacyRes, 'connect.sid');

src/client/socket.ts

@@ -23,6 +23,7 @@ import {
   SocketOptions,
   UserError,
 } from '../types';
+import { createPinnedAgent, describePinFailure } from './tls';
 
 const READY_MESSAGE = '___ready___';
 const OBJECT_CHANGE = 'objectChange';
@@ -111,8 +112,18 @@ export class AdminSocketClient implements SocketClient {
     if (this.options.cookie) {
       wsOptions.headers = { Cookie: this.options.cookie };
     }
-    if (this.options.allowSelfSigned) {
-      wsOptions.rejectUnauthorized = false;
+    // Never a literal `false`: whether the certificate chain is checked is the user's
+    // `allowSelfSigned` decision, and writing it as a constant would claim otherwise.
+    // When validation is off, identity comes from the pinned fingerprint instead —
+    // the agent below drops the connection before the Cookie header is written if the
+    // certificate is not the expected one. See `src/client/tls.ts`.
+    wsOptions.rejectUnauthorized = !this.options.allowSelfSigned;
+    const agent = createPinnedAgent(this.options.url, {
+      allowSelfSigned: Boolean(this.options.allowSelfSigned),
+      certFingerprint: this.options.certFingerprint,
+    });
+    if (agent) {
+      wsOptions.agent = agent;
     }
 
     this.connectPromise = new Promise<void>((resolve, reject) => {
@@ -196,10 +207,11 @@ export class AdminSocketClient implements SocketClient {
           clearTimeout(connectTimer);
           this.connectPromise = null;
           reject(
-            new UserError(
-              `Could not connect to ioBroker Admin at ${this.options.url}: ${err.message}`,
-              'Check the URL/port and that the Admin instance is reachable.',
-            ),
+            describePinFailure(err) ??
+              new UserError(
+                `Could not connect to ioBroker Admin at ${this.options.url}: ${err.message}`,
+                'Check the URL/port and that the Admin instance is reachable.',
+              ),
           );
           return;
         }