@camstack/system 1.2.113 → 1.2.115

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

@@ -1,26 +1,80 @@
+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[];
 }
 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.
+ * 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,3 @@
-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, evaluateExistingCert, loadTlsCert, MAX_LEAF_VALIDITY_DAYS, type TlsCertPair, } from './cert-manager.js';
+export { CA_COMMON_NAME } from './cert-openssl.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.113",
+  "version": "1.2.115",
   "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.