signalk-ssl 0.5.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

@@ -8,7 +8,7 @@ import { PassphraseSource } from './passphrase-source.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,50 +18,62 @@ const resolveConfig = (raw) => {
 const resolveConfigPath = (app, fallback) => {
     return app.config?.configPath ?? fallback;
 };
-const sansAreEmpty = (config) => config.sans.dnsNames.length === 0 && config.sans.ipAddresses.length === 0;
 /**
- * One-shot seed: on first run with an empty SAN list, pre-populate dnsNames
- * with the name the server advertises on mDNS so the user sees a sensible,
- * server-specific default in the plugin config screen instead of a blank field.
- *
- * Guarded by a persistent marker so it runs at most once per install: a user
- * who deletes the seeded name will not see it re-added on the next restart
- * (the SAN-provenance rule from AGENTS.md). Returns true when it triggered a
- * restart, in which case the caller must stop — the plugin is being restarted
- * with the new config.
+ * 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.
  */
-const maybeSeedHostname = async (store, config, rawHostname, restart, log) => {
-    if (!sansAreEmpty(config) || (await store.hasSeededHostname())) {
-        return false;
+export const formatStatusMessage = (status) => {
+    if (status === null) {
+        return 'starting';
     }
-    const hostname = discoverAdvertisedHostname(rawHostname);
-    if (hostname === null) {
-        // No useful suggestion (container ID, localhost, etc.). Don't write the
-        // marker — if the host gets a real name later, we still want to seed then.
-        return false;
+    if (status.permissionWarning !== null) {
+        return `error: ${status.permissionWarning}`;
     }
-    await store.markHostnameSeeded(hostname);
-    const newConfig = {
-        ...config,
-        sans: { ...config.sans, dnsNames: [hostname] }
-    };
-    log(`${PLUGIN_ID} seeding empty SANs with discovered hostname ${hostname}`);
-    restart(newConfig);
-    return true;
+    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,
-        start(rawConfig, restart) {
+        // 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();
             const configPath = resolveConfigPath(extended, dataDir);
@@ -70,30 +82,12 @@ const pluginConstructor = (app) => {
             service = new SslService({ store, passphrase, config, configPath });
             const svcLocal = service;
             const storeLocal = store;
-            const cfgLocal = config;
             const logSchedulerError = (err) => {
                 app.error(`${PLUGIN_ID} scheduled renewal failed: ${String(err)}`);
             };
             void storeLocal
                 .init()
                 .then(async () => {
-                // First-run SAN seed must run before the issue flow: if it triggers a
-                // restart, start() runs again with the seeded config and the issue
-                // happens then. Bail out here so we don't issue against empty SANs and
-                // immediately get restarted out from under it.
-                try {
-                    const rawHostname = extended.config?.getExternalHostname?.() ?? '';
-                    const restarted = await maybeSeedHostname(storeLocal, cfgLocal, rawHostname, restart, (msg) => {
-                        app.debug(msg);
-                    });
-                    if (restarted) {
-                        return;
-                    }
-                }
-                catch (e) {
-                    // A seed failure must never block cert issuance — log and continue.
-                    app.error(`${PLUGIN_ID} hostname seed failed: ${String(e)}`);
-                }
                 try {
                     const warning = await svcLocal.checkWritePermissions();
                     if (warning !== null) {
@@ -110,6 +104,7 @@ 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);
@@ -139,7 +134,10 @@ const pluginConstructor = (app) => {
                 store,
                 passphrase,
                 config,
-                getRawHostname: () => extended.config?.getExternalHostname?.() ?? ''
+                getRawHostname: rawHostname,
+                onStatus: (s) => {
+                    lastStatus = s;
+                }
             });
         },
         signalKApiRoutes(router) {
@@ -149,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/dist/plugin/storage.d.ts

@@ -34,13 +34,4 @@ export declare class CertStore {
     writeSettings(settings: SettingsOnDisk): Promise<void>;
     readConvenienceEnvelope(): Promise<ConveniencePassphraseEnvelope | null>;
     writeConvenienceEnvelope(env: ConveniencePassphraseEnvelope): Promise<void>;
-    /**
-     * Whether the plugin has already attempted its one-shot SAN seed (auto-adding
-     * the discovered mDNS hostname to an empty dnsNames list on first run). The
-     * marker makes the seed a one-time action: once it exists, a user who deletes
-     * the seeded name will not see it re-added on the next restart. Presence is
-     * the whole signal; the stored body is informational only.
-     */
-    hasSeededHostname(): Promise<boolean>;
-    markHostnameSeeded(hostname: string): Promise<void>;
 }

package/dist/plugin/storage.js

@@ -9,8 +9,7 @@ const FILES = {
     state: 'state.json',
     leafState: 'leaf-state.json',
     settings: 'settings.json',
-    convenience: 'passphrase.kdf.json',
-    hostnameSeeded: 'hostname-seeded.json'
+    convenience: 'passphrase.kdf.json'
 };
 const PEM_KEY_MODE = 0o600;
 const PEM_CERT_MODE = 0o644;
@@ -131,19 +130,4 @@ export class CertStore {
         await this.init();
         await atomicWrite(this.path('convenience'), JSON.stringify(env, null, 2), JSON_MODE);
     }
-    /**
-     * Whether the plugin has already attempted its one-shot SAN seed (auto-adding
-     * the discovered mDNS hostname to an empty dnsNames list on first run). The
-     * marker makes the seed a one-time action: once it exists, a user who deletes
-     * the seeded name will not see it re-added on the next restart. Presence is
-     * the whole signal; the stored body is informational only.
-     */
-    async hasSeededHostname() {
-        return (await readIfExists(this.path('hostnameSeeded'))) !== null;
-    }
-    async markHostnameSeeded(hostname) {
-        await this.init();
-        const body = JSON.stringify({ hostname, seededAt: new Date().toISOString() }, null, 2);
-        await atomicWrite(this.path('hostnameSeeded'), body, JSON_MODE);
-    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "signalk-ssl",
-  "version": "0.5.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>