@lynn123411/dsh-web-auth-url 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lynn123411
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,19 @@
+# @lynn123411/dsh-web-auth-url
+
+DSH Web GUI 的访问鉴权补位：把当前实例**带 token 的访问地址**交给模型与 shell。`dsh-web-app` 有意只把干净地址交给模型（`app:web-surface` 段落）和 shell（`DSH_WEB_URL`），带 token 的地址只打印到 stdout 并交给默认浏览器——于是模型自测这个 GUI（抓页面、探路由、确认客户端插件有没有生效）时第一枪必然 401，只能翻启动器日志找 token。本插件把这半补上，且不把 secret 写进提示词或 session。
+
+## 特性
+
+- **`DSH_WEB_AUTH_URL` 托管环境变量**：每次 shell 调用即时解析的带 token 回环地址（`http://127.0.0.1:<port>/?token=…`），DSH 重启换 token 后自动跟随；不缓存、不落盘。
+- **提示词段落 `app:web-auth-url`**：紧随 `app:web-surface`（order + 10）贡献一段说明——只报变量名、不报值，并交代必需用法：第一次请求 `curl -c "$JAR" -b "$JAR" "$DSH_WEB_AUTH_URL"` 拿到 303 并种下 cookie，之后复用同一个 jar 即已授权。
+- **`prompt` 三档**：`env`（默认）只报变量名，token 不进提示词与 transcript；`inline` 把带 token 的地址直接写进段落（地址每次装配即时解析，重启后不过期，但 token 会随请求发给模型服务商并落盘进 session）；`off` 只保留环境变量。
+- **无 web 部署静默降级**：CLI / TUI / 缺 `connection` 的组合下注册照常完成，但 `resolve` 返回空、段落渲染成空串，而空段落由内核 `renderPrompt` 过滤，系统提示词里不留痕迹。
+- **不新增端口、不新增凭据**：token 取自已装载的 `connection` 服务，与启动时打印到 stdout 的是同一个。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @lynn123411/dsh-web-auth-url
+```
+
+本地开发按仓库规则用 `link:`——`cd ~/.dsh/profiles/web && pnpm add "link:/Users/tny/Desktop/work/my-dsh/plugins/dsh-web-auth-url" --offline`，并在 profile `package.json` 的 `dsh.profile.bundles` 里登记本包（`dsh plugin add` 会自动登记，手工 link 不会）。宿主半边只在 DSH 启动时装载，改完须重启实例；自检 `npm test` 跑 `scripts/smoke-host.mjs`。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# @lynn123411/dsh-web-auth-url bundle patch
+# 声明在 package.json 的 dsh.bundle.patch，`dsh plugin add` 后自动并入 profile 层栈。
+# 只 insert 一行宿主半边：本插件没有客户端半边，也没有要覆盖的内核行。
+- insert:
+    - id: dsh-web-auth-url
+      name: '@lynn123411/dsh-web-auth-url'

package/lib/index.js

@@ -0,0 +1,135 @@
+/**
+ * @lynn123411/dsh-web-auth-url — 宿主半区（node）。
+ *
+ * Web GUI 的每个请求都要过 connection 的浏览器会话鉴权，而鉴权的入口只有
+ * 一个：带本进程 launch token 的根地址。干净地址 `http://127.0.0.1:<port>`
+ * 一律 401，而且这是 `dsh-web-app` 有意为之——它把干净地址交给模型
+ * （`app:web-surface` 段落）和 shell（`DSH_WEB_URL`），带 token 的地址只
+ * 打印到 stdout、交给默认浏览器。
+ *
+ * 代价是模型想自测这个 GUI（抓页面、探路由、确认客户端插件有没有生效）时
+ * 第一枪必然 401，只能翻启动器日志找 token。本插件补上这个缺口，同时不把
+ * secret 放进提示词或 transcript：
+ *
+ * 1. `DSH_WEB_AUTH_URL` —— 每次 shell 调用**即时解析**的带 token 地址，
+ *    因此 DSH 重启换 token 后自动跟随（静态字符串做不到这一点）。
+ * 2. 紧随 `app:web-surface`（order + 10）的一段提示词，说明该地址存在，
+ *    以及「第一次请求 303 换 cookie、之后复用同一个 jar」这个必需用法——
+ *    只报变量名，不报值；`prompt: 'inline'` 才把地址直接写进段落。
+ *
+ * 没有 web 部署的宿主（CLI / TUI / 缺 connection 的组合）不是错误路径：注册
+ * 照常完成，`resolve` 返回空、段落渲染成空串，而空段落会被 renderPrompt
+ * 过滤掉，系统提示词里不留痕迹。
+ *
+ * @module dsh-web-auth-url
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+/** Cordis 插件名（= patch 行 id）。 */
+export const name = 'dsh-web-auth-url'
+
+/** 本插件不硬依赖任何服务：web 服务缺失时静默降级，见模块头。 */
+export const inject = []
+
+/** 回环主机名，与 dsh-web-app 同口径（模型在宿主机上，回环即本实例）。 */
+const LOOPBACK_HOST = '127.0.0.1'
+
+/** 本插件唯一登记的托管环境变量。 */
+const AUTH_URL_KEY = 'DSH_WEB_AUTH_URL'
+
+/** web-app 交给 shell 的干净地址，只在提示词里做对照。 */
+const CLEAN_URL_KEY = 'DSH_WEB_URL'
+
+/** shellEnv 贡献者名。 */
+const CONTRIBUTOR_NAME = 'dsh-web-auth-url'
+
+/** 提示词段落名。 */
+const SECTION_NAME = 'app:web-auth-url'
+
+/** 段落排在 `app:web-surface` 之后，紧挨着它所补充的那段话。 */
+const SECTION_OFFSET = 10
+
+/** 插件配置。 */
+export const Config = z.object({
+  /**
+   * 提示词段落如何交代这个地址。
+   *
+   * - `env`：只报 `$DSH_WEB_AUTH_URL`（默认；token 不进提示词与 transcript）
+   * - `inline`：把带 token 的地址直接写进段落（地址每次装配即时解析，重启后
+   *   不会过期，但 token 会随每次请求发给模型服务商并落盘进 session）
+   * - `off`：不注册段落，只保留环境变量
+   */
+  prompt: z
+    .union([z.const('env'), z.const('inline'), z.const('off')])
+    .default('env')
+    .description('how the prompt section names the authenticated URL: env (point at $DSH_WEB_AUTH_URL), inline (print the tokenized URL), off (no section)'),
+})
+
+/**
+ * 解析本进程当前的带 token 地址。
+ * @param ctx - 任意能读到 webServer / connection 的上下文。
+ * @returns 带 token 的回环地址；没有 web 部署时 undefined。
+ */
+function resolveAuthenticatedUrl(ctx) {
+  const port = ctx.get('webServer')?.port
+  const connection = ctx.get('connection')
+  if (port === undefined || typeof connection?.authenticatedUrl !== 'function') return undefined
+  return connection.authenticatedUrl(`http://${LOOPBACK_HOST}:${String(port)}`)
+}
+
+/**
+ * 渲染提示词段落。
+ * @param ctx - 装配用的上下文。
+ * @param mode - 已解析的 `prompt` 配置。
+ * @returns 段落文本；地址不可解析时返回空串（等于不贡献段落）。
+ */
+function promptText(ctx, mode) {
+  const url = resolveAuthenticatedUrl(ctx)
+  if (url === undefined) return ''
+  const inline = mode === 'inline'
+  const address = inline
+    ? url
+    : `\`$${AUTH_URL_KEY}\` (\`$${CLEAN_URL_KEY}\` is the same origin without the token)`
+  const target = inline ? url : `"$${AUTH_URL_KEY}"`
+  return [
+    'Shell access to this Web GUI is authenticated: an unauthenticated request to the clean URL answers 401,',
+    "because the browser session is a signed cookie minted from this process's launch token.",
+    `The authenticated address is ${address}.`,
+    `Exchange the token once and keep the jar — \`curl -s -c "$JAR" -b "$JAR" -o /dev/null -w '%{http_code}' ${target}\` answers 303 and sets the cookie;`,
+    'every later request through that jar is authorized.',
+  ].join(' ')
+}
+
+/**
+ * 装载插件：登记托管环境变量，并按配置贡献提示词段落。
+ * @param ctx - 宿主插件上下文。
+ * @param config - 已解析的 {@link Config}。
+ */
+export function apply(ctx, config) {
+  const mode = config?.prompt ?? 'env'
+
+  ctx.inject(['shellEnv'], (envCtx) => {
+    envCtx.shellEnv.register({
+      name: CONTRIBUTOR_NAME,
+      variables: {
+        [AUTH_URL_KEY]: {
+          description: 'Canonical local URL of the DeepSeek Harness Web GUI serving this session, carrying this process launch token for the browser-session exchange.',
+        },
+      },
+      resolve: () => {
+        const url = resolveAuthenticatedUrl(envCtx)
+        return url === undefined ? {} : { [AUTH_URL_KEY]: url }
+      },
+    })
+  })
+
+  if (mode === 'off') return
+  ctx.inject(['systemPrompt'], (promptCtx) => {
+    promptCtx.systemPrompt.section({
+      name: SECTION_NAME,
+      order: promptCtx.systemPrompt.getSectionOrder('WEB_SURFACE') + SECTION_OFFSET,
+      text: () => promptText(promptCtx, mode),
+    })
+  })
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@lynn123411/dsh-web-auth-url",
+  "version": "0.1.0",
+  "description": "把当前 Web 实例的带 token 访问地址交给模型与 shell：托管 DSH_WEB_AUTH_URL（每次 shell 调用即时解析，跟随重启后的 token 轮换），并贡献一段紧随 web-surface 的提示词说明 cookie jar 用法，secret 不进提示词与 transcript。",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib",
+    "scripts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "dsh-plugin",
+    "cordis",
+    "web",
+    "auth"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tttnny/my-dsh.git",
+    "directory": "plugins/dsh-web-auth-url"
+  },
+  "scripts": {
+    "test": "node scripts/smoke-host.mjs",
+    "check": "node scripts/smoke-host.mjs"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  }
+}

package/scripts/smoke-host.mjs

@@ -0,0 +1,129 @@
+/**
+ * 宿主半边装配自检：用带守卫的假上下文真跑一遍 apply()，断言登记形状、
+ * 即时解析的地址，以及三种 prompt 模式各自的段落文本。
+ *
+ * 守卫必须真的抛错（末尾有反例断言），否则「未声明的服务」这类断言全是空转。
+ */
+
+import assert from 'node:assert/strict';
+import { apply, Config, inject, name } from '../lib/index.js';
+
+const PORT = 3080;
+const TOKEN = 'launch-token-example';
+const CLEAN_URL = `http://127.0.0.1:${PORT}`;
+const AUTH_URL = `${CLEAN_URL}/?token=${TOKEN}`;
+
+/**
+ * 造一个假上下文。
+ * @param services - 树上可读到的服务。
+ * @param declared - 本上下文已 inject 的服务名。
+ * @returns 读未声明服务即抛 cordis 同款错误的上下文。
+ */
+function makeContext(services, declared = new Set()) {
+  const base = {
+    get: (key) => services[key],
+    inject: (names, callback) => {
+      for (const key of names) {
+        if (!(key in services)) throw new Error(`fake tree is missing service "${key}"`);
+      }
+      callback(makeContext(services, new Set(names)));
+    },
+  };
+  return new Proxy(base, {
+    get(target, property, receiver) {
+      if (typeof property === 'symbol' || property in target) return Reflect.get(target, property, receiver);
+      if (!declared.has(property)) throw new Error(`cannot get property "${property}" without inject`);
+      return services[property];
+    },
+  });
+}
+
+/** 一套带 web 部署的服务桩。 */
+function webServices() {
+  return {
+    webServer: { port: PORT },
+    connection: { authenticatedUrl: (baseUrl) => `${baseUrl}/?token=${TOKEN}` },
+    shellEnv: { register: () => () => {} },
+    systemPrompt: { section: () => () => {}, getSectionOrder: (order) => (order === 'WEB_SURFACE' ? 10100 : Number.NaN) },
+  };
+}
+
+/** 捕获一次 apply() 的登记结果。 */
+function load(config, services = webServices()) {
+  const captured = { contributor: undefined, section: undefined };
+  services.shellEnv.register = (contributor) => {
+    captured.contributor = contributor;
+    return () => {};
+  };
+  services.systemPrompt.section = (section) => {
+    captured.section = section;
+    return () => {};
+  };
+  apply(makeContext(services), config);
+  return { captured, services };
+}
+
+// --- 插件身份 -------------------------------------------------------------
+assert.equal(name, 'dsh-web-auth-url');
+assert.deepEqual(inject, [], '插件必须声明零硬依赖，web 缺失时靠 ctx.get 降级');
+assert.equal(Config({}).prompt, 'env', 'prompt 默认必须是 env（token 不进提示词）');
+assert.equal(Config({ prompt: 'inline' }).prompt, 'inline');
+assert.throws(() => Config({ prompt: 'nope' }), '非法 prompt 必须被 schema 拒绝');
+
+// --- 环境变量 -------------------------------------------------------------
+{
+  const { captured } = load({ prompt: 'env' });
+  const contributor = captured.contributor;
+  assert.equal(contributor.name, 'dsh-web-auth-url');
+  assert.deepEqual(Object.keys(contributor.variables), ['DSH_WEB_AUTH_URL']);
+  assert.ok(contributor.variables.DSH_WEB_AUTH_URL.description.trim().length > 0, '登记的变量必须有描述');
+  assert.deepEqual(contributor.resolve({}), { DSH_WEB_AUTH_URL: AUTH_URL }, 'resolve 必须给出带 token 的当前地址');
+}
+
+// --- token 轮换：每次 resolve 重新解析 -------------------------------------
+{
+  const { captured, services } = load({ prompt: 'env' });
+  services.connection.authenticatedUrl = (baseUrl) => `${baseUrl}/?token=rotated`;
+  assert.deepEqual(captured.contributor.resolve({}), { DSH_WEB_AUTH_URL: `${CLEAN_URL}/?token=rotated` });
+}
+
+// --- 无 web 部署：不报错、不贡献值 -----------------------------------------
+{
+  const services = webServices();
+  delete services.connection;
+  delete services.webServer;
+  const { captured } = load({ prompt: 'env' }, services);
+  assert.deepEqual(captured.contributor.resolve({}), {}, '缺 connection 时 resolve 必须返回空');
+  assert.equal(captured.section.text(), '', '缺 connection 时段落必须渲染成空串');
+}
+
+// --- 提示词段落 -----------------------------------------------------------
+{
+  const { captured } = load({ prompt: 'env' });
+  assert.equal(captured.section.name, 'app:web-auth-url');
+  assert.equal(captured.section.order, 10110, '段落必须紧跟 WEB_SURFACE（10100）');
+  const text = captured.section.text();
+  assert.ok(text.includes('DSH_WEB_AUTH_URL'), 'env 模式必须报出变量名');
+  assert.ok(!text.includes(TOKEN), 'env 模式绝不能把 token 写进提示词');
+  assert.ok(text.includes('401') && text.includes('303') && text.includes('$JAR'), 'env 模式必须交代 401 / 303 / cookie jar 用法');
+}
+{
+  const { captured } = load({ prompt: 'inline' });
+  const text = captured.section.text();
+  assert.ok(text.includes(AUTH_URL), 'inline 模式必须把带 token 的地址写进段落');
+  assert.ok(!text.includes('DSH_WEB_AUTH_URL'), 'inline 模式不再报变量名');
+}
+{
+  const { captured } = load({ prompt: 'off' });
+  assert.equal(captured.section, undefined, 'off 模式不得注册段落');
+  assert.ok(captured.contributor !== undefined, 'off 模式仍须登记环境变量');
+}
+
+// --- 守卫自身的反例断言（守卫失效即失败） ---------------------------------
+{
+  const ctx = makeContext(webServices());
+  assert.throws(() => ctx.shellEnv, /without inject/, '读未声明服务必须抛错，否则上面的断言全是空转');
+  assert.equal(ctx.get('shellEnv') !== undefined, true, 'ctx.get 不抛错，可选能力走它');
+}
+
+console.log('smoke-host: ok');