@riceawa/dsh-lan-gateway 0.5.4 → 0.5.5

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import z from "@deepseek-ai/schemastery";
-import { IncomingMessage, ServerResponse } from "node:http";
 import { Context } from "@deepseek-ai/cordis";
+import { IncomingMessage, ServerResponse } from "http";
 //#region src/index.d.ts
 /** Stable Cordis plugin name. */
 declare const name = "dsh-lan-gateway";
@@ -60,12 +60,17 @@ interface Config {
   /**
    * Removed capability: authentication is always required. Retained only so an
    * explicit legacy `authRequired: false` is rejected loudly instead of
-   * silently ignored.
+   * silently ignored. Not card-editable and never written back to the user
+   * section — the config route builds its patch from the editable key set.
    */
   authRequired?: boolean;
   /** Session cookie lifetime in days. */
   cookieMaxAgeDays: number;
-  /** Cookie name. */
+  /**
+   * Cookie name. Deliberately not card-editable — see the editable key set in
+   * `config-fields.ts`; the config route applies a patch, so an operator's
+   * custom name survives every save from the Settings card.
+   */
   cookieName: string;
   /** Whether the gateway listener speaks TLS. */
   tlsEnabled: boolean;
@@ -75,7 +80,13 @@ interface Config {
   tlsCertPath?: string;
   /** Custom mode: path to the PEM private key. */
   tlsKeyPath?: string;
-  /** Self-signed mode: comma/space separated DNS names and IPs for the SANs. */
+  /**
+   * Self-signed mode: comma/space separated DNS names and IPs for the SANs.
+   *
+   * Read when a certificate is generated, not when it is served: changing it
+   * does not replace a certificate that already exists and is still valid. Use
+   * `lan_gateway tls-regenerate` for that.
+   */
   tlsSelfSignedHosts?: string;
   /**
    * Self-signed certificate validity in days (default 825 ≈ 27 months).
@@ -88,6 +99,8 @@ interface Config {
    * self-signed certificate is either clicked through or trusted by hand,
    * there is nothing to gain from the shorter window and a re-trust to lose
    * every time it lapses.
+   *
+   * Like `tlsSelfSignedHosts`, this applies to the next generation only.
    */
   tlsCertMaxAgeDays: number;
   /**
@@ -99,6 +112,11 @@ interface Config {
    * An identifier for a trusted TLS-terminating proxy in front of the gateway.
    * Declaring one marks the ingress encrypted (Secure cookies, passes the
    * encrypted-ingress gate) without this listener sending HSTS.
+   *
+   * Note the coupling with login rate limiting: the limiter is keyed by
+   * `socket.remoteAddress`, and `X-Forwarded-For` is deliberately untrusted, so
+   * behind such a proxy every browser shares one bucket — the login budget
+   * becomes per-deployment, not per-client.
    */
   trustedTerminator?: string;
   /**
@@ -144,6 +162,27 @@ declare function resolveSecureCookies(cfg: Pick<Config, 'secureCookies' | 'tlsEn
  * used, and a state-changing method must carry that Origin. Exported for tests.
  */
 declare function isTrustedConfigRequest(req: IncomingMessage): boolean;
+/**
+ * Turn a submitted config patch into the next user section: only keys the card
+ * can edit, only real values, and `null` (or an emptied optional) removes the
+ * key rather than storing it.
+ *
+ * The patch is built from the *submitted* object, never from a schema call's
+ * output. Schemastery fills defaults into whatever it validates and passes
+ * unknown keys through, so deriving the section from `Config(submitted)` wrote
+ * `authRequired: true` (a capability that exists only to be refused) and any
+ * stray key into the user's settings on every save — and, because it also
+ * materialized `cookieName`, reset an operator's custom cookie name to the
+ * schema default.
+ *
+ * A `null` value is the card's clear: the key is dropped from the patch, which
+ * leaves it absent from the section, so it re-inherits the composition layer.
+ */
+declare function buildConfigPatch(submitted: Record<string, unknown>): {
+  patch: Record<string, unknown>;
+  clear: string[];
+  unknown: string[];
+};
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, GatewayController, StartFacts, ToolResult, UpstreamConnectionSurface, WebServerSurface, apply, gatewayStartProblems, inject, isTrustedConfigRequest, name, resolveSecureCookies };
+export { Config, GatewayController, StartFacts, ToolResult, UpstreamConnectionSurface, WebServerSurface, apply, buildConfigPatch, gatewayStartProblems, inject, isTrustedConfigRequest, name, resolveSecureCookies };