@riceawa/dsh-lan-gateway 0.5.5 → 0.6.1

package/lib/index.js

@@ -1897,33 +1897,91 @@ const name = "dsh-lan-gateway";
 /** Requires the web server service (binds before this row's apply runs) and the tool registry. */
 const inject = ["webServer", "tools"];
 /**
-* The `lan-gateway` user-settings namespace, mirroring the composition schema.
-* A plain string literal: dsh-settings dropped the `settingsNamespace()` brand
-* helper in 0.1.2-rc.1 and `register` validates the literal itself, so this
-* shape works against both that release line and the older branded one.
+* Schemastery configuration validated by the Loader.
+*
+* Every field is `.volatile()`, which is what lets the Settings service write
+* it: 0.1.7 projects only volatile fields into forms and refuses an edit to any
+* other path (`not volatile`). The mark also changes the runtime shape — a
+* volatile field arrives as a reference (see `ConfigRefs`), never as the plain
+* value the rest of this file expects — so read it through `readConfig`.
 */
-const NS = "lan-gateway";
-/** Schemastery configuration validated by the Loader. */
 const Config = z.object({
-	enabled: z.boolean().default(false),
-	gatewayPort: z.natural().min(1).max(65535).default(3081),
-	dshTargetPort: z.natural().min(1).max(65535),
-	lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]),
-	lanPasswordless: z.boolean().default(false),
-	authRequired: z.boolean().default(true),
-	cookieMaxAgeDays: z.natural().min(1).max(365).default(7),
-	cookieName: z.string().default("dsh_gw_auth"),
-	tlsEnabled: z.boolean().default(false),
-	tlsMode: z.union([z.const("self-signed"), z.const("custom")]).default("self-signed"),
-	tlsCertPath: z.string(),
-	tlsKeyPath: z.string(),
-	tlsSelfSignedHosts: z.string().default("localhost"),
-	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825),
-	allowInsecurePlaintext: z.boolean().default(false),
-	trustedTerminator: z.string(),
-	secureCookies: z.boolean()
+	enabled: z.boolean().default(false).volatile(),
+	gatewayPort: z.natural().min(1).max(65535).default(3081).volatile(),
+	dshTargetPort: z.natural().min(1).max(65535).volatile(),
+	lanCidrs: z.array(String).default([...DEFAULT_LAN_CIDR_STRINGS]).volatile(),
+	lanPasswordless: z.boolean().default(false).volatile(),
+	authRequired: z.boolean().default(true).volatile(),
+	cookieMaxAgeDays: z.natural().min(1).max(365).default(7).volatile(),
+	cookieName: z.string().default("dsh_gw_auth").volatile(),
+	tlsEnabled: z.boolean().default(false).volatile(),
+	tlsMode: z.union([z.const("self-signed"), z.const("custom")]).default("self-signed").volatile(),
+	tlsCertPath: z.string().volatile(),
+	tlsKeyPath: z.string().volatile(),
+	tlsSelfSignedHosts: z.string().default("localhost").volatile(),
+	tlsCertMaxAgeDays: z.natural().min(1).max(3650).default(825).volatile(),
+	allowInsecurePlaintext: z.boolean().default(false).volatile(),
+	trustedTerminator: z.string().volatile(),
+	secureCookies: z.boolean().volatile()
 });
 /**
+* Unwrap the config references into the plain values every other function in
+* this file reads. Called on each access rather than once, because a settings
+* write updates the references in place.
+* @param refs - the config object handed to `apply`.
+* @returns one detached plain snapshot.
+*/
+function readConfig(refs) {
+	const dshTargetPort = refs.dshTargetPort?.get();
+	const authRequired = refs.authRequired?.get();
+	const tlsCertPath = refs.tlsCertPath?.get();
+	const tlsKeyPath = refs.tlsKeyPath?.get();
+	const tlsSelfSignedHosts = refs.tlsSelfSignedHosts?.get();
+	const trustedTerminator = refs.trustedTerminator?.get();
+	const secureCookies = refs.secureCookies?.get();
+	return {
+		enabled: refs.enabled.get(),
+		gatewayPort: refs.gatewayPort.get(),
+		lanCidrs: [...refs.lanCidrs.get()],
+		lanPasswordless: refs.lanPasswordless.get(),
+		cookieMaxAgeDays: refs.cookieMaxAgeDays.get(),
+		cookieName: refs.cookieName.get(),
+		tlsEnabled: refs.tlsEnabled.get(),
+		tlsMode: refs.tlsMode.get(),
+		tlsCertMaxAgeDays: refs.tlsCertMaxAgeDays.get(),
+		allowInsecurePlaintext: refs.allowInsecurePlaintext.get(),
+		...dshTargetPort !== void 0 ? { dshTargetPort } : {},
+		...authRequired !== void 0 ? { authRequired } : {},
+		...tlsCertPath !== void 0 ? { tlsCertPath } : {},
+		...tlsKeyPath !== void 0 ? { tlsKeyPath } : {},
+		...tlsSelfSignedHosts !== void 0 ? { tlsSelfSignedHosts } : {},
+		...trustedTerminator !== void 0 ? { trustedTerminator } : {},
+		...secureCookies !== void 0 ? { secureCookies } : {}
+	};
+}
+/**
+* Build the reference-shaped config `apply` receives, exactly as the Loader
+* builds it. Exported for tests that drive `apply` directly.
+* @param raw - a config object; missing fields take their schema defaults.
+* @returns one reference per volatile field.
+*/
+function configRefs(raw) {
+	return Config(raw);
+}
+/**
+* Validate a raw config object the way the Loader does, and unwrap it.
+*
+* `Config` marks every field volatile, so a validation hands the values back as
+* references (typed deeply-readonly by schemastery); this returns the plain
+* shape the rest of the file reads. Used to judge a config the Settings card is
+* about to save, before it is persisted.
+* @param raw - a config object; missing fields take their schema defaults.
+* @returns the validated plain config.
+*/
+function validateConfig(raw) {
+	return readConfig(configRefs(raw));
+}
+/**
 * 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.
@@ -2101,16 +2159,18 @@ function apply(ctx, config) {
 	let connectionGeneration = 0;
 	/** Builds a fresh shared-session relay for a dsh port, once the base supports sessions. */
 	let makeRelay;
-	/** The authoritative config: settings section when attached, else composition. */
-	let configSource = () => config;
-	/** Whether writes go to the settings section rather than staying in memory. */
+	/** Whether the settings service is attached, so writes reach the profile entry. */
 	let settingsAttached = false;
-	/** The settings scope for the `lan-gateway` namespace, while one is attached. */
-	let settingsScope;
 	/**
-	* The settings provider, for the one write a scope cannot express: a section
-	* key must be *removed* to re-inherit the composition layer, and only the
-	* provider's path-addressed `mutate` can unset one.
+	* This plugin's own Loader entry id. dsh 0.1.7 addresses a settings write by
+	* the *entry id* — the `lan-gateway` namespace this plugin used to register
+	* with is gone along with `settingsScope`.
+	*/
+	let settingsEntryId;
+	/**
+	* The settings service, for the one write a merge patch cannot express: a key
+	* must be *removed* to re-inherit the composition layer, and only its
+	* path-addressed `mutate` can unset one.
 	*/
 	let settingsProvider;
 	/**
@@ -2121,7 +2181,7 @@ function apply(ctx, config) {
 	let lifecycle = Promise.resolve();
 	/** Set by the dispose hook; a start that completes after it must undo itself. */
 	let disposed = false;
-	const effective = () => configSource();
+	const effective = () => readConfig(config);
 	/** Queue one lifecycle action behind every action already running. */
 	const enqueue = (reason, action) => {
 		lifecycle = lifecycle.then(action).catch((error) => {
@@ -2198,26 +2258,62 @@ function apply(ctx, config) {
 			}
 		});
 	};
-	/** Record the run intent where it will survive: the settings section, or memory. */
+	/** Record the run intent where it will survive: the profile entry, or memory. */
 	const setRunIntent = async (enabled) => {
-		if (settingsAttached && settingsScope !== void 0) {
-			await settingsScope.update({ enabled });
+		if (settingsAttached && settingsProvider !== void 0 && settingsEntryId !== void 0) {
+			await settingsProvider.update(settingsEntryId, { enabled });
 			return;
 		}
 		manualOverride = enabled;
 	};
+	/**
+	* Apply a login-password change and reconcile the listener. One
+	* implementation behind both surfaces the operator has — the `lan_gateway`
+	* tool's `set-password` command and the Settings card's
+	* `/lan-gateway/password` route — so the epoch bump, the listener stop on a
+	* clear, and the first-password reconcile cannot diverge between them.
+	*
+	* The credential itself is never read back out: `state` holds a scrypt hash
+	* and salt, and neither is returned to a caller.
+	*/
+	const applyPassword = async (password) => {
+		if (password !== void 0 && password.length > 0 && password.length < 8) return {
+			ok: false,
+			message: `Password must be at least 8 characters.`
+		};
+		const setting = password !== void 0 && password.length > 0;
+		const hadPassword = state.password !== void 0;
+		state = await setPassword(state, setting ? password : void 0);
+		saveState(state);
+		gateway?.setState(state);
+		if (!setting) {
+			await setRunIntent(false);
+			return enqueue("password cleared", async () => {
+				if (gateway !== void 0) await stopGateway();
+				lastError = "Password cleared — the gateway listener was stopped (a password is required to run).";
+			}).then(() => ({
+				ok: true,
+				message: "Password cleared. Session epoch advanced and the gateway listener was stopped — set a password before enabling it again."
+			}));
+		}
+		if (!hadPassword) await syncGateway("password set");
+		return {
+			ok: true,
+			message: "Password set. Session epoch advanced — every previously issued session is now invalid; all sources must sign in again."
+		};
+	};
 	ctx.inject(["settings"], (sctx) => {
-		const scope = sctx.settings.register(NS, Config, { base: config });
-		settingsScope = scope;
+		const entryId = ctx.fiber.entry?.options.id;
+		if (entryId === void 0) return;
+		settingsEntryId = entryId;
 		settingsProvider = sctx.settings;
 		settingsAttached = true;
-		configSource = () => scope.get();
-		sctx.effect(() => scope.watch(() => {
+		sctx.effect(() => sctx.settings.configure({ auto: false }, ctx.fiber));
+		sctx.effect(() => ctx.on("loader/volatile-update", () => {
 			syncGateway("settings change");
 		}));
 		sctx.effect(() => () => {
-			configSource = () => config;
-			settingsScope = void 0;
+			settingsEntryId = void 0;
 			settingsProvider = void 0;
 			settingsAttached = false;
 			syncGateway("settings detach");
@@ -2241,22 +2337,29 @@ function apply(ctx, config) {
 		});
 		syncGateway("connection attach");
 	});
-	const configRouteHandler = async (req, res) => {
-		const snapshot = () => {
-			const cfg = effective();
-			return {
-				config: cfg,
-				running: gateway !== void 0,
-				port: cfg.gatewayPort,
-				tls: tlsStatusLine(cfg),
-				upstreamSessionAvailable,
-				lastError: lastError ?? null
-			};
-		};
-		const send = (status, body) => {
-			res.writeHead(status, { "content-type": "application/json" });
-			res.end(JSON.stringify(body));
+	const sendJson = (res, status, body) => {
+		res.writeHead(status, { "content-type": "application/json" });
+		res.end(JSON.stringify(body));
+	};
+	/**
+	* What both card routes report. `passwordSet` is a boolean on purpose: the
+	* card must be able to say whether a credential exists without any part of
+	* that credential — not even its length — ever leaving this process.
+	*/
+	const snapshot = () => {
+		const cfg = effective();
+		return {
+			config: cfg,
+			running: gateway !== void 0,
+			port: cfg.gatewayPort,
+			tls: tlsStatusLine(cfg),
+			upstreamSessionAvailable,
+			passwordSet: state.password !== void 0,
+			lastError: lastError ?? null
 		};
+	};
+	const configRouteHandler = async (req, res) => {
+		const send = (status, body) => sendJson(res, status, body);
 		if (!isTrustedConfigRequest(req)) {
 			send(403, { error: "request refused: this route answers same-origin loopback requests only" });
 			return;
@@ -2282,12 +2385,14 @@ function apply(ctx, config) {
 			send(400, { error: "body must be a config object" });
 			return;
 		}
-		if (settingsProvider === void 0) {
+		const settings = settingsProvider;
+		const entryId = settingsEntryId;
+		if (settings === void 0 || entryId === void 0) {
 			send(409, { error: "settings service unavailable — edit the profile patch (cordis.patch.yml) instead" });
 			return;
 		}
 		const { patch, clear, unknown } = buildConfigPatch(submitted);
-		const candidate = Config({
+		const candidate = validateConfig({
 			...effective(),
 			...patch
 		});
@@ -2306,7 +2411,7 @@ function apply(ctx, config) {
 				op: "unset",
 				path: [key]
 			}))];
-			if (ops.length > 0) await settingsProvider.mutate(NS, ops);
+			if (ops.length > 0) await settings.mutate(entryId, ops);
 			await syncGateway("config route save");
 			const next = { ...snapshot() };
 			if (unknown.length > 0) next["ignored"] = unknown;
@@ -2320,7 +2425,42 @@ function apply(ctx, config) {
 		path: "/lan-gateway/config",
 		handler: configRouteHandler
 	}), "dsh-lan-gateway: config route");
-	ctx.tools.register(lanGatewayTool({
+	const passwordRouteHandler = async (req, res) => {
+		if (!isTrustedConfigRequest(req)) {
+			sendJson(res, 403, { error: "request refused: this route answers same-origin loopback requests only" });
+			return;
+		}
+		if (req.method !== "POST") {
+			sendJson(res, 405, { error: "method not allowed" });
+			return;
+		}
+		const body = await readBody(req, 4096, res);
+		if (body === void 0) return;
+		let submitted;
+		try {
+			submitted = JSON.parse(body);
+		} catch {
+			sendJson(res, 400, { error: "invalid JSON body" });
+			return;
+		}
+		const password = typeof submitted === "object" && submitted !== null && !Array.isArray(submitted) ? submitted["password"] : void 0;
+		if (typeof password !== "string" || password.length === 0) {
+			sendJson(res, 400, { error: `password must be a non-empty string of at least 8 characters; this route only sets one — use the lan_gateway tool to clear it` });
+			return;
+		}
+		const result = await applyPassword(password);
+		if (!result.ok) {
+			sendJson(res, 400, { error: result.message });
+			return;
+		}
+		sendJson(res, 200, snapshot());
+	};
+	ctx.effect(() => ctx.webServer.register({
+		kind: "exact",
+		path: "/lan-gateway/password",
+		handler: passwordRouteHandler
+	}), "dsh-lan-gateway: password route");
+	const controller = {
 		status() {
 			const cfg = desiredConfig();
 			const dshPort = cfg.dshTargetPort ?? ctx.webServer.port;
@@ -2349,32 +2489,7 @@ function apply(ctx, config) {
 				message: "Gateway disabled."
 			};
 		},
-		async setPassword(password) {
-			if (password !== void 0 && password.length > 0 && password.length < 8) return {
-				ok: false,
-				message: "Password must be at least 8 characters."
-			};
-			const setting = password !== void 0 && password.length > 0;
-			const hadPassword = state.password !== void 0;
-			state = await setPassword(state, setting ? password : void 0);
-			saveState(state);
-			gateway?.setState(state);
-			if (!setting) {
-				await setRunIntent(false);
-				return enqueue("password cleared", async () => {
-					if (gateway !== void 0) await stopGateway();
-					lastError = "Password cleared — the gateway listener was stopped (a password is required to run).";
-				}).then(() => ({
-					ok: true,
-					message: "Password cleared. Session epoch advanced and the gateway listener was stopped — set a password before enabling it again."
-				}));
-			}
-			if (!hadPassword) await syncGateway("password set");
-			return {
-				ok: true,
-				message: "Password set. Session epoch advanced — every previously issued session is now invalid; all sources must sign in again."
-			};
-		},
+		setPassword: applyPassword,
 		rotateSecret() {
 			const next = {
 				cookieSecret: randomBytes(32).toString("base64"),
@@ -2424,7 +2539,8 @@ function apply(ctx, config) {
 				message: `Failed to regenerate TLS certificate: ${failure}`
 			};
 		}
-	}));
+	};
+	ctx.tools.register(lanGatewayTool(controller));
 	ctx.effect(() => {
 		syncGateway("boot");
 		return async () => {
@@ -2434,4 +2550,4 @@ function apply(ctx, config) {
 	}, "dsh-lan-gateway: listener lifecycle");
 }
 //#endregion
-export { Config, apply, buildConfigPatch, gatewayStartProblems, inject, isTrustedConfigRequest, name, resolveSecureCookies };
+export { Config, apply, buildConfigPatch, configRefs, gatewayStartProblems, inject, isTrustedConfigRequest, name, readConfig, resolveSecureCookies, validateConfig };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@riceawa/dsh-lan-gateway",
-  "description": "LAN/internet reverse-proxy gateway for the DeepSeek Harness web GUI: binds 0.0.0.0 and forwards to the loopback dsh web server. Default-deny: every source (loopback, LAN, internet) must sign in with an HMAC session cookie unless lanPasswordless is explicitly enabled; against dsh >= 0.1.2-rc.1 the gateway relays one shared upstream browser session, so the harness's own authorization still gates every request. Fail-closed start guard (password required, plaintext needs an explicit opt-in), session revocation by epoch (password changes and secret rotation kill cookies and live WebSockets), same-site/Origin fence on HTTP and WebSocket upgrades, optional TLS (auto self-signed or user-supplied certs), and a Settings → Plugins card for live adjustment of port, CIDRs, auth, and TLS. Includes an insecure-origin UUID shim client bundle: on gateway-served plain-HTTP origins browsers lack crypto.randomUUID, so the client half patches a getRandomValues-backed randomUUID onto the Crypto prototype, fixing workspace open over LAN without touching DSH source.",
-  "version": "0.5.5",
+  "description": "LAN/internet reverse-proxy gateway for the DeepSeek Harness web GUI: binds 0.0.0.0 and forwards to the loopback dsh web server. Default-deny: every source (loopback, LAN, internet) must sign in with an HMAC session cookie unless lanPasswordless is explicitly enabled; against dsh >= 0.1.2-rc.1 the gateway relays one shared upstream browser session, so the harness's own authorization still gates every request. Fail-closed start guard (password required, plaintext needs an explicit opt-in), session revocation by epoch (password changes and secret rotation kill cookies and live WebSockets), same-site/Origin fence on HTTP and WebSocket upgrades, optional TLS (auto self-signed or user-supplied certs), and a Settings → Plugins card for live adjustment of port, CIDRs, auth, TLS, and the login password (the card overwrites the stored credential without ever displaying the old one; the password stays a scrypt hash in state.json, out of the config schema). Includes an insecure-origin UUID shim client bundle: on gateway-served plain-HTTP origins browsers lack crypto.randomUUID, so the client half patches a getRandomValues-backed randomUUID onto the Crypto prototype, fixing workspace open over LAN without touching DSH source.",
+  "version": "0.6.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -42,22 +42,34 @@
     }
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-settings": "^0.1.2-rc.1 || ^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.2-rc.1 || ^0.1.5-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/cordis": "^4.0.4",
+    "@deepseek-ai/dsh-settings": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.7-rc.2 || ^0.2.0-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "4.0.2",
-    "@deepseek-ai/dsh-brand": "0.1.5-rc.2",
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/cordis-plugin-loader": "1.0.5",
+    "@deepseek-ai/cosmokit": "1.8.5",
+    "@deepseek-ai/dsh-brand": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-ptc-runtime": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-user-approval": "0.1.7-rc.2",
     "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-scope": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-settings": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.2",
-    "@deepseek-ai/dsh-util-values": "0.1.5-rc.2",
-    "@deepseek-ai/schemastery": "3.18.2",
+    "@deepseek-ai/dsh-client-ui-plugin-manager": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-settings": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-scope": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-util-values": "0.1.7-rc.2",
+    "@deepseek-ai/schemastery": "3.18.4",
     "@types/node": "^22.0.0",
     "@types/react": "~18.3.1",
     "react": "^18.2.0",

package/skills/lan-gateway.md

@@ -41,12 +41,26 @@ Do not edit state files by hand — use the `lan_gateway` tool.
 - `lan_gateway` with `command: "set-password"` and `password: "<new pass>"`
   (min 8 chars) — set the login password. Setting it revokes every existing session
   (all sources, LAN included, must sign in again). Pass an empty password to clear —
-  clearing stops the listener (a password is required to run).
+  clearing stops the listener (a password is required to run). The user can also
+  change it themselves from the Plugins card; see below.
 - `lan_gateway` with `command: "rotate-secret"` — invalidate every issued login
   cookie and every live WebSocket (users must sign in again).
 - `lan_gateway` with `command: "tls-regenerate"` — mint a fresh self-signed
   certificate and hot-restart the listener (tlsMode must be `self-signed`).
 
+## The user can change it without the agent
+
+The **Plugins** page's LAN gateway card, on the machine running dsh, carries a
+login-password form. It reports Set / Not set (never the stored password), takes
+the new password twice, and overwrites the old one directly — no old password
+required. Point the user there when they would rather not hand the password to
+the model; use the tool when they ask you to do it.
+
+The card is loopback-only, so a browser reaching dsh through the gateway gets a
+403 for it, and it can only *set* a password: clearing stops the listener, which
+stays a `lan_gateway set-password` command. A change made there behaves exactly
+like the tool's — the session epoch advances and every session is revoked.
+
 ## After enabling
 
 Tell the user the gateway URL they can share:

package/src/client/index.ts

@@ -7,10 +7,9 @@
  *    installs a getRandomValues-backed `randomUUID` on the Crypto prototype at
  *    module scope. With TLS enabled the origin is secure and the shim is a
  *    no-op.
- * 2. Settings card: registers the LAN gateway card into the official
- *    Settings → Plugins page (`settings.plugin.item` slot), editing the
- *    `lan-gateway` settings namespace so port, CIDRs, auth, and TLS are
- *    adjustable from the GUI.
+ * 2. Settings card: registers the LAN gateway card into the official Plugins
+ *    page (`plugins.item` slot) so port, CIDRs, auth, and TLS stay adjustable
+ *    from the GUI.
  */
 
 /** RFC 4122 v4 UUID from crypto.getRandomValues (available on insecure origins). */
@@ -62,12 +61,25 @@ export function installRandomUuidShim(): boolean {
 installRandomUuidShim()
 
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
-import { LanGatewayCard } from './lan-gateway-card.tsx'
+// Type-only, and never bundled: the Plugins page's slot contract (`plugins.item`)
+// and the settings domain's `configForms` service both resolve from the web
+// shell's frozen module table. Importing them is what subjects the registration
+// below to the platform's own contract instead of a local copy that drifts the
+// next time upstream renames a slot.
+import type {} from '@deepseek-ai/dsh-client-ui-plugin-manager/client'
+import type {} from '@deepseek-ai/dsh-client-ui-settings/client'
+import { LanGatewayCard, cardTitle } from './lan-gateway-card.tsx'
 
 export const name = 'dsh-lan-gateway'
 
-/** Only the slots service: the card itself is self-loading (ModLens-style). */
-export const inject = ['slots']
+/**
+ * The profile entry id this plugin's bundle patch composes it under, and the
+ * settings namespace dsh ≥ 0.1.7 addresses every write by.
+ */
+const ENTRY_ID = 'dsh-lan-gateway'
+
+/** The slots service the card rides, and the settings mirror the gate reads. */
+export const inject = ['slots', 'configForms']
 
 /**
  * Mount the settings card and the UUID shim.
@@ -76,28 +88,26 @@ export const inject = ['slots']
 export function apply(ctx: ClientContext): void {
   installRandomUuidShim()
 
-  // The card rides the official Plugins → Configurable tab. Like ModLens, it
-  // registers with no inject face and fetches its own loopback config route,
-  // so it has no settings/locale/connection service dependencies.
+  // The card rides the official Plugins page. Like ModLens it registers with no
+  // inject face and fetches its own loopback config route, so it depends on no
+  // settings, locale, or connection service.
   //
-  // The `settings.plugin.item` slot is keyed BY the settings namespace the
-  // card edits (rc.8 contract): the configurable tab only dispatches entries
-  // whose `options.key` is both present and served by the Host's settings
-  // describe mirror. Registering with `id` alone throws
-  // `keyed slot "settings.plugin.item" requires options.key` and the card
-  // silently disappears from Settings → Plugins.
+  // dsh 0.1.7 replaced the namespace-keyed `settings.plugin.item` slot with the
+  // list slot `plugins.item`, which is where a host-plane plugin's own
+  // configuration page belongs ("one companion package per host-plane
+  // namespace"); the page renders the contribution as the card's one-liner and,
+  // once opened, as the body of the plugin's own page. Registering into the
+  // retired slot left the card invisible on 0.1.7.
   //
-  // `id`/`order` ride the legacy list-slot shape (older DSH versions
-  // dispatched this slot by id): harmless metadata on the keyed slot, and
-  // what keeps the card mounting if this plugin ever loads into an older
-  // deployment. Spread from a typed constant so the keyed registration type
-  // stays exact.
-  const legacyListOptions = { id: 'lan-gateway', order: 30 } as const
-  ctx.slots.inject('settings.plugin.item', function* () {
-    yield ctx.slots.register({
-      name: 'settings.plugin.item',
-      key: 'lan-gateway',
-      ...legacyListOptions,
-    }, LanGatewayCard)
-  })
+  // `whileServed` keeps the entry off the page until the Host's settings mirror
+  // serves this plugin's entry. That is the one gate worth having: without a
+  // Loader entry there is nothing to write to, and the card would appear only
+  // to fail every save with the route's 409.
+  ctx.effect(() => ctx.configForms.whileServed([ENTRY_ID], () =>
+    ctx.slots.inject('plugins.item', () => ctx.slots.register({
+      name: 'plugins.item',
+      id: ENTRY_ID,
+      order: 30,
+      label: () => cardTitle(),
+    }, LanGatewayCard))))
 }