signalk-ssl 0.2.3 → 0.3.0

package/README.md

@@ -55,6 +55,20 @@ The CA private key is always encrypted at rest with PBES2 / PBKDF2-SHA256 / AES-
 | `env`                   | Reads `SIGNALK_SSL_PASSPHRASE` from the environment at startup.      | Boxes where you set the env var via systemd / Compose.        |
 | `webapp`                | Prompts in the webapp on each restart.                               | High-security setups where the passphrase lives in your head. |
 
+### Changing the passphrase
+
+The **Change passphrase** panel on the status dashboard re-encrypts the CA
+private key under a new passphrase. The CA certificate itself is untouched, so
+every device that already trusts your CA keeps working and no restart is
+needed. Enter the current passphrase plus the new one; a wrong current
+passphrase is rejected without changing anything on disk.
+
+In `env` mode you must **also** update `SIGNALK_SSL_PASSPHRASE` to the new value
+(systemd unit / Compose file), or the next restart won't be able to decrypt the
+CA. In `convenience` mode the passphrase is machine-derived and not typeable, so
+this flow doesn't apply — to re-key a convenience-mode install, switch to `env`
+or `webapp` mode first.
+
 ## Mode of operation
 
 - **Generate** (default) — fresh CA on first run.
@@ -67,6 +81,7 @@ The CA private key is always encrypted at rest with PBES2 / PBKDF2-SHA256 / AES-
 - `POST /plugins/signalk-ssl/renew` — issue / renew leaf (admin auth required)
 - `POST /plugins/signalk-ssl/unlock` — supply passphrase (webapp mode, admin auth required)
 - `POST /plugins/signalk-ssl/lock` — drop in-memory passphrase
+- `POST /plugins/signalk-ssl/rotate` — re-encrypt the CA key under a new passphrase (admin auth required)
 - `GET /signalk/v1/api/ssl/ca.crt` — **public** download of CA cert (PEM)
 - `GET /signalk/v1/api/ssl/ca.mobileconfig` — **public** download of Apple profile
 
@@ -97,6 +112,15 @@ The renewal scheduler runs daily and re-issues whenever the configured SANs no l
 
 SignalK refuses to start with a TLS key that isn't `0600`. The plugin writes `0600` and re-chmods on every install. If you see this error, check that no other process has rewritten the file.
 
+### "Cannot write the CA / certificate files" (rootless Podman UID shift)
+
+The plugin probes write access to its data dir and the cert path at startup. Inside **rootless Podman**, a bind-mounted host directory can look present but reject child creation when the directory is owned by a UID that doesn't match the container's effective UID — the classic UID-shift symptom. When this happens the plugin logs a warning and shows a red banner on the status dashboard instead of silently failing on the first cert write.
+
+Fixes:
+
+- Run the container with `--userns=keep-id` (Podman) so in-container writes land as the host owner. On hosts where the SignalK user isn't UID 1000, use the explicit form `--userns=keep-id:uid=<in-image-uid>,gid=<in-image-gid>`.
+- Or `chown` the mounted directory to the UID the container process runs as.
+
 ### "I rotated the CA and now every phone is broken"
 
 That's the cost of rotating a CA. Every device needs to re-install the new root. The webapp's "Regenerate CA" button shows this consequence before it lets you proceed.

package/dist/plugin/api.js

@@ -36,6 +36,28 @@ export const registerAdminRoutes = (router, deps) => {
         deps.service.acknowledgeRestart();
         sendJson(res, 200, { kind: 'locked' });
     });
+    router.post('/rotate', asyncRoute(async (req, res) => {
+        const body = (req.body ?? {});
+        if (typeof body.oldPassphrase !== 'string' || body.oldPassphrase.length === 0) {
+            sendJson(res, 400, { error: 'oldPassphrase required' });
+            return;
+        }
+        if (typeof body.newPassphrase !== 'string' || body.newPassphrase.length === 0) {
+            sendJson(res, 400, { error: 'newPassphrase required' });
+            return;
+        }
+        const out = await deps.service.rotatePassphrase(body.oldPassphrase, body.newPassphrase);
+        // Map the outcome to a status: a wrong old passphrase is a client error,
+        // a missing CA is a 409 (nothing to rotate yet), an internal failure 500.
+        const status = out.kind === 'rotated'
+            ? 200
+            : out.kind === 'wrong-passphrase'
+                ? 403
+                : out.kind === 'no-ca'
+                    ? 409
+                    : 500;
+        sendJson(res, status, out);
+    }));
 };
 /** Mounted by the server at /signalk/v1/api/* via signalKApiRoutes — read-only public. */
 export const buildPublicRoutes = (router, deps) => {

package/dist/plugin/container-env.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Best-effort detection that we're running inside a container. None of these
+ * signals is authoritative on its own, but any one of them is a strong hint:
+ *   - `/.dockerenv` — Docker writes this into every container.
+ *   - `/run/.containerenv` — Podman's equivalent.
+ *   - `container` env var — set by systemd-nspawn and some Podman setups.
+ */
+export declare const detectContainer: (env?: NodeJS.ProcessEnv) => boolean;
+export interface PermissionProbe {
+    readonly dir: string;
+    readonly writable: boolean;
+    readonly error: string | null;
+}
+/**
+ * Verify the process can actually create + remove a file under `dir`. A bare
+ * `access(dir, W_OK)` is not enough on bind-mounted volumes where the dir
+ * looks writable but the effective UID can't create children (the classic
+ * rootless-Podman UID-shift symptom). So we write a real probe file.
+ */
+export declare const probeWritable: (dir: string) => Promise<PermissionProbe>;
+export interface PermissionCheckInput {
+    readonly dataDir: string;
+    readonly configPath: string;
+    readonly containerized?: boolean;
+}
+/**
+ * Run write probes against the two directories the plugin must write to and,
+ * if either fails while containerized, return an operator-facing warning that
+ * names the rootless-Podman UID-shift failure mode explicitly. Returns null
+ * when everything is writable.
+ */
+export declare const checkPermissions: (input: PermissionCheckInput) => Promise<string | null>;

package/dist/plugin/container-env.js

@@ -0,0 +1,62 @@
+import { access, constants, mkdir, rm, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Best-effort detection that we're running inside a container. None of these
+ * signals is authoritative on its own, but any one of them is a strong hint:
+ *   - `/.dockerenv` — Docker writes this into every container.
+ *   - `/run/.containerenv` — Podman's equivalent.
+ *   - `container` env var — set by systemd-nspawn and some Podman setups.
+ */
+export const detectContainer = (env = process.env) => {
+    return (existsSync('/.dockerenv') ||
+        existsSync('/run/.containerenv') ||
+        (env.container !== undefined && env.container !== ''));
+};
+/**
+ * Verify the process can actually create + remove a file under `dir`. A bare
+ * `access(dir, W_OK)` is not enough on bind-mounted volumes where the dir
+ * looks writable but the effective UID can't create children (the classic
+ * rootless-Podman UID-shift symptom). So we write a real probe file.
+ */
+export const probeWritable = async (dir) => {
+    const probe = join(dir, `.signalk-ssl-write-probe.${process.pid.toString()}`);
+    try {
+        await mkdir(dir, { recursive: true });
+        await access(dir, constants.W_OK);
+        // The access() check passes on some UID-shifted mounts that still reject
+        // child creation, so follow it with an actual create + remove.
+        await rm(probe, { force: true });
+        await writeFile(probe, '');
+        await rm(probe, { force: true });
+        return { dir, writable: true, error: null };
+    }
+    catch (e) {
+        return { dir, writable: false, error: e instanceof Error ? e.message : String(e) };
+    }
+};
+/**
+ * Run write probes against the two directories the plugin must write to and,
+ * if either fails while containerized, return an operator-facing warning that
+ * names the rootless-Podman UID-shift failure mode explicitly. Returns null
+ * when everything is writable.
+ */
+export const checkPermissions = async (input) => {
+    const containerized = input.containerized ?? detectContainer();
+    const probes = await Promise.all([probeWritable(input.dataDir), probeWritable(input.configPath)]);
+    const failed = probes.filter((p) => !p.writable);
+    if (failed.length === 0) {
+        return null;
+    }
+    const dirs = failed.map((p) => p.dir).join(', ');
+    if (containerized) {
+        return (`Cannot write to ${dirs}. This is the classic rootless-Podman UID-shift ` +
+            `symptom: the bind-mounted host directory is owned by a UID that doesn't ` +
+            `match the container's effective UID. Run the container with ` +
+            `--userns=keep-id (Podman) so in-container writes land as the host owner, ` +
+            `or chown the mounted directory to the container UID. Until this is fixed ` +
+            `the plugin can't persist the CA or install certificates.`);
+    }
+    return (`Cannot write to ${dirs}. Check directory ownership and permissions — the ` +
+        `plugin needs to write the CA state and install ssl-*.pem there.`);
+};

package/dist/plugin/index.js

@@ -42,6 +42,15 @@ const pluginConstructor = (app) => {
                 app.error(`${PLUGIN_ID} scheduled renewal failed: ${String(err)}`);
             };
             void store.init().then(async () => {
+                try {
+                    const warning = await svcLocal.checkWritePermissions();
+                    if (warning !== null) {
+                        app.error(`${PLUGIN_ID} permission warning: ${warning}`);
+                    }
+                }
+                catch (e) {
+                    app.error(`${PLUGIN_ID} permission probe failed: ${String(e)}`);
+                }
                 try {
                     const outcome = await svcLocal.issueIfNeeded();
                     app.debug(`${PLUGIN_ID} initial issueIfNeeded: ${JSON.stringify(outcome)}`);

package/dist/plugin/service.d.ts

@@ -17,6 +17,16 @@ export type IssueOutcome = {
     readonly kind: 'error';
     readonly message: string;
 };
+export type RotateOutcome = {
+    readonly kind: 'rotated';
+} | {
+    readonly kind: 'no-ca';
+} | {
+    readonly kind: 'wrong-passphrase';
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
 export interface ServiceStatus {
     readonly hasCa: boolean;
     readonly caFingerprint: string | null;
@@ -27,6 +37,7 @@ export interface ServiceStatus {
     readonly leafSansDns: readonly string[];
     readonly leafSansIp: readonly string[];
     readonly restartRequired: boolean;
+    readonly permissionWarning: string | null;
 }
 export interface SslServiceDeps {
     readonly store: CertStore;
@@ -37,10 +48,32 @@ export interface SslServiceDeps {
 export declare class SslService {
     private readonly deps;
     private restartRequired;
+    private permissionWarning;
     constructor(deps: SslServiceDeps);
+    /**
+     * Probe write access to the data dir and the cert install path. On a
+     * rootless-Podman UID-shift the bind-mounted host dir looks present but
+     * rejects child creation; this surfaces that as an operator-facing warning
+     * (logged at start, exposed via /status) rather than failing silently on
+     * the first cert write. Idempotent — safe to call on every start.
+     */
+    checkWritePermissions(): Promise<string | null>;
     targets(): InstallTargets;
     private resolveSans;
     issueIfNeeded(): Promise<IssueOutcome>;
+    /**
+     * Re-encrypt the CA private key under a new passphrase. The CA key is the
+     * only passphrase-protected artifact (leaf keys are written plaintext at
+     * 0o600 to the TLS path), so rotation is a single re-wrap: decrypt with the
+     * old passphrase, re-encrypt with the new one, write back atomically.
+     *
+     * `oldPassphrase` must match whatever the CA key is currently wrapped with
+     * — for `env`/`webapp` modes that's the operator's typed value; for
+     * `convenience` mode it's the machine-derived digest, which the caller
+     * can't type, so this route is only meaningful for env/webapp installs.
+     * We verify by attempting decryption and never touch disk on a mismatch.
+     */
+    rotatePassphrase(oldPassphrase: string, newPassphrase: string): Promise<RotateOutcome>;
     private bootstrapCa;
     private importCa;
     private signAndStoreLeaf;

package/dist/plugin/service.js

@@ -4,13 +4,29 @@ import { computeSpkiFingerprint, decryptPrivateKeyPkcs8, encryptPrivateKeyPkcs8,
 import { needsRenewal } from './needs-renewal.js';
 import { parseSans, sanitizeHostname } from './sans.js';
 import { defaultTargets, installCerts } from './cert-installer.js';
+import { checkPermissions } from './container-env.js';
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 export class SslService {
     deps;
     restartRequired = false;
+    permissionWarning = null;
     constructor(deps) {
         this.deps = deps;
     }
+    /**
+     * Probe write access to the data dir and the cert install path. On a
+     * rootless-Podman UID-shift the bind-mounted host dir looks present but
+     * rejects child creation; this surfaces that as an operator-facing warning
+     * (logged at start, exposed via /status) rather than failing silently on
+     * the first cert write. Idempotent — safe to call on every start.
+     */
+    async checkWritePermissions() {
+        this.permissionWarning = await checkPermissions({
+            dataDir: this.deps.store.dataDir,
+            configPath: this.deps.configPath
+        });
+        return this.permissionWarning;
+    }
     targets() {
         return defaultTargets(this.deps.configPath);
     }
@@ -49,6 +65,42 @@ export class SslService {
         this.restartRequired = true;
         return { kind: 'issued', reason: 'first-run' };
     }
+    /**
+     * Re-encrypt the CA private key under a new passphrase. The CA key is the
+     * only passphrase-protected artifact (leaf keys are written plaintext at
+     * 0o600 to the TLS path), so rotation is a single re-wrap: decrypt with the
+     * old passphrase, re-encrypt with the new one, write back atomically.
+     *
+     * `oldPassphrase` must match whatever the CA key is currently wrapped with
+     * — for `env`/`webapp` modes that's the operator's typed value; for
+     * `convenience` mode it's the machine-derived digest, which the caller
+     * can't type, so this route is only meaningful for env/webapp installs.
+     * We verify by attempting decryption and never touch disk on a mismatch.
+     */
+    async rotatePassphrase(oldPassphrase, newPassphrase) {
+        const caState = await this.deps.store.readCaState();
+        if (caState === null) {
+            return { kind: 'no-ca' };
+        }
+        let caPrivateKey;
+        try {
+            caPrivateKey = await decryptPrivateKeyPkcs8(caState.encryptedKeyPem, oldPassphrase);
+        }
+        catch {
+            return { kind: 'wrong-passphrase' };
+        }
+        try {
+            const reEncrypted = await encryptPrivateKeyPkcs8(caPrivateKey, newPassphrase);
+            await this.deps.store.writeCaState({ ...caState, encryptedKeyPem: reEncrypted });
+        }
+        catch (e) {
+            return { kind: 'error', message: e instanceof Error ? e.message : String(e) };
+        }
+        // The in-memory passphrase (webapp mode) must follow the re-wrap, or the
+        // next resolve() would still hand back the old value and fail to decrypt.
+        this.deps.passphrase.unlockWith(newPassphrase);
+        return { kind: 'rotated' };
+    }
     async bootstrapCa(passphrase) {
         if (this.deps.config.mode === 'import') {
             return this.importCa(passphrase);
@@ -129,7 +181,8 @@ export class SslService {
                 leafDaysRemaining: null,
                 leafSansDns: [],
                 leafSansIp: [],
-                restartRequired: this.restartRequired
+                restartRequired: this.restartRequired,
+                permissionWarning: this.permissionWarning
             };
         }
         const decision = needsRenewal(leafState.certificatePem, this.resolveSans(), this.deps.config.renewalThresholdDays);
@@ -142,7 +195,8 @@ export class SslService {
             leafDaysRemaining: Math.round(decision.daysUntilExpiry),
             leafSansDns: this.deps.config.sans.dnsNames.map((d) => sanitizeHostname(d).toLowerCase()),
             leafSansIp: this.deps.config.sans.ipAddresses,
-            restartRequired: this.restartRequired
+            restartRequired: this.restartRequired,
+            permissionWarning: this.permissionWarning
         };
     }
     acknowledgeRestart() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-ssl",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "SSL/TLS certificate management plugin for SignalK Node Server — generate a local CA, issue server certs, distribute the root via QR to phones/tablets",
   "type": "module",
   "main": "dist/plugin/index.js",