@riceawa/dsh-lan-gateway 0.4.0 → 0.5.0

package/lib/index.d.ts

@@ -16,9 +16,15 @@ interface WebServerSurface {
     handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
   }): () => void;
 }
+/** Minimal surface of the dsh client-connection service (session-capable bases). */
+interface UpstreamConnectionSurface {
+  /** A root URL for the upstream origin carrying the process launch token. */
+  authenticatedUrl(baseUrl: string): string;
+}
 declare module '@deepseek-ai/cordis' {
   interface Context {
     webServer: WebServerSurface;
+    connection: UpstreamConnectionSurface;
   }
 }
 /** One command result returned to the model. */
@@ -31,7 +37,7 @@ interface GatewayController {
   status(): ToolResult;
   enable(): Promise<ToolResult>;
   disable(): Promise<ToolResult>;
-  setPassword(password: string | undefined): ToolResult;
+  setPassword(password: string | undefined): Promise<ToolResult>;
   rotateSecret(): ToolResult;
   regenerateTls(): Promise<ToolResult>;
 }
@@ -43,10 +49,20 @@ interface Config {
   gatewayPort: number;
   /** Explicit dsh target port; defaults to the live `ctx.webServer.port`. */
   dshTargetPort?: number;
-  /** LAN CIDRs treated as password-free. */
+  /** LAN CIDRs that may be treated as trusted when `lanPasswordless` is on. */
   lanCidrs: string[];
-  /** Whether non-LAN sources must authenticate. */
-  authRequired: boolean;
+  /**
+   * Opt-in (default false): let LAN/loopback sources skip the gateway login.
+   * Only allowed against a session-capable dsh base, where upstream auth still
+   * gates every request via the relayed shared session.
+   */
+  lanPasswordless: boolean;
+  /**
+   * Removed capability: authentication is always required. Retained only so an
+   * explicit legacy `authRequired: false` is rejected loudly instead of
+   * silently ignored.
+   */
+  authRequired?: boolean;
   /** Session cookie lifetime in days. */
   cookieMaxAgeDays: number;
   /** Cookie name. */
@@ -63,9 +79,40 @@ interface Config {
   tlsSelfSignedHosts?: string;
   /** Self-signed certificate validity in days (default 825 ≈ 27 months). */
   tlsCertMaxAgeDays: number;
+  /**
+   * Escape hatch (default false): permit plaintext HTTP. Never derived from
+   * `X-Forwarded-Proto` — the operator declares it.
+   */
+  allowInsecurePlaintext: boolean;
+  /**
+   * 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.
+   */
+  trustedTerminator?: string;
 }
 /** Schemastery configuration validated by the Loader. */
 declare const Config: z<Config>;
+/** Facts the fail-closed start guard needs to judge a config. */
+interface StartFacts {
+  /** Whether the dsh base enforces browser-session auth (auto-detected). */
+  upstreamSessionAvailable: boolean;
+}
+/**
+ * The fail-closed problems that prevent a config from enabling the listener.
+ * Returns every problem (not just the first) so the operator sees the full
+ * migration at once. Exported for tests.
+ */
+declare function gatewayStartProblems(cfg: Config, facts: StartFacts): string[];
+/**
+ * Same-origin loopback fence for the native `/lan-gateway/config` route. The
+ * gateway refuses to relay this prefix, so the only way in is the native
+ * loopback listener itself (a genuine local user, or a local process that could
+ * already read `~/.dsh`). Host must be loopback (also blocks DNS rebinding),
+ * cross-site fetches are refused, an Origin must match the Host the browser
+ * used, and a state-changing method must carry that Origin. Exported for tests.
+ */
+declare function isTrustedConfigRequest(req: IncomingMessage): boolean;
 declare function apply(ctx: Context, config: Config): void;
 //#endregion
-export { Config, GatewayController, ToolResult, WebServerSurface, apply, inject, name };
+export { Config, GatewayController, StartFacts, ToolResult, UpstreamConnectionSurface, WebServerSurface, apply, gatewayStartProblems, inject, isTrustedConfigRequest, name };