signalk-ssl 0.4.0 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ The Appstore installs plugins with `npm install --ignore-scripts`, so this packa
    - **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/`.
+4. Open the plugin webapp at `/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
@@ -76,7 +76,7 @@ or `webapp` mode first.
 
 ## Routes
 
-- `GET /plugins/signalk-ssl/` — webapp (admin auth required)
+- `GET /signalk-ssl/` — webapp static files (served by signalk-server at the module name, 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)

package/dist/plugin/api.d.ts

@@ -1,5 +1,5 @@
 import type { IRouter } from 'express';
-import type { SslService } from './service.js';
+import type { SslService, ServiceStatus } from './service.js';
 import type { SignalkSslConfig } from './schema.js';
 import type { PassphraseSource } from './passphrase-source.js';
 import type { CertStore } from './storage.js';
@@ -13,6 +13,10 @@ export interface AdminApiDeps extends ApiDeps {
     /** Returns the raw hostname signalk-server uses for mDNS advertisement,
      * or '' if unavailable. See ExtendedServerAPI in src/plugin/index.ts. */
     readonly getRawHostname: () => string;
+    /** Called with each fresh status the admin routes compute, so the plugin can
+     * keep its synchronous statusMessage() cache current (the webapp polls
+     * /status, and /renew recomputes it). Optional. */
+    readonly onStatus?: (status: ServiceStatus) => void;
 }
 /** Mounted by the server at /plugins/signalk-ssl/* — admin auth applied. */
 export declare const registerAdminRoutes: (router: IRouter, deps: AdminApiDeps) => void;

package/dist/plugin/api.js

@@ -12,6 +12,7 @@ const asyncRoute = (fn) => (req, res, next) => {
 export const registerAdminRoutes = (router, deps) => {
     router.get('/status', asyncRoute(async (_req, res) => {
         const s = await deps.service.status();
+        deps.onStatus?.(s);
         sendJson(res, 200, s);
     }));
     router.get('/api/local-ips', (_req, res) => {
@@ -22,6 +23,9 @@ export const registerAdminRoutes = (router, deps) => {
     });
     router.post('/renew', asyncRoute(async (_req, res) => {
         const out = await deps.service.issueIfNeeded();
+        if (deps.onStatus) {
+            deps.onStatus(await deps.service.status());
+        }
         sendJson(res, 200, out);
     }));
     router.post('/unlock', asyncRoute(async (req, res) => {

package/dist/plugin/index.d.ts

@@ -1,4 +1,13 @@
 import 'reflect-metadata';
 import type { PluginConstructor } from '@signalk/server-api';
+import { type ServiceStatus } from './service.js';
+/**
+ * One-line status for the admin plugin list. statusMessage() must be
+ * synchronous, so this formats a cached {@link ServiceStatus} snapshot rather
+ * than reading the cert state from disk. Describes issuance state — not config —
+ * so an operator can tell "issued and healthy" from "no cert yet" or "error" at
+ * a glance. `null` snapshot means startup hasn't produced one yet.
+ */
+export declare const formatStatusMessage: (status: ServiceStatus | null) => string;
 declare const pluginConstructor: PluginConstructor;
 export default pluginConstructor;

package/dist/plugin/index.js

@@ -5,10 +5,10 @@
 import 'reflect-metadata';
 import { CertStore } from './storage.js';
 import { PassphraseSource } from './passphrase-source.js';
-import { SslService } from './service.js';
+import { SslService, discoverAdvertisedHostname } from './service.js';
 import { startRenewalScheduler } from './scheduler.js';
 import { buildPublicRoutes, registerAdminRoutes } from './api.js';
-import { ConfigSchema, DEFAULT_CONFIG } from './schema.js';
+import { buildConfigSchema, 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.';
@@ -18,18 +18,61 @@ const resolveConfig = (raw) => {
 const resolveConfigPath = (app, fallback) => {
     return app.config?.configPath ?? fallback;
 };
+/**
+ * One-line status for the admin plugin list. statusMessage() must be
+ * synchronous, so this formats a cached {@link ServiceStatus} snapshot rather
+ * than reading the cert state from disk. Describes issuance state — not config —
+ * so an operator can tell "issued and healthy" from "no cert yet" or "error" at
+ * a glance. `null` snapshot means startup hasn't produced one yet.
+ */
+export const formatStatusMessage = (status) => {
+    if (status === null) {
+        return 'starting';
+    }
+    if (status.permissionWarning !== null) {
+        return `error: ${status.permissionWarning}`;
+    }
+    if (!status.hasCa) {
+        return 'no CA yet — enable and save config';
+    }
+    if (!status.hasLeaf) {
+        return 'CA ready, no certificate issued yet';
+    }
+    const name = status.leafSansDns[0] ?? status.leafSansIp[0] ?? 'certificate';
+    const days = status.leafDaysRemaining;
+    const expiry = days === null ? '' : ` · ${days.toString()}d left`;
+    const restart = status.restartRequired ? ' · restart to apply' : '';
+    return `${name}${expiry}${restart}`;
+};
 const pluginConstructor = (app) => {
     const extended = app;
+    // The raw hostname signalk-server uses for mDNS (EXTERNALHOST → proxy_host →
+    // settings.hostname → os.hostname()), '' when unavailable.
+    const rawHostname = () => extended.config?.getExternalHostname?.() ?? '';
     let scheduler = null;
     let service = null;
     let store = null;
     let passphrase = null;
     let config = DEFAULT_CONFIG;
+    // Cached snapshot for the synchronous statusMessage(); refreshed after each
+    // issue attempt. Approximate between refreshes (the webapp /status is live).
+    let lastStatus = null;
+    const refreshStatus = async (svc) => {
+        try {
+            lastStatus = await svc.status();
+        }
+        catch (e) {
+            app.error(`${PLUGIN_ID} status refresh failed: ${String(e)}`);
+        }
+    };
     const plugin = {
         id: PLUGIN_ID,
         name: PLUGIN_NAME,
         description: PLUGIN_DESCRIPTION,
-        schema: () => ConfigSchema,
+        // Re-evaluated by signalk-server on every config-screen load, so the
+        // discovered hostname is injected as the dnsNames default and shows up
+        // pre-filled in the form *before* the plugin is enabled.
+        schema: () => buildConfigSchema(discoverAdvertisedHostname(rawHostname())),
         start(rawConfig, _restart) {
             config = resolveConfig(rawConfig);
             const dataDir = app.getDataDirPath();
@@ -38,10 +81,13 @@ const pluginConstructor = (app) => {
             passphrase = new PassphraseSource(config.passphraseMode, store);
             service = new SslService({ store, passphrase, config, configPath });
             const svcLocal = service;
+            const storeLocal = store;
             const logSchedulerError = (err) => {
                 app.error(`${PLUGIN_ID} scheduled renewal failed: ${String(err)}`);
             };
-            void store.init().then(async () => {
+            void storeLocal
+                .init()
+                .then(async () => {
                 try {
                     const warning = await svcLocal.checkWritePermissions();
                     if (warning !== null) {
@@ -58,9 +104,18 @@ const pluginConstructor = (app) => {
                 catch (e) {
                     app.error(`${PLUGIN_ID} initial issue failed: ${String(e)}`);
                 }
+                await refreshStatus(svcLocal);
                 // 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);
+            })
+                // Terminal guard: store.init() (mkdir on a read-only / UID-shifted data
+                // dir) or a throw from startRenewalScheduler would otherwise surface as
+                // an unhandled rejection. The per-block try/catch above keep the issue
+                // flow going; this only catches what they can't. scheduler is left null
+                // on failure (the assignment is the last statement), so stop() is safe.
+                .catch((e) => {
+                app.error(`${PLUGIN_ID} startup failed: ${String(e)}`);
             });
             app.debug(`${PLUGIN_ID} started; data dir=${dataDir}; configPath=${configPath}`);
         },
@@ -79,7 +134,10 @@ const pluginConstructor = (app) => {
                 store,
                 passphrase,
                 config,
-                getRawHostname: () => extended.config?.getExternalHostname?.() ?? ''
+                getRawHostname: rawHostname,
+                onStatus: (s) => {
+                    lastStatus = s;
+                }
             });
         },
         signalKApiRoutes(router) {
@@ -89,11 +147,7 @@ const pluginConstructor = (app) => {
             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 formatStatusMessage(lastStatus);
         }
     };
     return plugin;

package/dist/plugin/schema.d.ts

@@ -1,4 +1,4 @@
-import { type Static } from '@sinclair/typebox';
+import { type Static, type TSchema } from '@sinclair/typebox';
 export declare const SansSchema: import("@sinclair/typebox").TObject<{
     dnsNames: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
     ipAddresses: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
@@ -25,5 +25,17 @@ export declare const ConfigSchema: import("@sinclair/typebox").TObject<{
     renewalThresholdDays: import("@sinclair/typebox").TInteger;
     clockSkewHours: import("@sinclair/typebox").TInteger;
 }>;
+/**
+ * Return the config schema with `dnsNames` pre-filled with the discovered mDNS
+ * hostname, so the server-rendered config form shows it as a suggested default
+ * before the plugin is enabled. Falls back to the static {@link ConfigSchema}
+ * (empty default) when no useful hostname is available.
+ *
+ * `schema()` is re-invoked by signalk-server on every config-screen load, so
+ * this is evaluated fresh each time — no caching, picks up hostname changes.
+ * A default is a non-forcing suggestion: a user who clears it gets an empty
+ * list, no provenance tracking needed.
+ */
+export declare const buildConfigSchema: (dnsDefault: string | null) => TSchema;
 export type SignalkSslConfig = Static<typeof ConfigSchema>;
 export declare const DEFAULT_CONFIG: SignalkSslConfig;

package/dist/plugin/schema.js

@@ -71,6 +71,27 @@ export const ConfigSchema = Type.Object({
     title: 'SignalK SSL',
     description: 'Manage a local Certificate Authority and HTTPS leaf certificates for this server.'
 });
+/**
+ * Return the config schema with `dnsNames` pre-filled with the discovered mDNS
+ * hostname, so the server-rendered config form shows it as a suggested default
+ * before the plugin is enabled. Falls back to the static {@link ConfigSchema}
+ * (empty default) when no useful hostname is available.
+ *
+ * `schema()` is re-invoked by signalk-server on every config-screen load, so
+ * this is evaluated fresh each time — no caching, picks up hostname changes.
+ * A default is a non-forcing suggestion: a user who clears it gets an empty
+ * list, no provenance tracking needed.
+ */
+export const buildConfigSchema = (dnsDefault) => {
+    if (dnsDefault === null) {
+        return ConfigSchema;
+    }
+    // ConfigSchema is a plain JSON object at runtime; clone so we never mutate the
+    // shared static schema, then swap in the hostname default.
+    const clone = structuredClone(ConfigSchema);
+    clone.properties.sans.properties.dnsNames.default = [dnsDefault];
+    return clone;
+};
 export const DEFAULT_CONFIG = {
     mode: 'generate',
     commonName: 'SignalK Local CA',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-ssl",
-  "version": "0.4.0",
+  "version": "0.6.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",
@@ -58,7 +58,7 @@
     "webapp": {
       "name": "SignalK SSL",
       "description": "SSL/TLS certificate management for SignalK",
-      "location": "/plugins/signalk-ssl/"
+      "location": "/signalk-ssl/"
     }
   },
   "peerDependencies": {

package/public/index.html

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>SignalK SSL</title>
-    <script type="module" crossorigin src="/plugins/signalk-ssl/assets/index-CVVhdLBc.js"></script>
-    <link rel="stylesheet" crossorigin href="/plugins/signalk-ssl/assets/index-xrow3Xg7.css">
+    <script type="module" crossorigin src="/signalk-ssl/assets/index-CVVhdLBc.js"></script>
+    <link rel="stylesheet" crossorigin href="/signalk-ssl/assets/index-xrow3Xg7.css">
   </head>
   <body class="bg-slate-50 text-slate-900">
     <div id="root"></div>