@camstack/system 1.2.114 → 1.2.116

package/dist/{retired-settings-keys-B52KsNz8.js → retired-settings-keys-BVAxT5XL.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-C1Aea3c6.js");
+const require_dist = require("./dist-Cri60Jd0.js");
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/{retired-settings-keys-C1efPfyW.mjs → retired-settings-keys-SrxMH3OT.mjs}

@@ -1,4 +1,4 @@
-import { kt as asJsonObject } from "./dist-CJ8RRSvQ.mjs";
+import { kt as asJsonObject } from "./dist-BpzbLPel.mjs";
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/tls/cert-evaluation.d.ts

@@ -0,0 +1,41 @@
+import { CertIdentity } from './cert-identity.js';
+/** OID `id-kp-serverAuth`. Apple's trustd requires it on the leaf. */
+export declare const SERVER_AUTH_OID = "1.3.6.1.5.5.7.3.1";
+/**
+ * Apple's `SecPolicyCheckOtherTrustValidityPeriod` ceiling is 825 days;
+ * the CA/Browser Forum's recommended maximum is 397. We sit at 397.
+ */
+export declare const MAX_LEAF_VALIDITY_DAYS = 397;
+/** Reissue this long before the leaf dies, so nobody serves an expired one. */
+export declare const LEAF_RENEWAL_WINDOW_DAYS = 30;
+/** A local root outlives many leaves — it is the anchor an operator trusts. */
+export declare const CA_VALIDITY_DAYS = 3650;
+/**
+ * The CA must outlive any leaf it signs by a margin, or a leaf issued
+ * today expires after its own issuer.
+ */
+export declare const CA_RENEWAL_WINDOW_DAYS: number;
+/**
+ * Why a reissue is happening. Reported on `EnsureTlsResult` and logged
+ * verbatim — an operator who trusted the old certificate by hand learns
+ * from this string, not from a browser error.
+ */
+export type CertRegenerationReason = 'missing' | 'unreadable' | 'no-local-ca' | 'ca-expiring' | 'key-mismatch' | 'expiring' | 'missing-server-auth-eku' | 'not-issued-by-local-ca' | 'validity-too-long' | 'san-coverage-gap';
+export interface CertEvaluationInput {
+    /** Contents of `camstack.crt` — leaf first, then the issuing CA. */
+    readonly chainPem: string;
+    /** Contents of `camstack.key` — the leaf's private key. */
+    readonly keyPem: string;
+    /** Contents of `camstack-ca.crt` — the local root. */
+    readonly caPem: string;
+    readonly identity: CertIdentity;
+    readonly now: Date;
+}
+export declare function reasonRequiresNewCa(reason: CertRegenerationReason): boolean;
+/**
+ * `null` when the material on disk is fit to keep serving.
+ *
+ * Order matters only for the quality of the reported reason; any
+ * non-null answer produces the same action.
+ */
+export declare function evaluateExistingCert(input: CertEvaluationInput): CertRegenerationReason | null;

package/dist/tls/cert-identity.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Names/addresses that go INTO the certificate, and the subset whose
+ * absence forces a reissue.
+ *
+ * The two are deliberately different sizes. Everything plausible is
+ * certified — costs nothing. Only a **stable** identity gates
+ * regeneration, because a gate that fires on a rotating address rewrites
+ * the certificate on every boot, which is a worse bug than the one the
+ * gate exists to fix.
+ */
+export interface CertIdentity {
+    readonly dnsNames: readonly string[];
+    readonly ipAddresses: readonly string[];
+    readonly requiredDnsNames: readonly string[];
+    readonly requiredIpAddresses: readonly string[];
+}
+export interface CertIdentityOptions {
+    readonly commonName: string;
+    readonly extraSans: readonly string[];
+}
+export declare function isIpv4(value: string): boolean;
+export declare function isIpv6(value: string): boolean;
+/**
+ * `fe80::/10` and `169.254.0.0/16`. An IPv6 link-local address needs a
+ * zone index to be usable and a SAN cannot carry one, so such an entry
+ * can never match anything — it is noise that makes the certificate look
+ * broader than it is.
+ */
+export declare function isLinkLocal(value: string): boolean;
+/** `fc00::/7` — the IPv6 range that behaves like RFC 1918 does for v4. */
+export declare function isUniqueLocalIpv6(value: string): boolean;
+/**
+ * Snapshot the machine's identity. Called once per `ensureTlsCert`; the
+ * result is both the SAN list for a new leaf and the yardstick the
+ * existing leaf is measured against.
+ */
+export declare function collectCertIdentity(options: CertIdentityOptions): CertIdentity;

package/dist/tls/cert-manager.d.ts

@@ -1,26 +1,91 @@
+import { CertRegenerationReason, evaluateExistingCert, MAX_LEAF_VALIDITY_DAYS } from './cert-evaluation.js';
+import { CertIdentity, collectCertIdentity } from './cert-identity.js';
 export interface TlsCertPair {
     readonly cert: Buffer;
     readonly key: Buffer;
 }
 export interface EnsureTlsResult {
+    /** Full chain — leaf then CA. This is what the listener serves. */
     readonly certPath: string;
+    /** The leaf's private key. */
     readonly keyPath: string;
+    /** The local root. **This** is the file an operator installs as trusted. */
+    readonly caCertPath: string;
+    readonly caKeyPath: string;
     readonly generated: boolean;
+    /** Why it was reissued — `null` when the existing material was kept. */
+    readonly reason: CertRegenerationReason | null;
+    /** True when the ROOT rotated, i.e. trust granted by hand is now void. */
+    readonly caRotated: boolean;
+    readonly fingerprintSha256: string;
+    readonly caFingerprintSha256: string;
+    /** Fingerprint of the leaf this one replaced — `null` on a fresh install. */
+    readonly previousFingerprintSha256: string | null;
+    /** ISO timestamp at which the leaf stops being valid. */
+    readonly validTo: string;
+    readonly sans: readonly string[];
+    /**
+     * Set when a reissue was needed and FAILED, and the previous material is
+     * still being served. Never null-and-degraded silently: this is the line
+     * that says the certificate is not what the rule wants it to be.
+     */
+    readonly reissueError: string | null;
 }
 export interface CertOptions {
-    /** Common Name for the cert (default: 'camstack.local') */
+    /** Common Name for the leaf (default: 'camstack.local') */
     readonly commonName?: string;
-    /** Validity in days (default: 825 — max for browsers) */
+    /** Leaf validity in days. Clamped to `MAX_LEAF_VALIDITY_DAYS`. */
     readonly validDays?: number;
-    /** Additional SANs (DNS names or IPs) */
+    /** Additional SANs (DNS names or IPs). Required coverage by definition. */
     readonly extraSans?: readonly string[];
 }
 /**
- * Ensure a self-signed TLS certificate exists in the given directory.
- * Generates one if missing. Returns paths to cert and key files.
+ * Ensure the hub has a usable TLS identity under `<dataDir>/tls`, made of
+ * a long-lived local **root** (`camstack-ca.crt`) and a short **leaf**
+ * chained to it (`camstack.crt` = leaf + root, `camstack.key`).
+ *
+ * ## The regeneration rule (D227)
+ *
+ * Reissue happens when, and only when, the material on disk **cannot do
+ * its job**:
+ *
+ * - it is absent, unreadable, or the key does not match the certificate;
+ * - the root is absent (every pre-2026-08 install: one self-signed
+ *   `CA:TRUE` leaf and no root) or is inside its renewal window;
+ * - the leaf is inside its 30-day renewal window;
+ * - the leaf lacks `extendedKeyUsage = serverAuth` — Apple's trustd
+ *   rejects an app-supplied anchor without it;
+ * - the leaf is not actually issued by the root on disk;
+ * - the leaf's validity span exceeds {@link MAX_LEAF_VALIDITY_DAYS};
+ * - **a name or address the hub must answer for is missing from the SAN
+ *   list** — a DHCP move, a new interface or a new hostname.
+ *
+ * And explicitly NOT when: the certificate names an address the machine
+ * no longer has (a superset still works — the check is one-directional),
+ * a volatile interface (docker/VPN/mesh) or a global-scope IPv6 address
+ * changed (SLAAC privacy addresses rotate daily), or a new build shipped.
+ *
+ * Every trigger is derived from the files plus the machine, so once a
+ * reissue clears them it clears them for good: the next boot returns
+ * `generated: false`. A certificate that moved on every boot would
+ * invalidate every trust an operator granted by hand — worse than the
+ * bugs this rule fixes.
+ *
+ * **The root is rotated only for root-level reasons.** SAN drift rotates
+ * the leaf alone, so trust granted to `camstack-ca.crt` survives every
+ * address change the hub will ever see.
  */
 export declare function ensureTlsCert(dataDir: string, options?: CertOptions): Promise<EnsureTlsResult>;
 /**
- * Load TLS cert+key from files. Returns Buffers suitable for Node.js TLS options.
+ * Operator "Regenerate": issue a new leaf under the existing local CA.
+ * Never rotates the root — trust granted to `camstack-ca.crt` survives.
+ */
+export declare function reissueTlsLeaf(dataDir: string, options?: CertOptions): Promise<EnsureTlsResult>;
+/**
+ * Load TLS cert+key from files. Returns Buffers suitable for Node.js TLS
+ * options. `certPath` is a full chain, so the listener presents the local
+ * root alongside the leaf.
  */
 export declare function loadTlsCert(certPath: string, keyPath: string): TlsCertPair;
+export type { CertIdentity, CertRegenerationReason };
+export { collectCertIdentity, evaluateExistingCert, MAX_LEAF_VALIDITY_DAYS };

package/dist/tls/cert-openssl.d.ts

@@ -0,0 +1,23 @@
+import { CertIdentity } from './cert-identity.js';
+/** Subject of the local root. Distinct from the leaf's CN by construction. */
+export declare const CA_COMMON_NAME = "CamStack Local CA";
+export interface CaMaterialPaths {
+    readonly caCertPath: string;
+    readonly caKeyPath: string;
+}
+export interface LeafMaterialPaths {
+    readonly certPath: string;
+    readonly keyPath: string;
+}
+/**
+ * A local root: 10 years, `pathlen:0` so it can sign leaves and nothing
+ * else, and **no EKU** — Apple rejects an anchor asserting
+ * `anyExtendedKeyUsage`, and a root with no EKU constrains nothing.
+ */
+export declare function generateCa(tmpDir: string): Promise<CaMaterialPaths>;
+/**
+ * A server leaf signed by the local root: `CA:FALSE`, and
+ * `extendedKeyUsage=serverAuth` — not `anyExtendedKeyUsage`, which
+ * Apple's `testAppTrustRoot_AnyEKU_AfterJul2019` asserts must fail.
+ */
+export declare function issueLeaf(tmpDir: string, ca: CaMaterialPaths, identity: CertIdentity, commonName: string, validDays: number): Promise<LeafMaterialPaths>;

package/dist/tls/index.d.ts

@@ -1 +1,5 @@
-export { ensureTlsCert, loadTlsCert, type TlsCertPair, type EnsureTlsResult, type CertOptions, } from './cert-manager.js';
+export { CA_VALIDITY_DAYS, type CertEvaluationInput, LEAF_RENEWAL_WINDOW_DAYS, SERVER_AUTH_OID, } from './cert-evaluation.js';
+export { type CertIdentity, type CertOptions, type CertRegenerationReason, collectCertIdentity, type EnsureTlsResult, ensureTlsCert, reissueTlsLeaf, evaluateExistingCert, loadTlsCert, MAX_LEAF_VALIDITY_DAYS, type TlsCertPair, } from './cert-manager.js';
+export { CA_COMMON_NAME } from './cert-openssl.js';
+export { validateUploadedTls, type UploadedTlsValidation } from './uploaded-cert.js';
+export { type TlsAccessStatus, readTlsAccessStatus, writeTlsMode, readTlsMode, readExtraSans, writeExtraSans, } from './tls-status.js';

package/dist/tls/tls-status.d.ts

@@ -0,0 +1,16 @@
+export type TlsMode = 'generated' | 'uploaded' | 'disabled';
+export interface TlsAccessStatus {
+    readonly mode: TlsMode;
+    readonly leafFingerprintSha256: string | null;
+    readonly caFingerprintSha256: string | null;
+    readonly validTo: string | null;
+    readonly sans: readonly string[];
+    readonly caCertPem: string | null;
+    readonly reissueError: string | null;
+    readonly restartRequired: boolean;
+}
+export declare function readTlsMode(dataDir: string): TlsMode;
+export declare function writeTlsMode(dataDir: string, mode: TlsMode): void;
+export declare function readExtraSans(dataDir: string): readonly string[];
+export declare function writeExtraSans(dataDir: string, sans: readonly string[]): void;
+export declare function readTlsAccessStatus(dataDir: string, restartRequired?: boolean): TlsAccessStatus;

package/dist/tls/uploaded-cert.d.ts

@@ -0,0 +1,14 @@
+export type UploadedTlsValidation = {
+    readonly ok: true;
+    readonly fingerprintSha256: string;
+    readonly validTo: string;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+/**
+ * Operator-supplied material must parse, match its key, and carry
+ * `extendedKeyUsage = serverAuth` — the same leaf defects D227 refused
+ * to keep generating.
+ */
+export declare function validateUploadedTls(certPem: string, keyPem: string): UploadedTlsValidation;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.114",
+  "version": "1.2.116",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",

package/dist/{manifest-python-deps-MA_BZGBz.js → manifest-python-deps-CwBbX4Ut.js}

@@ -17,8 +17,8 @@ node_v8 = require_chunk.__toESM(node_v8);
 let node_vm = require("node:vm");
 node_vm = require_chunk.__toESM(node_vm);
 let _camstack_types_addon = require("@camstack/types/addon");
-let _trpc_client = require("@trpc/client");
 let node_net = require("node:net");
+let _trpc_client = require("@trpc/client");
 //#region src/kernel/heap-watch.ts
 /**
 * heap-watch — hub-main's own memory, on the record, and returned to the OS.

package/dist/{manifest-python-deps-Cb1ANt3i.mjs → manifest-python-deps-SGdbr9D5.mjs}

@@ -13,8 +13,8 @@ import { createServer } from "node:http";
 import * as v8 from "node:v8";
 import * as vm from "node:vm";
 import { BOOT_RECOVERY_BACKOFF_MS, DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, asJsonObject, asString, createDeviceProxy, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, readNodePin, scopeKey, sleep, withCapInputDefaults } from "@camstack/types/addon";
-import { TRPCClientError, createTRPCClient } from "@trpc/client";
 import { connect, createServer as createServer$1 } from "node:net";
+import { TRPCClientError, createTRPCClient } from "@trpc/client";
 //#region src/kernel/heap-watch.ts
 /**
 * heap-watch — hub-main's own memory, on the record, and returned to the OS.