commandmate 0.27.1 → 0.28.0

package/dist/lib/push/vapid.d.ts

@@ -0,0 +1,178 @@
+/**
+ * VAPID configuration for Web Push, and the one startup check that reports on it
+ * (Issue #1125; the check and the subject rules are Issues #2123 / #2124).
+ *
+ * Keys are supplied via environment variables and read lazily so tests can vary
+ * them and so an unconfigured deployment simply disables push (never crashes).
+ * The private key and subject are secrets — never log the returned config.
+ *
+ * ## Why the default subject is an https: URL (Issue #2124)
+ *
+ * The VAPID `sub` claim is the sender's contact, and **Apple validates it**. The
+ * original default, `mailto:commandmate@localhost`, names a domain that cannot
+ * exist, so APNs answered 403 and iOS/iPadOS received nothing while Android kept
+ * working — FCM is permissive about `sub`, so testing on Android alone cannot
+ * see it. Measured by the orchestrator during the Epic #2002 device UAT
+ * (2026-08-27, develop e8d09989), fanning ONE waiting notification to two
+ * devices:
+ *
+ *   Android 10 / Chrome 151 -> FCM   default subject: delivered
+ *   iPad / iPadOS 18.7      -> APNs  default subject: 403, push-send-failed
+ *                                    https://github.com/Kewton/CommandMate: delivered
+ *
+ * This file's author did NOT reproduce that on hardware; the APNs/FCM behaviour
+ * above is quoted from that UAT and is not re-measured here. What IS pinned by
+ * the unit suite is the pure part: which subjects this module accepts and which
+ * it flags, and that the default is one of the accepted ones.
+ *
+ * RFC 8292 §2.1 allows both `mailto:` and `https:` for `sub`, so a project URL
+ * is a conforming default that needs no per-install mailbox.
+ *
+ * ## Why an invalid subject is reported and NOT replaced
+ *
+ * {@link inspectVapidConfig} flags a bad `CM_VAPID_SUBJECT`; {@link getVapidConfig}
+ * still returns it verbatim. Silently substituting the default would make the
+ * warning describe a value the server does not actually send, and would make
+ * `commandmate status` disagree with the wire. The operator set it; they are told
+ * it will be rejected, and startup is never blocked (fail-open, exactly as
+ * `lib/server/localhost-self-check` is).
+ *
+ * ## No `@/` imports here, ever
+ *
+ * `src/cli/commands/status.ts` imports this module so the CLI and the server run
+ * the SAME check, and `tsconfig.cli.json` resets `paths` to `{}` — an alias
+ * import here would break `npm run build:cli`. Same constraint as
+ * `lib/server/localhost-self-check.ts` and `lib/detection/version-probes.ts`.
+ * This module must also stay dependency-free for that reason.
+ *
+ * @module lib/push/vapid
+ */
+export interface VapidConfig {
+    publicKey: string;
+    privateKey: string;
+    subject: string;
+}
+/**
+ * Default `sub` claim when `CM_VAPID_SUBJECT` is unset.
+ *
+ * A real, resolvable https: URL — see the module header for the APNs measurement
+ * that made `mailto:commandmate@localhost` the wrong answer (Issue #2124).
+ */
+export declare const VAPID_DEFAULT_SUBJECT = "https://github.com/Kewton/CommandMate";
+/** The three environment variables that configure Web Push. */
+export declare const VAPID_ENV_KEYS: {
+    readonly publicKey: "CM_VAPID_PUBLIC_KEY";
+    readonly privateKey: "CM_VAPID_PRIVATE_KEY";
+    readonly subject: "CM_VAPID_SUBJECT";
+};
+/** What is wrong with a `CM_VAPID_SUBJECT`, or `null` when nothing is. */
+export type VapidSubjectIssue = 
+/** Neither `mailto:` nor `https:` — RFC 8292 §2.1 allows only those two. */
+'unsupported-scheme'
+/** Parsed as a supported scheme but carries no host at all. */
+ | 'missing-host'
+/** A host no push service can resolve: `localhost`, a bare name, a reserved TLD, a loopback literal. */
+ | 'non-routable-host';
+/**
+ * The host a subject names, lowercased, or `null` when it names none.
+ *
+ * `mailto:` takes everything after the LAST `@` (a local part may legally contain
+ * one when quoted) up to the first `?` (RFC 6068 header separator). `https:` is
+ * parsed by `URL`, whose `hostname` already strips the brackets off an IPv6
+ * literal.
+ */
+export declare function extractVapidSubjectHost(subject: string): string | null;
+/**
+ * Decide whether a `sub` claim is one a push service can be expected to accept.
+ *
+ * Deliberately conservative: it rejects only hosts that provably cannot resolve.
+ * A reachable-but-wrong contact (`mailto:nobody@example.com`) is the operator's
+ * business, and a check that guessed at it would warn on healthy installs.
+ *
+ * @param subject - Raw `CM_VAPID_SUBJECT`, or the default.
+ * @returns The problem, or `null` when the subject is usable.
+ */
+export declare function classifyVapidSubject(subject: string): VapidSubjectIssue | null;
+/** How a deployment's Web Push configuration reads right now. */
+export type VapidStatus = 
+/** Neither key is set: push is off, and nothing was half-configured. */
+'unconfigured'
+/** Exactly one of the two keys is set — almost always a typo or a half-finished edit. */
+ | 'partial'
+/** Both keys present, but `CM_VAPID_SUBJECT` will be rejected by at least APNs. */
+ | 'invalid-subject'
+/** Both keys present and the subject is usable. Nothing to report. */
+ | 'ok';
+/** The single verdict {@link inspectVapidConfig} produces (Issues #2123 / #2124). */
+export interface VapidInspection {
+    status: VapidStatus;
+    /** True when both keys are present, i.e. when push can send at all. */
+    configured: boolean;
+    /** The `sub` claim that will actually be sent. */
+    subject: string;
+    /** Whether {@link subject} came from the environment or from the built-in default. */
+    subjectSource: 'env' | 'default';
+    /** What is wrong with {@link subject}, or `null`. */
+    subjectIssue: VapidSubjectIssue | null;
+    /** Names of the VAPID variables that are set — never their values. */
+    presentKeys: readonly string[];
+    /** Names of the key variables that are missing. */
+    missingKeys: readonly string[];
+}
+/** The slice of the environment this module reads. */
+export type VapidEnv = Readonly<Record<string, string | undefined>>;
+/**
+ * Read the three variables and say, in one verdict, everything both Issues need
+ * reported: whether push is on at all (#2123) and whether the subject will be
+ * accepted (#2124).
+ *
+ * ONE check, two facts — deliberately not two checks. The startup log, the
+ * `commandmate status` output and the unit suite all consume this one function,
+ * so the two surfaces cannot drift apart.
+ *
+ * Pure: no I/O, no logging, never throws.
+ *
+ * @param env - Environment to read (default: `process.env`). `commandmate status`
+ *   passes the env the *daemon* runs with, which is not this process's own.
+ */
+export declare function inspectVapidConfig(env?: VapidEnv): VapidInspection;
+/**
+ * The startup / `status` report, as lines — shared by both surfaces so they can
+ * never drift apart, exactly as `formatLocalhostConflictWarning` is (#2113).
+ *
+ * **Returns an empty array when the configuration is healthy.** That silence is
+ * the negative control both Issues ask for: a correctly configured server prints
+ * nothing about push, so the presence of a line is itself the signal.
+ *
+ * Never includes a key or a private value. `subject` is printed because it is the
+ * value the operator has to fix, and it is a contact address rather than a
+ * credential — the module header's "never log the config" rule is about the keys.
+ */
+export declare function formatVapidReportLines(inspection: VapidInspection): string[];
+/** Options for {@link runVapidSelfCheck}. */
+export interface RunVapidSelfCheckOptions {
+    /** Environment to inspect (default: `process.env`). */
+    env?: VapidEnv;
+    /** Where the report goes (default: `console.warn`). */
+    warn?: (message: string) => void;
+}
+/**
+ * Run the startup self-check and print its verdict, or nothing when healthy.
+ *
+ * Fail-open by construction, the same contract `runLocalhostSelfCheck` carries:
+ * it never throws, it never blocks `listen`, and a healthy install is silent.
+ *
+ * @returns The inspection, or `null` when the check itself could not be carried
+ *   out (which is reported as nothing at all).
+ */
+export declare function runVapidSelfCheck(options?: RunVapidSelfCheckOptions): VapidInspection | null;
+/**
+ * Returns the VAPID config, or null when push is not configured (both public
+ * and private keys must be present). Read from env on every call.
+ */
+export declare function getVapidConfig(): VapidConfig | null;
+/** True when both VAPID keys are configured. */
+export declare function isPushConfigured(): boolean;
+/** The public (application server) key clients need to subscribe, or null. */
+export declare function getVapidPublicKey(): string | null;
+//# sourceMappingURL=vapid.d.ts.map

package/dist/lib/push/vapid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vapid.d.ts","sourceRoot":"","sources":["../../../src/lib/push/vapid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,0CAA0C,CAAC;AAE7E,+DAA+D;AAC/D,eAAO,MAAM,cAAc;;;;CAIjB,CAAC;AAuBX,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB;AAC3B,4EAA4E;AAC1E,oBAAoB;AACtB,+DAA+D;GAC7D,cAAc;AAChB,wGAAwG;GACtG,mBAAmB,CAAC;AAQxB;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBtE;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe9E;AAED,iEAAiE;AACjE,MAAM,MAAM,WAAW;AACrB,wEAAwE;AACtE,cAAc;AAChB,yFAAyF;GACvF,SAAS;AACX,mFAAmF;GACjF,iBAAiB;AACnB,sEAAsE;GACpE,IAAI,CAAC;AAET,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,WAAW,CAAC;IACpB,uEAAuE;IACvE,UAAU,EAAE,OAAO,CAAC;IACpB,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,aAAa,EAAE,KAAK,GAAG,SAAS,CAAC;IACjC,qDAAqD;IACrD,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,sEAAsE;IACtE,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B,mDAAmD;IACnD,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,sDAAsD;AACtD,MAAM,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,QAAsB,GAAG,eAAe,CAiC/E;AAcD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,eAAe,GAAG,MAAM,EAAE,CAiC5E;AAED,6CAA6C;AAC7C,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,uDAAuD;IACvD,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,GAAE,wBAA6B,GAAG,eAAe,GAAG,IAAI,CAahG;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,WAAW,GAAG,IAAI,CAQnD;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAEjD"}

package/dist/lib/push/vapid.js

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * VAPID configuration for Web Push, and the one startup check that reports on it
+ * (Issue #1125; the check and the subject rules are Issues #2123 / #2124).
+ *
+ * Keys are supplied via environment variables and read lazily so tests can vary
+ * them and so an unconfigured deployment simply disables push (never crashes).
+ * The private key and subject are secrets — never log the returned config.
+ *
+ * ## Why the default subject is an https: URL (Issue #2124)
+ *
+ * The VAPID `sub` claim is the sender's contact, and **Apple validates it**. The
+ * original default, `mailto:commandmate@localhost`, names a domain that cannot
+ * exist, so APNs answered 403 and iOS/iPadOS received nothing while Android kept
+ * working — FCM is permissive about `sub`, so testing on Android alone cannot
+ * see it. Measured by the orchestrator during the Epic #2002 device UAT
+ * (2026-08-27, develop e8d09989), fanning ONE waiting notification to two
+ * devices:
+ *
+ *   Android 10 / Chrome 151 -> FCM   default subject: delivered
+ *   iPad / iPadOS 18.7      -> APNs  default subject: 403, push-send-failed
+ *                                    https://github.com/Kewton/CommandMate: delivered
+ *
+ * This file's author did NOT reproduce that on hardware; the APNs/FCM behaviour
+ * above is quoted from that UAT and is not re-measured here. What IS pinned by
+ * the unit suite is the pure part: which subjects this module accepts and which
+ * it flags, and that the default is one of the accepted ones.
+ *
+ * RFC 8292 §2.1 allows both `mailto:` and `https:` for `sub`, so a project URL
+ * is a conforming default that needs no per-install mailbox.
+ *
+ * ## Why an invalid subject is reported and NOT replaced
+ *
+ * {@link inspectVapidConfig} flags a bad `CM_VAPID_SUBJECT`; {@link getVapidConfig}
+ * still returns it verbatim. Silently substituting the default would make the
+ * warning describe a value the server does not actually send, and would make
+ * `commandmate status` disagree with the wire. The operator set it; they are told
+ * it will be rejected, and startup is never blocked (fail-open, exactly as
+ * `lib/server/localhost-self-check` is).
+ *
+ * ## No `@/` imports here, ever
+ *
+ * `src/cli/commands/status.ts` imports this module so the CLI and the server run
+ * the SAME check, and `tsconfig.cli.json` resets `paths` to `{}` — an alias
+ * import here would break `npm run build:cli`. Same constraint as
+ * `lib/server/localhost-self-check.ts` and `lib/detection/version-probes.ts`.
+ * This module must also stay dependency-free for that reason.
+ *
+ * @module lib/push/vapid
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VAPID_ENV_KEYS = exports.VAPID_DEFAULT_SUBJECT = void 0;
+exports.extractVapidSubjectHost = extractVapidSubjectHost;
+exports.classifyVapidSubject = classifyVapidSubject;
+exports.inspectVapidConfig = inspectVapidConfig;
+exports.formatVapidReportLines = formatVapidReportLines;
+exports.runVapidSelfCheck = runVapidSelfCheck;
+exports.getVapidConfig = getVapidConfig;
+exports.isPushConfigured = isPushConfigured;
+exports.getVapidPublicKey = getVapidPublicKey;
+/**
+ * Default `sub` claim when `CM_VAPID_SUBJECT` is unset.
+ *
+ * A real, resolvable https: URL — see the module header for the APNs measurement
+ * that made `mailto:commandmate@localhost` the wrong answer (Issue #2124).
+ */
+exports.VAPID_DEFAULT_SUBJECT = 'https://github.com/Kewton/CommandMate';
+/** The three environment variables that configure Web Push. */
+exports.VAPID_ENV_KEYS = {
+    publicKey: 'CM_VAPID_PUBLIC_KEY',
+    privateKey: 'CM_VAPID_PRIVATE_KEY',
+    subject: 'CM_VAPID_SUBJECT',
+};
+/**
+ * Host suffixes that never resolve on the public internet, so a push service can
+ * never verify a `sub` that names one.
+ *
+ * `.example` is here as a *TLD*; `example.com` is an ordinary resolvable domain
+ * and is deliberately NOT rejected (it is the conventional placeholder in every
+ * VAPID tutorial and in this repository's own tests).
+ */
+const NON_ROUTABLE_TLDS = [
+    'local',
+    'localhost',
+    'localdomain',
+    'internal',
+    'intranet',
+    'home',
+    'lan',
+    'test',
+    'invalid',
+    'example',
+];
+/** Loopback / unspecified literals, which are never a contact anyone can reach. */
+function isLoopbackLiteral(host) {
+    if (host === '::1' || host === '0.0.0.0' || host === '::')
+        return true;
+    return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+/**
+ * The host a subject names, lowercased, or `null` when it names none.
+ *
+ * `mailto:` takes everything after the LAST `@` (a local part may legally contain
+ * one when quoted) up to the first `?` (RFC 6068 header separator). `https:` is
+ * parsed by `URL`, whose `hostname` already strips the brackets off an IPv6
+ * literal.
+ */
+function extractVapidSubjectHost(subject) {
+    const trimmed = subject.trim();
+    if (/^mailto:/i.test(trimmed)) {
+        const address = trimmed.slice('mailto:'.length).split('?')[0];
+        const at = address.lastIndexOf('@');
+        if (at < 0)
+            return null;
+        const host = address.slice(at + 1).trim().toLowerCase();
+        return host.length > 0 ? host : null;
+    }
+    try {
+        const url = new URL(trimmed);
+        return url.hostname.length > 0 ? url.hostname.toLowerCase() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether a `sub` claim is one a push service can be expected to accept.
+ *
+ * Deliberately conservative: it rejects only hosts that provably cannot resolve.
+ * A reachable-but-wrong contact (`mailto:nobody@example.com`) is the operator's
+ * business, and a check that guessed at it would warn on healthy installs.
+ *
+ * @param subject - Raw `CM_VAPID_SUBJECT`, or the default.
+ * @returns The problem, or `null` when the subject is usable.
+ */
+function classifyVapidSubject(subject) {
+    const trimmed = subject.trim();
+    if (!/^(mailto:|https:\/\/)/i.test(trimmed))
+        return 'unsupported-scheme';
+    const host = extractVapidSubjectHost(trimmed);
+    if (host === null)
+        return 'missing-host';
+    if (isLoopbackLiteral(host))
+        return 'non-routable-host';
+    // A bare name (`localhost`, `mac-mini`) has no public resolution path.
+    if (!host.includes('.'))
+        return 'non-routable-host';
+    const tld = host.slice(host.lastIndexOf('.') + 1);
+    if (NON_ROUTABLE_TLDS.includes(tld))
+        return 'non-routable-host';
+    return null;
+}
+/**
+ * Read the three variables and say, in one verdict, everything both Issues need
+ * reported: whether push is on at all (#2123) and whether the subject will be
+ * accepted (#2124).
+ *
+ * ONE check, two facts — deliberately not two checks. The startup log, the
+ * `commandmate status` output and the unit suite all consume this one function,
+ * so the two surfaces cannot drift apart.
+ *
+ * Pure: no I/O, no logging, never throws.
+ *
+ * @param env - Environment to read (default: `process.env`). `commandmate status`
+ *   passes the env the *daemon* runs with, which is not this process's own.
+ */
+function inspectVapidConfig(env = process.env) {
+    const publicKey = env[exports.VAPID_ENV_KEYS.publicKey]?.trim() ?? '';
+    const privateKey = env[exports.VAPID_ENV_KEYS.privateKey]?.trim() ?? '';
+    const rawSubject = env[exports.VAPID_ENV_KEYS.subject]?.trim() ?? '';
+    const presentKeys = [];
+    const missingKeys = [];
+    (publicKey ? presentKeys : missingKeys).push(exports.VAPID_ENV_KEYS.publicKey);
+    (privateKey ? presentKeys : missingKeys).push(exports.VAPID_ENV_KEYS.privateKey);
+    const subject = rawSubject || exports.VAPID_DEFAULT_SUBJECT;
+    const subjectSource = rawSubject ? 'env' : 'default';
+    const subjectIssue = classifyVapidSubject(subject);
+    if (rawSubject)
+        presentKeys.push(exports.VAPID_ENV_KEYS.subject);
+    const configured = publicKey !== '' && privateKey !== '';
+    const status = configured
+        ? subjectIssue === null
+            ? 'ok'
+            : 'invalid-subject'
+        : publicKey || privateKey
+            ? 'partial'
+            : 'unconfigured';
+    return {
+        status,
+        configured,
+        subject,
+        subjectSource,
+        subjectIssue,
+        presentKeys,
+        missingKeys,
+    };
+}
+/** Human-readable reason for a {@link VapidSubjectIssue}. */
+function describeSubjectIssue(issue) {
+    switch (issue) {
+        case 'unsupported-scheme':
+            return 'it is neither a "mailto:" address nor an "https://" URL (RFC 8292 allows only those two)';
+        case 'missing-host':
+            return 'it names no host at all';
+        case 'non-routable-host':
+            return 'its host cannot be resolved from the public internet (localhost, a bare name, or a reserved TLD)';
+    }
+}
+/**
+ * The startup / `status` report, as lines — shared by both surfaces so they can
+ * never drift apart, exactly as `formatLocalhostConflictWarning` is (#2113).
+ *
+ * **Returns an empty array when the configuration is healthy.** That silence is
+ * the negative control both Issues ask for: a correctly configured server prints
+ * nothing about push, so the presence of a line is itself the signal.
+ *
+ * Never includes a key or a private value. `subject` is printed because it is the
+ * value the operator has to fix, and it is a contact address rather than a
+ * credential — the module header's "never log the config" rule is about the keys.
+ */
+function formatVapidReportLines(inspection) {
+    switch (inspection.status) {
+        case 'ok':
+            return [];
+        case 'unconfigured':
+            return [
+                'Push notifications are disabled: no VAPID keys are configured.',
+                `  Set ${exports.VAPID_ENV_KEYS.publicKey} and ${exports.VAPID_ENV_KEYS.privateKey} to enable them.`,
+                '  "commandmate init" generates a key pair for you.',
+                '  Setup: docs/user-guide/webapp-guide.md ("Phone notifications")',
+            ];
+        case 'partial':
+            return [
+                `Push notifications are disabled: ${inspection.missingKeys.join(' and ')} ${inspection.missingKeys.length > 1 ? 'are' : 'is'} not set.`,
+                `  Both ${exports.VAPID_ENV_KEYS.publicKey} and ${exports.VAPID_ENV_KEYS.privateKey} are required;` +
+                    ' a key pair only works as a pair.',
+                '  "commandmate init" generates a key pair for you.',
+                '  Setup: docs/user-guide/webapp-guide.md ("Phone notifications")',
+            ];
+        case 'invalid-subject':
+            return [
+                `${exports.VAPID_ENV_KEYS.subject}="${inspection.subject}" will be rejected by Apple (APNs):` +
+                    ` ${describeSubjectIssue(inspection.subjectIssue)}.`,
+                '  iPhone/iPad receive nothing while Android keeps working, because FCM does not check it.',
+                `  Use a reachable contact, e.g. ${exports.VAPID_DEFAULT_SUBJECT} or mailto:you@your-domain.example.org.`,
+                `  Unset ${exports.VAPID_ENV_KEYS.subject} to fall back to ${exports.VAPID_DEFAULT_SUBJECT}.`,
+            ];
+    }
+}
+/**
+ * Run the startup self-check and print its verdict, or nothing when healthy.
+ *
+ * Fail-open by construction, the same contract `runLocalhostSelfCheck` carries:
+ * it never throws, it never blocks `listen`, and a healthy install is silent.
+ *
+ * @returns The inspection, or `null` when the check itself could not be carried
+ *   out (which is reported as nothing at all).
+ */
+function runVapidSelfCheck(options = {}) {
+    const { env = process.env, warn = (message) => console.warn(message) } = options;
+    try {
+        const inspection = inspectVapidConfig(env);
+        for (const line of formatVapidReportLines(inspection)) {
+            warn(line);
+        }
+        return inspection;
+    }
+    catch {
+        // A diagnostic must never be the reason a server fails to start.
+        return null;
+    }
+}
+/**
+ * Returns the VAPID config, or null when push is not configured (both public
+ * and private keys must be present). Read from env on every call.
+ */
+function getVapidConfig() {
+    const publicKey = process.env[exports.VAPID_ENV_KEYS.publicKey]?.trim();
+    const privateKey = process.env[exports.VAPID_ENV_KEYS.privateKey]?.trim();
+    if (!publicKey || !privateKey) {
+        return null;
+    }
+    const subject = process.env[exports.VAPID_ENV_KEYS.subject]?.trim() || exports.VAPID_DEFAULT_SUBJECT;
+    return { publicKey, privateKey, subject };
+}
+/** True when both VAPID keys are configured. */
+function isPushConfigured() {
+    return getVapidConfig() !== null;
+}
+/** The public (application server) key clients need to subscribe, or null. */
+function getVapidPublicKey() {
+    return getVapidConfig()?.publicKey ?? null;
+}

package/dist/lib/server/localhost-self-check.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Startup self-check: does the URL we tell users to open actually reach US?
+ * Issue #2113
+ *
+ * CommandMate binds IPv4 `127.0.0.1` by default (server.ts, `CM_BIND`), but every
+ * setup guide sends the user to `http://localhost:<port>`. On macOS `localhost`
+ * resolves `::1` (IPv6) BEFORE `127.0.0.1`, and a `0.0.0.0`/`::` bind of ours never
+ * covers `::1` either — so an unrelated process holding `::1:<port>` silently owns
+ * the address the docs advertise. The browser then talks to that process while
+ * CommandMate keeps reporting a healthy `> Ready on http://127.0.0.1:<port>`.
+ *
+ * Measured 2026-08-27 on develop 54e122a9: `127.0.0.1:3000` answered in 14ms while
+ * `localhost:3000` and `[::1]:3000` both timed out after 10s against a stray Next.js
+ * dev server. Because the squatter was also Next.js, the browser pulled chunks from
+ * the WRONG app and rendered CommandMate's own `error.chunkReload.title`
+ * ("Updating to the latest version") — an error screen that looks like ours while
+ * not being served by us at all.
+ *
+ * HOW IDENTITY IS DECIDED (the part that has to be exact):
+ *
+ * The probe sends a GET to `<protocol>://localhost:<port>/api/auth/status` carrying a
+ * one-shot random nonce in `x-cm-self-check`, and our own HTTP server carries a
+ * temporary `prependListener('request')` that watches for that nonce. The verdict comes
+ * from OUR OWN OBSERVATION of the request, never from trusting the response body:
+ *
+ *   observed the nonce            -> 'self'         (the advertised URL reaches us)
+ *   got an HTTP response, no nonce-> 'foreign'      (something else answered)  <- WARN
+ *   connection error / timeout    -> 'unreachable'  (nothing there; browsers fall
+ *                                                    through to 127.0.0.1)     <- silent
+ *
+ * `/api/auth/status` is deliberately an EXISTING endpoint (it is in
+ * AUTH_EXCLUDED_PATHS, touches no DB and mutates nothing), so no diagnostic route had
+ * to be added. Nothing in the verdict depends on what it returns, which is why the
+ * check still works with auth on, with an IP ACL that would 403 us, and against an
+ * HTTPS server with a self-signed certificate.
+ *
+ * FAIL-OPEN IS THE CONTRACT. Nothing here throws, nothing here blocks `listen`, and
+ * only the 'foreign' verdict produces output. 'unreachable' is deliberately silent:
+ * an empty `::1` is the NORMAL case on a machine where nothing squats the port, and
+ * Node's Happy Eyeballs (and every browser) then falls through to `127.0.0.1`.
+ *
+ * @module lib/server/localhost-self-check
+ */
+import { type IncomingMessage, type ServerResponse } from 'http';
+/** Header the probe request carries its nonce in */
+export declare const SELF_CHECK_HEADER = "x-cm-self-check";
+/**
+ * Endpoint the probe targets. Existing route, in AUTH_EXCLUDED_PATHS
+ * (src/config/auth-config.ts), no DB access, no side effects.
+ */
+export declare const SELF_CHECK_PATH = "/api/auth/status";
+/** Hostname the docs advertise, and therefore the one under test */
+export declare const SELF_CHECK_HOSTNAME = "localhost";
+/** How long to wait for either the nonce observation or a response */
+export declare const SELF_CHECK_TIMEOUT_MS = 3000;
+/**
+ * Directory (under the config dir) the conflict records live in.
+ *
+ * `logs/` and not a dedicated `self-check/`: in a local install `getConfigDir()` is the
+ * repository checkout itself, and `.gitignore` already ignores `logs/` there (it does
+ * the same for `data/`, `skills/`, `temp/` — "service-owned runtime state lands at the
+ * repo root"). A new top-level directory would show up as an untracked change in the
+ * user's own repository, which for a worktree manager means dirtying a repo it also
+ * displays. The record is diagnostic output keyed by port, so `logs/` fits it anyway.
+ */
+export declare const SELF_CHECK_DIR_NAME = "logs";
+/** Filename prefix of a conflict record inside {@link SELF_CHECK_DIR_NAME} */
+export declare const SELF_CHECK_FILE_PREFIX = "self-check-";
+/**
+ * What the startup probe concluded.
+ *
+ * Only `foreign` is actionable; see the module header for why `unreachable` is silent.
+ */
+export type LocalhostProbeVerdict = 'self' | 'foreign' | 'unreachable';
+/**
+ * The record a conflicted server leaves behind for `commandmate status`.
+ *
+ * `pid` is what makes the record trustworthy: `status` only reports it when it matches
+ * the PID it just read out of the state file, so a record left by an earlier server on
+ * the same port can never be attributed to the current one.
+ */
+export interface LocalhostConflictRecord {
+    /** Port the conflict was observed on */
+    port: number;
+    /** PID of the CommandMate server that observed it */
+    pid: number;
+    /** CM_BIND as configured */
+    bind: string;
+    /** URL CommandMate actually listens on */
+    boundUrl: string;
+    /** URL that was probed, i.e. the one the documentation advertises */
+    probedUrl: string;
+    /** ISO timestamp of the observation */
+    detectedAt: string;
+}
+/**
+ * The slice of `http.Server` the probe needs. Structural on purpose: tests hand it a
+ * real `http.Server`, and nothing here should be able to touch the rest of the server.
+ */
+export interface RequestObserver {
+    prependListener(event: 'request', listener: (req: IncomingMessage, res: ServerResponse) => void): unknown;
+    removeListener(event: 'request', listener: (req: IncomingMessage, res: ServerResponse) => void): unknown;
+}
+/** Options for {@link probeLocalhostIdentity} */
+export interface ProbeLocalhostOptions {
+    /** Our own HTTP(S) server, used to observe the probe request landing on us */
+    server: RequestObserver;
+    /** Port the server listens on */
+    port: number;
+    /** Protocol the server speaks (default: 'http') */
+    protocol?: 'http' | 'https';
+    /** Hostname to probe (default: {@link SELF_CHECK_HOSTNAME}); overridden in tests */
+    host?: string;
+    /** Request path (default: {@link SELF_CHECK_PATH}) */
+    path?: string;
+    /** Deadline for the whole probe (default: {@link SELF_CHECK_TIMEOUT_MS}) */
+    timeoutMs?: number;
+    /** Nonce override; generated per call when omitted */
+    nonce?: string;
+}
+/**
+ * Ask "if a user opens the URL we advertise, do they reach this process?".
+ *
+ * Resolves as soon as the answer is known — the nonce observation fires on our
+ * server's `request` event, i.e. when headers arrive, so a 'self' verdict does not
+ * wait for Next.js to render or compile the route.
+ *
+ * Never rejects.
+ */
+export declare function probeLocalhostIdentity(options: ProbeLocalhostOptions): Promise<LocalhostProbeVerdict>;
+/**
+ * Build the dialable URL for a bind address, matching resolveServerEndpoint()'s rule
+ * that a wildcard bind is reported as 127.0.0.1.
+ */
+export declare function formatBoundUrl(protocol: 'http' | 'https', bind: string, port: number): string;
+/**
+ * The warning, as lines, shared by the startup log and `commandmate status` so the two
+ * can never drift apart.
+ */
+export declare function formatLocalhostConflictWarning(record: LocalhostConflictRecord): string[];
+/** Directory holding the per-port conflict records */
+export declare function getSelfCheckDir(): string;
+/**
+ * Path of the record for one port (`<configDir>/logs/self-check-<port>.json`).
+ *
+ * @throws Error when the port is not a plausible TCP port — the value becomes a
+ *   filename, so it is validated rather than interpolated blindly.
+ */
+export declare function getSelfCheckStatePath(port: number): string;
+/**
+ * Persist a conflict for `commandmate status` to read.
+ *
+ * @returns true when the record was written
+ */
+export declare function writeLocalhostConflict(record: LocalhostConflictRecord): boolean;
+/**
+ * Read the conflict recorded for a port.
+ *
+ * Never throws: `status` must keep working on an unreadable, truncated or
+ * hand-edited record, and on a machine where the config dir cannot be resolved at all.
+ *
+ * @returns The record, or null when there is none (or it is unusable)
+ */
+export declare function readLocalhostConflict(port: number): LocalhostConflictRecord | null;
+/**
+ * Drop the record for a port. Called on every clean self-check and on shutdown, so a
+ * fixed environment stops warning on the next start rather than needing a manual sweep.
+ */
+export declare function clearLocalhostConflict(port: number): void;
+/** Options for {@link runLocalhostSelfCheck} */
+export interface RunLocalhostSelfCheckOptions {
+    /** Our own HTTP(S) server */
+    server: RequestObserver;
+    /** Port the server listens on */
+    port: number;
+    /** CM_BIND as configured */
+    bind: string;
+    /** Protocol the server speaks (default: 'http') */
+    protocol?: 'http' | 'https';
+    /** Hostname to probe (default: {@link SELF_CHECK_HOSTNAME}); overridden in tests */
+    host?: string;
+    /** Deadline for the probe */
+    timeoutMs?: number;
+    /** PID to stamp the record with (default: `process.pid`) */
+    pid?: number;
+    /** Clock, injectable for deterministic tests */
+    now?: () => Date;
+    /** Where the warning goes (default: `console.warn`) */
+    warn?: (message: string) => void;
+    /** Probe override, injected by tests */
+    probe?: (options: ProbeLocalhostOptions) => Promise<LocalhostProbeVerdict>;
+}
+/**
+ * Run the startup self-check and route its verdict to the log and the status file.
+ *
+ * Fail-open by construction: every path is wrapped, the function never rejects, and the
+ * caller in server.ts does not await it. A `null` return means the check could not be
+ * carried out at all — which is reported as nothing, exactly like 'unreachable'.
+ *
+ * @returns The verdict, or null when the check itself failed
+ */
+export declare function runLocalhostSelfCheck(options: RunLocalhostSelfCheckOptions): Promise<LocalhostProbeVerdict | null>;
+//# sourceMappingURL=localhost-self-check.d.ts.map