signalk-ssl 0.0.1 → 0.1.6

package/README.md

@@ -1,22 +1,111 @@
 # signalk-ssl
 
-SSL/TLS certificate management plugin for [SignalK Node Server](https://signalk.org/).
+SSL/TLS certificate management for [SignalK Node Server](https://signalk.org/).
 
-**Status:** skeleton — name reserved on npm, implementation pending.
+Generates a local Certificate Authority, signs server certificates for your boat's hostnames and IP addresses, and provides a QR code so phones and tablets can install the CA root without SSH.
 
-## Planned scope
+## Why
 
-Manage SSL/TLS certificates for the SignalK server from inside the server:
+- Marina Wi-Fi has no public DNS name, so Let's Encrypt is out.
+- Self-signed certs without a CA make every browser scream.
+- Doing it by hand means SSH, `openssl`, and `update-ca-certificates` per device — for non-technical boaters that's not happening.
 
-- Generate and install self-signed certificates
-- Let's Encrypt / ACME certificate provisioning and renewal
-- Bring-your-own-cert (BYOC) install and rotation
-- Expiry monitoring and pre-expiry alerts
-- Trust chain / CA bundle management
+`signalk-ssl` collapses the whole flow into "open plugin → configure SANs → scan QR on each phone".
+
+## Prerequisites
+
+- Node.js ≥ 22.5.0 (matches the `engines.node` floor in `package.json`)
+- SignalK Node Server ≥ 2.0 (uses the `@signalk/server-api` v2 plugin contract)
 
 ## Install
 
-Not ready for use. Once published with real functionality, install via the SignalK Appstore as `signalk-ssl`.
+In the SignalK admin UI: **Appstore → Available → signalk-ssl → Install**.
+
+The Appstore installs plugins with `npm install --ignore-scripts`, so this package ships with `dist/` and `public/` pre-built. No build step runs on your server.
+
+## Configure
+
+1. Enable the plugin in the SignalK admin UI.
+2. Open the plugin configuration screen and fill in:
+   - **SANs** — at least one DNS name (e.g. `signalk.local`, `boat.local`) and/or the boat's LAN IP. The webapp shows the discovered IPv4 addresses.
+   - **Passphrase mode** — `convenience` is the default and just works.
+   - Defaults for CA validity (10 years), leaf validity (397 days), renewal threshold (30 days), clock-skew backdate (24 hours) are fine for most boats.
+3. Save the config. The plugin generates the CA, signs a leaf certificate, and writes both to SignalK's TLS path (`ssl-cert.pem`, `ssl-key.pem`, `ssl-chain.pem` in the configured config directory).
+4. Open the plugin webapp at `/plugins/signalk-ssl/`.
+5. Restart SignalK so the new certificate is picked up by the HTTPS listener. (The webapp shows a banner reminding you.)
+
+## Distribute the CA to phones
+
+In the webapp, the **Install on your devices** panel shows a QR code. The target URL is auto-selected by user-agent:
+
+- iPhone / iPad → `.mobileconfig` profile (installs as a configuration profile; user enables full trust in Settings)
+- Android / desktop → plain `.crt` with `application/x-x509-ca-cert` MIME
+
+Scan with the device's camera, follow the OS prompts. The webapp includes step-by-step instructions for each platform.
+
+Verify out-of-band by comparing the SHA-256 fingerprint shown on the boat against the one displayed on the device after install.
+
+## Passphrase modes
+
+The CA private key is always encrypted at rest with PBES2 / PBKDF2-SHA256 / AES-256-CBC PKCS#8.
+
+| Mode                    | What it does                                                         | When to use                                                   |
+| ----------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `convenience` (default) | Derives the wrapping key from this host's identity. Nothing to type. | Single-purpose SignalK boxes where physical access ≈ root.    |
+| `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. |
+
+## Mode of operation
+
+- **Generate** (default) — fresh CA on first run.
+- **Import** — load an existing CA cert + encrypted key from configured paths. Useful if you're moving from Keeper / the SignalK Universal Installer, or running multiple SignalK servers behind one CA.
+
+## Routes
+
+- `GET /plugins/signalk-ssl/` — webapp (admin auth required)
+- `GET /plugins/signalk-ssl/status` — JSON status (admin auth required)
+- `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
+- `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
+
+The two `/ssl/` paths are intentionally unauthenticated so phones without SignalK accounts can fetch the CA via the QR-coded URL. (`PUT`/`POST` on `/signalk/v1/api/*` is auto-protected by the server, so we can't accidentally expose a destructive endpoint here.)
+
+## Container (Podman / Docker) notes
+
+- The plugin uses `app.getDataDirPath()`, which means the per-plugin data lives under SignalK's data volume — survives container rebuilds.
+- Certs land at `${app.config.configPath}/ssl-{cert,key,chain}.pem`, again on the data volume.
+- mDNS `.local` resolution does **not** work through Podman's default bridge network. Either run with `--network=host` or use IP-based SANs and DNS on your router. The webapp can show the LAN IP URL as a fallback when it detects this case.
+- For outbound trust **inside** the container (so the SignalK Node process trusts its own CA when calling itself or another boat service), set `NODE_EXTRA_CA_CERTS=/path/to/ca.crt` in the container env. Node reads this before plugins load, so the plugin can't set it on itself — the value must be in your Quadlet/Compose/run script.
+
+## Troubleshooting
+
+### "iOS Safari says the certificate is invalid"
+
+Three usual causes:
+
+1. The leaf cert doesn't list the hostname in the SAN. Check the SANs in the plugin config; re-issue if you added one after the fact.
+2. The phone's clock is more than 24 hours behind. This plugin backdates `notBefore` by 24h to soften this; if it's still too far off, fix NTP on the boat.
+3. The CA root isn't installed (or full trust isn't enabled in Settings → General → About → Certificate Trust Settings).
+
+### "I changed the LAN IP and now nothing works"
+
+The renewal scheduler runs daily and re-issues whenever the configured SANs no longer cover the leaf cert. To force an immediate refresh, click **Renew now** in the webapp.
+
+### "Permission denied" on the cert key
+
+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.
+
+### "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.
+
+## Out of scope
+
+- ACME / Let's Encrypt (would live in a separate `signalk-acme` plugin)
+- Revocation lists / OCSP
+- Multi-CA / multi-tenant
 
 ## License
 

package/dist/plugin/api.d.ts

@@ -0,0 +1,15 @@
+import type { IRouter } from 'express';
+import type { SslService } from './service.js';
+import type { SignalkSslConfig } from './schema.js';
+import type { PassphraseSource } from './passphrase-source.js';
+import type { CertStore } from './storage.js';
+export interface ApiDeps {
+    readonly service: SslService;
+    readonly store: CertStore;
+    readonly passphrase: PassphraseSource;
+    readonly config: SignalkSslConfig;
+}
+/** Mounted by the server at /plugins/signalk-ssl/* — admin auth applied. */
+export declare const registerAdminRoutes: (router: IRouter, deps: ApiDeps) => void;
+/** Mounted by the server at /signalk/v1/api/* via signalKApiRoutes — read-only public. */
+export declare const buildPublicRoutes: (router: IRouter, deps: ApiDeps) => IRouter;

package/dist/plugin/api.js

@@ -0,0 +1,63 @@
+import { buildMobileconfig } from './mobileconfig.js';
+import { discoverLocalIps } from './service.js';
+const sendJson = (res, status, body) => {
+    res.status(status).type('application/json').send(JSON.stringify(body));
+};
+const asyncRoute = (fn) => (req, res, next) => {
+    fn(req, res).catch((err) => {
+        next(err);
+    });
+};
+/** Mounted by the server at /plugins/signalk-ssl/* — admin auth applied. */
+export const registerAdminRoutes = (router, deps) => {
+    router.get('/status', asyncRoute(async (_req, res) => {
+        const s = await deps.service.status();
+        sendJson(res, 200, s);
+    }));
+    router.get('/api/local-ips', (_req, res) => {
+        sendJson(res, 200, { ipAddresses: discoverLocalIps() });
+    });
+    router.post('/renew', asyncRoute(async (_req, res) => {
+        const out = await deps.service.issueIfNeeded();
+        sendJson(res, 200, out);
+    }));
+    router.post('/unlock', asyncRoute(async (req, res) => {
+        const body = (req.body ?? {});
+        if (typeof body.passphrase !== 'string' || body.passphrase.length === 0) {
+            sendJson(res, 400, { error: 'passphrase required' });
+            return;
+        }
+        deps.passphrase.unlockWith(body.passphrase);
+        const out = await deps.service.issueIfNeeded();
+        sendJson(res, 200, out);
+    }));
+    router.post('/lock', (_req, res) => {
+        deps.passphrase.lock();
+        deps.service.acknowledgeRestart();
+        sendJson(res, 200, { kind: 'locked' });
+    });
+};
+/** Mounted by the server at /signalk/v1/api/* via signalKApiRoutes — read-only public. */
+export const buildPublicRoutes = (router, deps) => {
+    router.get('/ssl/ca.crt', asyncRoute(async (_req, res) => {
+        const ca = await deps.store.readCaState();
+        if (ca === null) {
+            sendJson(res, 404, { error: 'no CA configured' });
+            return;
+        }
+        res.type('application/x-x509-ca-cert').send(ca.certificatePem);
+    }));
+    router.get('/ssl/ca.mobileconfig', asyncRoute(async (_req, res) => {
+        const ca = await deps.store.readCaState();
+        if (ca === null) {
+            sendJson(res, 404, { error: 'no CA configured' });
+            return;
+        }
+        const xml = buildMobileconfig(ca.certificatePem, {
+            caName: deps.config.commonName,
+            organization: deps.config.organization
+        });
+        res.type('application/x-apple-aspen-config').send(xml);
+    }));
+    return router;
+};

package/dist/plugin/cert-installer.d.ts

@@ -0,0 +1,13 @@
+export interface InstallTargets {
+    readonly certPath: string;
+    readonly keyPath: string;
+    readonly chainPath: string;
+}
+export declare const defaultTargets: (configPath: string) => InstallTargets;
+/**
+ * Atomically install the leaf certificate, key, and chain into the paths
+ * signalk-server reads at boot (`${configPath}/ssl-cert.pem`,
+ * `ssl-key.pem`, `ssl-chain.pem`). signalk-server enforces strict perms on
+ * the key file (refuses to start if it's group/world-readable).
+ */
+export declare const installCerts: (targets: InstallTargets, leafPem: string, leafKeyPem: string, caPem: string) => Promise<void>;

package/dist/plugin/cert-installer.js

@@ -0,0 +1,41 @@
+import { chmod, mkdir, rename, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+const PEM_KEY_MODE = 0o600;
+const PEM_CERT_MODE = 0o644;
+export const defaultTargets = (configPath) => ({
+    certPath: join(configPath, 'ssl-cert.pem'),
+    keyPath: join(configPath, 'ssl-key.pem'),
+    chainPath: join(configPath, 'ssl-chain.pem')
+});
+const atomicWrite = async (path, data, mode, pid = process.pid) => {
+    const tmp = `${path}.${pid.toString()}.${Date.now().toString()}.tmp`;
+    await writeFile(tmp, data, { mode });
+    await rename(tmp, path);
+    // rename preserves mode on Linux; chmod is belt-and-braces for filesystems
+    // where the inherited umask might widen it (some mounted volumes do).
+    await chmod(path, mode);
+};
+/**
+ * Atomically install the leaf certificate, key, and chain into the paths
+ * signalk-server reads at boot (`${configPath}/ssl-cert.pem`,
+ * `ssl-key.pem`, `ssl-chain.pem`). signalk-server enforces strict perms on
+ * the key file (refuses to start if it's group/world-readable).
+ */
+export const installCerts = async (targets, leafPem, leafKeyPem, caPem) => {
+    // mkdir every distinct parent directory. defaultTargets() puts all three
+    // files under the same configPath, but the InstallTargets contract doesn't
+    // require that, and a caller picking custom paths would otherwise ENOENT.
+    const parents = new Set([
+        dirname(targets.certPath),
+        dirname(targets.keyPath),
+        dirname(targets.chainPath)
+    ]);
+    await Promise.all([...parents].map((d) => mkdir(d, { recursive: true })));
+    await atomicWrite(targets.keyPath, leafKeyPem, PEM_KEY_MODE);
+    await atomicWrite(targets.certPath, leafPem, PEM_CERT_MODE);
+    // Chain file = leaf + CA, separated by newline. Caddy/Go's tls.X509KeyPair
+    // expects the leaf first; Node's https.createServer doesn't strictly need
+    // a chain file but signalk-server's interface exposes one, so we write it.
+    const chain = `${leafPem.trimEnd()}\n${caPem.trimEnd()}\n`;
+    await atomicWrite(targets.chainPath, chain, PEM_CERT_MODE);
+};

package/dist/plugin/crypto.d.ts

@@ -0,0 +1,15 @@
+import type { FingerprintAlgorithm, GenerateCaInput, GeneratedCa, SignLeafInput, SignedLeaf } from './types.js';
+export declare const generateKeyPair: () => Promise<CryptoKeyPair>;
+export declare const generateCa: (input: GenerateCaInput) => Promise<GeneratedCa>;
+export declare const signLeaf: (input: SignLeafInput) => Promise<SignedLeaf>;
+/**
+ * Encrypt a CryptoKey as PBES2 / PBKDF2-SHA256 / AES-256-CBC PKCS#8 PEM.
+ * (Node's openssl bindings don't expose AES-GCM as a PBES2 cipher; AES-256-CBC
+ * is the strongest cipher Node will emit and is what `openssl pkcs8 -topk8`
+ * produces by default for `-v2 aes-256-cbc`.)
+ */
+export declare const encryptPrivateKeyPkcs8: (key: CryptoKey, passphrase: string) => Promise<string>;
+export declare const decryptPrivateKeyPkcs8: (pem: string, passphrase: string) => Promise<CryptoKey>;
+export declare const derivePassphraseKey: (passphrase: string, salt: Uint8Array, iterations?: number) => Promise<CryptoKey>;
+export declare const computeSpkiFingerprint: (certificatePem: string, algorithm: FingerprintAlgorithm) => Promise<string>;
+export declare const verifyChain: (leafPem: string, caPem: string, atDate?: Date) => Promise<boolean>;

package/dist/plugin/crypto.js

@@ -0,0 +1,163 @@
+import { createPrivateKey, randomBytes, webcrypto } from 'node:crypto';
+import { AuthorityKeyIdentifierExtension, BasicConstraintsExtension, cryptoProvider, ExtendedKeyUsage, ExtendedKeyUsageExtension, KeyUsageFlags, KeyUsagesExtension, SubjectAlternativeNameExtension, SubjectKeyIdentifierExtension, X509Certificate, X509CertificateGenerator } from '@peculiar/x509';
+// Build the DN as a structured JsonName so @peculiar/x509 handles RFC 4514
+// escaping internally. Hand-rolled `CN=${name}, O=${org}` interpolation
+// would break on common names containing comma, equals, plus, backslash, etc.
+const dn = (commonName, organization) => [
+    { CN: [commonName] },
+    { O: [organization] }
+];
+// Node's `webcrypto.Crypto` and the WebWorker lib's global `Crypto` diverge on
+// the Ed25519 overload; the runtime objects are identical but the structural
+// types aren't compatible. @peculiar/x509 v1 only declares the global type.
+cryptoProvider.set(webcrypto);
+const EC_ALGORITHM = {
+    name: 'ECDSA',
+    namedCurve: 'P-256',
+    hash: 'SHA-256'
+};
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const MS_PER_HOUR = 60 * 60 * 1000;
+const PBKDF2_DEFAULT_ITERATIONS = 600_000;
+const generateSerialNumber = () => {
+    const bytes = randomBytes(16);
+    // Clear leading bit so DER encoding stays positive (an unsigned integer in
+    // X.509 must not start with 0x80+; setting bit 7 of byte 0 to 0 enforces it).
+    const firstByte = bytes[0] ?? 0;
+    bytes[0] = firstByte & 0x7f;
+    return bytes.toString('hex');
+};
+export const generateKeyPair = async () => {
+    return webcrypto.subtle.generateKey(EC_ALGORITHM, true, ['sign', 'verify']);
+};
+export const generateCa = async (input) => {
+    const keys = await generateKeyPair();
+    const notBefore = new Date();
+    const notAfter = new Date(notBefore.getTime() + input.validityDays * MS_PER_DAY);
+    const distinguishedName = dn(input.commonName, input.organization);
+    const cert = await X509CertificateGenerator.create({
+        serialNumber: generateSerialNumber(),
+        subject: distinguishedName,
+        issuer: distinguishedName,
+        notBefore,
+        notAfter,
+        publicKey: keys.publicKey,
+        signingKey: keys.privateKey,
+        signingAlgorithm: EC_ALGORITHM,
+        extensions: [
+            new BasicConstraintsExtension(true, undefined, true),
+            new KeyUsagesExtension(KeyUsageFlags.keyCertSign | KeyUsageFlags.cRLSign, true),
+            await SubjectKeyIdentifierExtension.create(keys.publicKey)
+        ]
+    });
+    return {
+        certificatePem: cert.toString('pem'),
+        privateKey: keys.privateKey
+    };
+};
+const sansToJsonGeneralNames = (sans) => {
+    return [
+        ...sans.dnsNames.map((value) => ({ type: 'dns', value })),
+        ...sans.ipAddresses.map((value) => ({ type: 'ip', value }))
+    ];
+};
+export const signLeaf = async (input) => {
+    const issuerCert = new X509Certificate(input.issuer.certificatePem);
+    const keys = await generateKeyPair();
+    // Clock-skew defence: a phone whose clock lags the server's would reject a
+    // cert whose notBefore is "right now". Backdating by clockSkewHours lets the
+    // common offline-boat scenario work without manual NTP intervention.
+    const now = Date.now();
+    const notBefore = new Date(now - input.clockSkewHours * MS_PER_HOUR);
+    const notAfter = new Date(now + input.validityDays * MS_PER_DAY);
+    const subject = dn(input.subjectCommonName, input.organization);
+    const cert = await X509CertificateGenerator.create({
+        serialNumber: generateSerialNumber(),
+        subject,
+        issuer: issuerCert.subject,
+        notBefore,
+        notAfter,
+        publicKey: keys.publicKey,
+        signingKey: input.issuer.privateKey,
+        signingAlgorithm: EC_ALGORITHM,
+        extensions: [
+            new BasicConstraintsExtension(false, undefined, true),
+            new KeyUsagesExtension(KeyUsageFlags.digitalSignature | KeyUsageFlags.keyEncipherment, true),
+            new ExtendedKeyUsageExtension([ExtendedKeyUsage.serverAuth], false),
+            new SubjectAlternativeNameExtension(sansToJsonGeneralNames(input.sans), false),
+            await SubjectKeyIdentifierExtension.create(keys.publicKey),
+            await AuthorityKeyIdentifierExtension.create(issuerCert.publicKey)
+        ]
+    });
+    const privateKeyPem = await exportPrivateKeyPlainPkcs8(keys.privateKey);
+    return {
+        certificatePem: cert.toString('pem'),
+        privateKey: keys.privateKey,
+        privateKeyPem
+    };
+};
+const cryptoKeyToKeyObject = async (key) => {
+    const exported = await webcrypto.subtle.exportKey('pkcs8', key);
+    return createPrivateKey({
+        key: Buffer.from(exported),
+        format: 'der',
+        type: 'pkcs8'
+    });
+};
+const keyObjectToCryptoKey = async (keyObject, usages) => {
+    const pkcs8 = keyObject.export({ type: 'pkcs8', format: 'der' });
+    return webcrypto.subtle.importKey('pkcs8', pkcs8, EC_ALGORITHM, true, usages);
+};
+const exportPrivateKeyPlainPkcs8 = async (key) => {
+    const keyObject = await cryptoKeyToKeyObject(key);
+    return keyObject.export({ type: 'pkcs8', format: 'pem' });
+};
+/**
+ * Encrypt a CryptoKey as PBES2 / PBKDF2-SHA256 / AES-256-CBC PKCS#8 PEM.
+ * (Node's openssl bindings don't expose AES-GCM as a PBES2 cipher; AES-256-CBC
+ * is the strongest cipher Node will emit and is what `openssl pkcs8 -topk8`
+ * produces by default for `-v2 aes-256-cbc`.)
+ */
+export const encryptPrivateKeyPkcs8 = async (key, passphrase) => {
+    const keyObject = await cryptoKeyToKeyObject(key);
+    return keyObject.export({
+        type: 'pkcs8',
+        format: 'pem',
+        cipher: 'aes-256-cbc',
+        passphrase
+    });
+};
+export const decryptPrivateKeyPkcs8 = async (pem, passphrase) => {
+    const keyObject = createPrivateKey({
+        key: pem,
+        format: 'pem',
+        passphrase
+    });
+    return keyObjectToCryptoKey(keyObject, ['sign']);
+};
+export const derivePassphraseKey = async (passphrase, salt, iterations = PBKDF2_DEFAULT_ITERATIONS) => {
+    const keyMaterial = await webcrypto.subtle.importKey('raw', new TextEncoder().encode(passphrase), { name: 'PBKDF2' }, false, ['deriveKey']);
+    return webcrypto.subtle.deriveKey({
+        name: 'PBKDF2',
+        hash: 'SHA-256',
+        salt,
+        iterations
+    }, keyMaterial, { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+};
+const DIGEST_ALG = {
+    sha256: 'SHA-256'
+};
+export const computeSpkiFingerprint = async (certificatePem, algorithm) => {
+    const cert = new X509Certificate(certificatePem);
+    const spki = await webcrypto.subtle.exportKey('spki', await cert.publicKey.export());
+    const digest = await webcrypto.subtle.digest(DIGEST_ALG[algorithm], spki);
+    const bytes = new Uint8Array(digest);
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, '0').toUpperCase())
+        .join(':');
+};
+export const verifyChain = async (leafPem, caPem, atDate = new Date()) => {
+    const leaf = new X509Certificate(leafPem);
+    const ca = new X509Certificate(caPem);
+    return leaf.verify({ publicKey: ca.publicKey, date: atDate });
+};

package/dist/plugin/index.d.ts

@@ -0,0 +1,3 @@
+import type { PluginConstructor } from '@signalk/server-api';
+declare const pluginConstructor: PluginConstructor;
+export default pluginConstructor;

package/dist/plugin/index.js

@@ -0,0 +1,81 @@
+import { CertStore } from './storage.js';
+import { PassphraseSource } from './passphrase-source.js';
+import { SslService } from './service.js';
+import { startRenewalScheduler } from './scheduler.js';
+import { buildPublicRoutes, registerAdminRoutes } from './api.js';
+import { ConfigSchema, DEFAULT_CONFIG } from './schema.js';
+const PLUGIN_ID = 'signalk-ssl';
+const PLUGIN_NAME = 'SignalK SSL';
+const PLUGIN_DESCRIPTION = 'Generate a local CA and issue trusted HTTPS certificates for your SignalK server.';
+const resolveConfig = (raw) => {
+    return { ...DEFAULT_CONFIG, ...raw };
+};
+const resolveConfigPath = (app, fallback) => {
+    return app.config?.configPath ?? fallback;
+};
+const pluginConstructor = (app) => {
+    const extended = app;
+    let scheduler = null;
+    let service = null;
+    let store = null;
+    let passphrase = null;
+    let config = DEFAULT_CONFIG;
+    const plugin = {
+        id: PLUGIN_ID,
+        name: PLUGIN_NAME,
+        description: PLUGIN_DESCRIPTION,
+        schema: () => ConfigSchema,
+        start(rawConfig, _restart) {
+            config = resolveConfig(rawConfig);
+            const dataDir = app.getDataDirPath();
+            const configPath = resolveConfigPath(extended, dataDir);
+            store = new CertStore(dataDir);
+            passphrase = new PassphraseSource(config.passphraseMode, store);
+            service = new SslService({ store, passphrase, config, configPath });
+            const svcLocal = service;
+            const logSchedulerError = (err) => {
+                app.error(`${PLUGIN_ID} scheduled renewal failed: ${String(err)}`);
+            };
+            void store.init().then(async () => {
+                try {
+                    const outcome = await svcLocal.issueIfNeeded();
+                    app.debug(`${PLUGIN_ID} initial issueIfNeeded: ${JSON.stringify(outcome)}`);
+                }
+                catch (e) {
+                    app.error(`${PLUGIN_ID} initial issue failed: ${String(e)}`);
+                }
+                // Start the scheduler only after init + initial issue have completed,
+                // so a short test interval can't race against an uninitialised store.
+                scheduler = startRenewalScheduler(svcLocal, logSchedulerError);
+            });
+            app.debug(`${PLUGIN_ID} started; data dir=${dataDir}; configPath=${configPath}`);
+        },
+        stop() {
+            scheduler?.stop();
+            scheduler = null;
+            passphrase?.lock();
+            app.debug(`${PLUGIN_ID} stopped`);
+        },
+        registerWithRouter(router) {
+            if (service === null || store === null || passphrase === null) {
+                return;
+            }
+            registerAdminRoutes(router, { service, store, passphrase, config });
+        },
+        signalKApiRoutes(router) {
+            if (service === null || store === null || passphrase === null) {
+                return router;
+            }
+            return buildPublicRoutes(router, { service, store, passphrase, config });
+        },
+        statusMessage() {
+            if (service === null) {
+                return 'starting';
+            }
+            // statusMessage must be synchronous; just describe the cached config.
+            return `mode=${config.mode}, sans=${(config.sans.dnsNames.length + config.sans.ipAddresses.length).toString()}`;
+        }
+    };
+    return plugin;
+};
+export default pluginConstructor;

package/dist/plugin/mobileconfig.d.ts

@@ -0,0 +1,10 @@
+export interface MobileconfigOptions {
+    readonly caName: string;
+    readonly organization: string;
+}
+/**
+ * Build an unsigned .mobileconfig profile that installs `caCertPem` as a
+ * trusted root on iOS/iPadOS. Localised consent text mirrors what Keeper
+ * ships in https-service.ts:227-297 (en/de/fr/es/nl).
+ */
+export declare const buildMobileconfig: (caCertPem: string, options: MobileconfigOptions) => string;

package/dist/plugin/mobileconfig.js

@@ -0,0 +1,95 @@
+import { randomUUID } from 'node:crypto';
+const escapeXml = (s) => s.replace(/[<>&'"]/g, (ch) => {
+    switch (ch) {
+        case '<':
+            return '&lt;';
+        case '>':
+            return '&gt;';
+        case '&':
+            return '&amp;';
+        case "'":
+            return '&apos;';
+        case '"':
+            return '&quot;';
+        default:
+            return ch;
+    }
+});
+const pemToDerBase64 = (pem) => pem
+    .replace(/-----BEGIN CERTIFICATE-----/g, '')
+    .replace(/-----END CERTIFICATE-----/g, '')
+    .replace(/\s/g, '');
+/**
+ * Build an unsigned .mobileconfig profile that installs `caCertPem` as a
+ * trusted root on iOS/iPadOS. Localised consent text mirrors what Keeper
+ * ships in https-service.ts:227-297 (en/de/fr/es/nl).
+ */
+export const buildMobileconfig = (caCertPem, options) => {
+    const der = pemToDerBase64(caCertPem);
+    const profileUuid = randomUUID().toUpperCase();
+    const certUuid = randomUUID().toUpperCase();
+    const name = escapeXml(options.caName);
+    const org = escapeXml(options.organization);
+    // Use the already-XML-escaped `name` here so the template literals are
+    // injection-safe at construction time. Below we no longer pass the strings
+    // through escapeXml again, since they're already safe.
+    const consent = {
+        en: `After installing this profile, enable full trust: Settings → General → About → Certificate Trust Settings → enable "${name}".`,
+        de: `Nach der Installation dieses Profils aktivieren Sie volles Vertrauen: Einstellungen → Allgemein → Info → Zertifikatsvertrauenseinstellungen → "${name}" aktivieren.`,
+        fr: `Après l'installation de ce profil, activez la confiance totale : Réglages → Général → Informations → Réglages des certificats → activer « ${name} ».`,
+        es: `Después de instalar este perfil, habilite la confianza total: Ajustes → General → Información → Ajustes de certificados → activar "${name}".`,
+        nl: `Schakel na installatie van dit profiel volledig vertrouwen in: Instellingen → Algemeen → Info → Instellingen vertrouwde certificaten → "${name}" inschakelen.`
+    };
+    const consentXml = Object.entries(consent)
+        .map(([lang, text]) => `\t\t<key>${lang}</key>\n\t\t<string>${text}</string>`)
+        .join('\n');
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+\t<key>PayloadContent</key>
+\t<array>
+\t\t<dict>
+\t\t\t<key>PayloadCertificateFileName</key>
+\t\t\t<string>signalk-ssl-ca.crt</string>
+\t\t\t<key>PayloadContent</key>
+\t\t\t<data>${der}</data>
+\t\t\t<key>PayloadDescription</key>
+\t\t\t<string>Adds the ${name} root certificate</string>
+\t\t\t<key>PayloadDisplayName</key>
+\t\t\t<string>${name}</string>
+\t\t\t<key>PayloadIdentifier</key>
+\t\t\t<string>com.signalk.ssl.ca-cert</string>
+\t\t\t<key>PayloadType</key>
+\t\t\t<string>com.apple.security.root</string>
+\t\t\t<key>PayloadUUID</key>
+\t\t\t<string>${certUuid}</string>
+\t\t\t<key>PayloadVersion</key>
+\t\t\t<integer>1</integer>
+\t\t</dict>
+\t</array>
+\t<key>PayloadDescription</key>
+\t<string>Installs the ${name} certificate so your device trusts HTTPS connections to your SignalK server.</string>
+\t<key>PayloadDisplayName</key>
+\t<string>SignalK Secure Connection</string>
+\t<key>PayloadIdentifier</key>
+\t<string>com.signalk.ssl.https-profile</string>
+\t<key>PayloadOrganization</key>
+\t<string>${org}</string>
+\t<key>PayloadRemovalDisallowed</key>
+\t<false/>
+\t<key>PayloadType</key>
+\t<string>Configuration</string>
+\t<key>PayloadUUID</key>
+\t<string>${profileUuid}</string>
+\t<key>PayloadVersion</key>
+\t<integer>1</integer>
+\t<key>ConsentText</key>
+\t<dict>
+\t\t<key>default</key>
+\t\t<string>${consent.en}</string>
+${consentXml}
+\t</dict>
+</dict>
+</plist>`;
+};

package/dist/plugin/needs-renewal.d.ts

@@ -0,0 +1,10 @@
+import type { ParsedSans } from './types.js';
+export type RenewalReason = 'expired' | 'expiring-soon' | 'san-mismatch' | 'ok';
+export interface RenewalDecision {
+    readonly needsRenewal: boolean;
+    readonly reason: RenewalReason;
+    readonly daysUntilExpiry: number;
+    readonly missingDnsNames: readonly string[];
+    readonly missingIpAddresses: readonly string[];
+}
+export declare const needsRenewal: (certificatePem: string, requiredSans: ParsedSans, thresholdDays: number, now?: Date) => RenewalDecision;