dsh-m 0.1.1 → 0.2.0

package/lib/core/host-api.js

@@ -0,0 +1,285 @@
+/**
+ * /dshm Host API dispatcher（DESIGN.md §4/§5）：可注入的 method 分发 + 请求防护 +
+ * HTTP 状态映射，供 host.ts 与契约测试共用。
+ *
+ * 解析顺序固定：只接受 POST → JSON Content-Type → 有上限读取并 drain body →
+ * 顶层必须是非 null/非数组对象且有 method → `ping` 跳过 guard，否则
+ * trustedRestartRequest host-equivalence guard → typed method/业务错误映射 → 其他 500。
+ */
+import { BOOT_ID, addDshPlugin, publicInstallStatus } from './dsh-cli.js';
+import { listInstalledWithMeta, listMarket, installFromRegistry, uninstallPlugin, upgradePlugin, } from './market.js';
+import { readInstalledPluginReadme } from './installed.js';
+import { isNewerVersion, npmLatest } from './versions.js';
+import { RegistryConfigError } from './registry-controller.js';
+import { checkRegistryEntries } from './registry-check.js';
+import { CATEGORIES } from './registry.js';
+import { servingPort, scheduleRestart, trustedRestartRequest } from './restart.js';
+export class BadJsonError extends Error {
+}
+export class BodyTooLargeError extends Error {
+}
+export class UnsupportedMediaTypeError extends Error {
+}
+class ApiProtocolError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+const BODY_MAX_BYTES = 1 << 20;
+function readBody(req, maxBytes = BODY_MAX_BYTES) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        let settled = false;
+        req.on('data', (chunk) => {
+            if (settled)
+                return;
+            size += chunk.length;
+            if (size > maxBytes) {
+                settled = true;
+                req.resume(); // drain：停止收集但不盲目 destroy socket
+                reject(new BodyTooLargeError());
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            if (!settled) {
+                settled = true;
+                resolve(Buffer.concat(chunks));
+            }
+        });
+        req.on('error', (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+    });
+}
+async function parseRequest(req) {
+    if ((req.method || 'GET').toUpperCase() !== 'POST') {
+        throw new ApiProtocolError(405, '只接受 POST');
+    }
+    const contentType = String(req.headers['content-type'] ?? '').trim();
+    if (!/^application\/(?:[\w.+-]+\+)?json\b/i.test(contentType)) {
+        throw new UnsupportedMediaTypeError();
+    }
+    const raw = await readBody(req);
+    let parsed;
+    if (raw.length === 0)
+        throw new BadJsonError('请求体不能为空');
+    try {
+        parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    }
+    catch {
+        throw new BadJsonError('请求体不是合法 JSON');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new BadJsonError('请求体顶层必须是对象');
+    }
+    const body = parsed;
+    const method = typeof body.method === 'string' ? body.method.trim() : '';
+    if (!method)
+        throw new BadJsonError('缺少 method');
+    if (method !== 'ping' && !trustedRestartRequest(req)) {
+        throw new ApiProtocolError(403, '拒绝跨源请求');
+    }
+    return { method, body };
+}
+function strArg(body, key) {
+    const v = body[key];
+    return typeof v === 'string' ? v.trim() : '';
+}
+function boolArg(v) {
+    return v === true || v === 'true' || v === 1 || v === '1';
+}
+function snapshotPayload(snap) {
+    return {
+        registryUrl: snap.configuredAddress,
+        configuredAddress: snap.configuredAddress,
+        activeConfigAddress: snap.activeConfigAddress,
+        pendingAddress: snap.pendingAddress,
+        configStatus: snap.configStatus,
+        configErrors: snap.configErrors,
+        warnings: snap.warnings,
+        registryState: snap.loaded,
+    };
+}
+function sendJson(res, status, value) {
+    const body = JSON.stringify(value);
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': Buffer.byteLength(body),
+        'cache-control': 'no-store',
+    });
+    res.end(body);
+}
+function errorStatus(err) {
+    if (err instanceof BadJsonError)
+        return { status: 400, payload: { ok: false, error: err.message } };
+    if (err instanceof BodyTooLargeError)
+        return { status: 413, payload: { ok: false, error: '请求体过大' } };
+    if (err instanceof UnsupportedMediaTypeError)
+        return { status: 415, payload: { ok: false, error: 'Content-Type 必须是 application/json' } };
+    if (err instanceof RegistryConfigError) {
+        return { status: 422, payload: { ok: false, error: err.message, errors: err.errors } };
+    }
+    if (err instanceof ApiProtocolError)
+        return { status: err.status, payload: { ok: false, error: err.message } };
+    return { status: 500, payload: { ok: false, error: err instanceof Error ? err.message : String(err) } };
+}
+export function createApiDispatcher(ctx) {
+    const d = {
+        listMarket: ctx.deps?.listMarket ?? listMarket,
+        listInstalledWithMeta: ctx.deps?.listInstalledWithMeta ?? listInstalledWithMeta,
+        installFromRegistry: ctx.deps?.installFromRegistry ?? installFromRegistry,
+        uninstallPlugin: ctx.deps?.uninstallPlugin ?? uninstallPlugin,
+        upgradePlugin: ctx.deps?.upgradePlugin ?? upgradePlugin,
+        checkRegistryEntries: ctx.deps?.checkRegistryEntries ?? checkRegistryEntries,
+        npmLatest: ctx.deps?.npmLatest ?? npmLatest,
+    };
+    const cfg = () => ctx.controller.config;
+    return async function handleApi(req, res) {
+        const abort = new AbortController();
+        res.once('close', () => abort.abort());
+        try {
+            const { method, body } = await parseRequest(req);
+            const signal = abort.signal;
+            let payload;
+            switch (method) {
+                case 'ping':
+                    payload = { plugin: ctx.pkg.name, version: ctx.pkg.version, node: process.version, boot: BOOT_ID };
+                    break;
+                case 'self-check': {
+                    try {
+                        const latest = await d.npmLatest(ctx.pkg.name, cfg().timeoutMs ?? 20_000);
+                        payload = { current: ctx.pkg.version, latest: latest.version, outdated: isNewerVersion(latest.version, ctx.pkg.version) };
+                    }
+                    catch (err) {
+                        payload = { current: ctx.pkg.version, latest: null, outdated: false, error: err instanceof Error ? err.message : String(err) };
+                    }
+                    break;
+                }
+                case 'self-upgrade': {
+                    const latest = await d.npmLatest(ctx.pkg.name, cfg().timeoutMs ?? 20_000);
+                    const result = await ctx.onMutation(() => addDshPlugin(`${ctx.pkg.name}@${latest.version}`));
+                    payload = { pkg: ctx.pkg.name, version: latest.version, usedAllowAllBuilds: result.usedAllowAllBuilds, needsRestart: true };
+                    break;
+                }
+                case 'registry': {
+                    await ctx.controller.ensureReady();
+                    const snap = await ctx.controller.snapshot({ force: boolArg(body.force), signal });
+                    payload = { plugins: snap.loaded.registry.plugins, registryState: snap.loaded };
+                    break;
+                }
+                case 'market': {
+                    await ctx.controller.ensureReady();
+                    // GUI policy：忽略客户端 withLatest，固定 true；limit clamp 1..50
+                    const limitRaw = Number(body.limit);
+                    const limit = Number.isFinite(limitRaw) && limitRaw > 0 ? Math.min(50, Math.max(1, Math.floor(limitRaw))) : 50;
+                    const offsetRaw = Number(body.offset);
+                    const offset = Number.isFinite(offsetRaw) && offsetRaw > 0 ? Math.floor(offsetRaw) : 0;
+                    const category = typeof body.category === 'string' && CATEGORIES.includes(body.category)
+                        ? body.category
+                        : null;
+                    const result = await d.listMarket(cfg(), {
+                        query: strArg(body, 'query'),
+                        category,
+                        offset,
+                        limit,
+                        force: boolArg(body.force),
+                        withLatest: true,
+                        namespace: 'host',
+                        signal,
+                    });
+                    payload = { ...result };
+                    break;
+                }
+                case 'installed': {
+                    await ctx.controller.ensureReady();
+                    const result = await d.listInstalledWithMeta(cfg(), { namespace: 'host', signal });
+                    payload = { ...result };
+                    break;
+                }
+                case 'readme': {
+                    const target = strArg(body, 'pkg');
+                    if (!target)
+                        throw new ApiProtocolError(400, '缺少 pkg');
+                    const result = await readInstalledPluginReadme(target);
+                    payload = { ...result };
+                    break;
+                }
+                case 'status':
+                    payload = { ...publicInstallStatus() };
+                    break;
+                case 'install': {
+                    const id = strArg(body, 'id');
+                    if (!id)
+                        throw new ApiProtocolError(400, '缺少 id');
+                    const version = typeof body.version === 'string' ? body.version : undefined;
+                    const result = await ctx.onMutation(() => d.installFromRegistry(id, cfg(), { version, namespace: 'host' }));
+                    payload = { ...result };
+                    break;
+                }
+                case 'uninstall': {
+                    const target = strArg(body, 'pkg');
+                    if (!target)
+                        throw new ApiProtocolError(400, '缺少 pkg');
+                    const result = await ctx.onMutation(() => d.uninstallPlugin(target, cfg(), { namespace: 'host' }));
+                    payload = { ...result };
+                    break;
+                }
+                case 'upgrade': {
+                    const target = strArg(body, 'pkg');
+                    if (!target)
+                        throw new ApiProtocolError(400, '缺少 pkg');
+                    const result = await ctx.onMutation(() => d.upgradePlugin(target, cfg(), { namespace: 'host' }));
+                    payload = { ...result };
+                    break;
+                }
+                case 'restart': {
+                    const result = scheduleRestart(servingPort(req));
+                    payload = { ...result };
+                    break;
+                }
+                case 'registry-config': {
+                    const snap = await ctx.controller.snapshot();
+                    payload = { ...snapshotPayload(snap) };
+                    break;
+                }
+                case 'registry-config-apply': {
+                    if (typeof body.registryUrl !== 'string')
+                        throw new ApiProtocolError(400, '缺少 registryUrl');
+                    const snap = await ctx.controller.apply(body.registryUrl, { signal });
+                    payload = { applied: true, ...snapshotPayload(snap) };
+                    break;
+                }
+                case 'registry-default-download': {
+                    const loaded = await ctx.controller.loadDefault({ force: true, signal });
+                    payload = { registry: loaded.registry, registryState: loaded };
+                    break;
+                }
+                case 'registry-diagnose': {
+                    await ctx.controller.ensureReady();
+                    const snap = await ctx.controller.snapshot();
+                    const check = await d.checkRegistryEntries(snap.loaded.registry, { signal });
+                    payload = { registryState: snap.loaded, check };
+                    break;
+                }
+                default:
+                    throw new ApiProtocolError(404, `未知 method: ${method}`);
+            }
+            sendJson(res, 200, { ok: true, ...payload });
+        }
+        catch (err) {
+            const { status, payload } = errorStatus(err);
+            if (!res.headersSent)
+                sendJson(res, status, payload);
+            else
+                res.destroy();
+        }
+    };
+}

package/lib/core/httpx.js

@@ -1,29 +1,42 @@
 /**
- * 安全基线 §17.1：仅 HTTPS（loopback http 例外）+ 响应大小上限 + 超时。
- * skillhub 的缺口（无统一体积上限）在这里补齐。
+ * 安全基线 §17.1：仅 HTTPS（loopback http 例外）+ 响应大小上限 + 超时 + 手动重定向。
+ * 所有 HTTP JSON/text/HEAD 请求共享同一 primitive：每一跳 assertSafeUrl、最多 3 跳、
+ * 循环检测、signal 传播、返回最终 URL；registry/homepage/icon 诊断不得另起一套。
  */
+import { Buffer } from 'node:buffer';
 export class HttpError extends Error {
     status;
-    constructor(status, message) {
+    /** 非 2xx 响应的 headers（供上层识别限流等场景）；body-cap/协议类错误无 headers */
+    headers;
+    constructor(status, message, headers) {
         super(message);
         this.status = status;
+        this.headers = headers;
     }
 }
 const MAX_DEFAULT = 2 * 1024 * 1024; // 2MB：registry/npm metadata 足够
+const MAX_REDIRECTS = 3;
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const USER_AGENT = 'dsh-m (personal marketplace)';
 export function assertSafeUrl(raw) {
     let url;
     try {
         url = new URL(raw);
     }
     catch {
-        throw new HttpError(400, `无效 URL: ${raw}`);
+        throw new HttpError(400, `无效 URL`);
     }
     if (url.protocol === 'https:')
         return url;
-    if (url.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(url.hostname)) {
+    const hostname = url.hostname.replace(/^\[/, '').replace(/\]$/, '').toLowerCase();
+    if (url.protocol === 'http:' && ['127.0.0.1', 'localhost', '::1'].includes(hostname)) {
         return url; // 本地 registry 覆盖调试用（DESIGN.md §2.1）
     }
-    throw new HttpError(400, `仅允许 HTTPS: ${raw}`);
+    throw new HttpError(400, '仅允许 HTTPS（loopback 可用 HTTP）');
+}
+/** UTF-8 fatal 解码：非法序列直接抛错，不用替换字符静默吞掉。 */
+export function decodeUtf8Fatal(buf) {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buf);
 }
 async function readCapped(res, maxBytes) {
     const declared = Number(res.headers.get('content-length') || 0);
@@ -47,46 +60,90 @@ async function readCapped(res, maxBytes) {
     }
     return Buffer.concat(chunks);
 }
-export async function fetchJsonLimited(url, opts = {}) {
-    assertSafeUrl(url);
-    const res = await fetch(url, {
-        signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
-        headers: { accept: 'application/json', 'user-agent': 'dsh-m (personal marketplace)', ...opts.headers },
-        redirect: 'follow',
+/**
+ * 统一安全 fetch：redirect:'manual' + 每跳 assertSafeUrl + 最多 3 跳 + 循环检测 +
+ * timeout/外部 signal 合并 + body cap。HEAD 不读 body。
+ */
+export async function fetchLimited(url, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? 20_000;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = opts.signal ? AbortSignal.any([timeoutSignal, opts.signal]) : timeoutSignal;
+    let current = assertSafeUrl(url);
+    const seen = new Set([current.toString()]);
+    for (let hop = 0;; hop++) {
+        const res = await fetch(current, {
+            redirect: 'manual',
+            signal,
+            method: opts.method ?? 'GET',
+            headers: { 'user-agent': USER_AGENT, ...opts.headers },
+        });
+        if (REDIRECT_STATUSES.has(res.status)) {
+            await res.body?.cancel().catch(() => undefined);
+            if (hop >= MAX_REDIRECTS)
+                throw new HttpError(502, `重定向超过 ${MAX_REDIRECTS} 跳`);
+            const location = res.headers.get('location');
+            if (!location)
+                throw new HttpError(502, '重定向缺少 Location');
+            let next;
+            try {
+                next = new URL(location, current);
+            }
+            catch {
+                throw new HttpError(502, '重定向 Location 无效');
+            }
+            assertSafeUrl(next.toString());
+            const key = next.toString();
+            if (seen.has(key))
+                throw new HttpError(502, '检测到重定向循环');
+            seen.add(key);
+            current = next;
+            continue;
+        }
+        const buffer = opts.method === 'HEAD' ? Buffer.alloc(0) : await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
+        return { status: res.status, ok: res.ok, finalUrl: current.toString(), headers: res.headers, buffer };
+    }
+}
+export async function fetchJsonLimitedMeta(url, opts = {}) {
+    const res = await fetchLimited(url, {
+        ...opts,
+        headers: { accept: 'application/json', ...opts.headers },
     });
     if (!res.ok)
-        throw new HttpError(res.status, `HTTP ${res.status}: ${url}`);
-    const buf = await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
+        throw new HttpError(res.status, `HTTP ${res.status}`, res.headers);
+    let text;
     try {
-        return JSON.parse(buf.toString('utf8'));
+        text = decodeUtf8Fatal(res.buffer);
     }
-    catch (err) {
-        throw new HttpError(502, `响应不是合法 JSON: ${url}`);
+    catch {
+        throw new HttpError(502, '响应不是合法 UTF-8');
+    }
+    try {
+        return { data: JSON.parse(text), finalUrl: res.finalUrl };
+    }
+    catch {
+        throw new HttpError(502, '响应不是合法 JSON');
     }
 }
+/** 旧契约兼容：只返回解析后的 JSON。 */
+export async function fetchJsonLimited(url, opts = {}) {
+    return (await fetchJsonLimitedMeta(url, opts)).data;
+}
 export async function fetchTextLimited(url, opts = {}) {
-    assertSafeUrl(url);
-    const res = await fetch(url, {
-        signal: AbortSignal.timeout(opts.timeoutMs ?? 20_000),
-        headers: { 'user-agent': 'dsh-m (personal marketplace)', ...opts.headers },
-        redirect: 'follow',
-    });
+    const res = await fetchLimited(url, opts);
     if (!res.ok)
-        throw new HttpError(res.status, `HTTP ${res.status}: ${url}`);
-    const buf = await readCapped(res, opts.maxBytes ?? MAX_DEFAULT);
-    return buf.toString('utf8');
+        throw new HttpError(res.status, `HTTP ${res.status}`, res.headers);
+    try {
+        return decodeUtf8Fatal(res.buffer);
+    }
+    catch {
+        throw new HttpError(502, '响应不是合法 UTF-8');
+    }
 }
-/** 可达性探测（icon/homepage 校验用）：2xx 即可达。 */
-export async function isReachable(url, timeoutMs = 8000) {
+/** 可达性探测（icon/homepage 诊断用）：2xx 即可达；HEAD 405 视为可达。 */
+export async function isReachable(url, timeoutMs = 8000, signal) {
     try {
-        assertSafeUrl(url);
-        const res = await fetch(url, {
-            method: 'HEAD',
-            signal: AbortSignal.timeout(timeoutMs),
-            headers: { 'user-agent': 'dsh-m (personal marketplace)' },
-            redirect: 'follow',
-        });
-        return res.ok || res.status === 405; // 有的站点拒绝 HEAD，视为可达
+        const res = await fetchLimited(url, { method: 'HEAD', timeoutMs, signal });
+        return res.ok || res.status === 405;
     }
     catch {
         return false;