dsh-perm-gate 5.0.4 → 5.1.2-compat.10

package/lib/appcontainer/probe.js

@@ -0,0 +1,66 @@
+/**
+ * probe.ts —— launcher `--probe` 裁决的 Node 侧消费（解析 / 缓存键 / 归因）。
+ *
+ * 探针产物只做**诊断与归因**，不做放行依据：逐 launch 的 Region B 解析 +
+ * LookupMoniker 只读预检（launcher 进程内）才是唯一信任锚。缓存因此只在
+ * Node 进程内存中、按 launcher 哈希 + OS build 键控——**永不落盘共享**：
+ * 探测结论与「会话上下文」（提权/受限 job）强相关（同一台机器两种上下文
+ * 结论相反已实测），进程内缓存即天然一上下文一份，键里无需也无法诚实
+ * 表达上下文，落盘共享则必然跨上下文污染。
+ */
+import { execFile } from 'node:child_process';
+/**
+ * Parse the probe's single-line stdout. Returns undefined for anything that
+ * is not a recognizable verdict (crash output, truncated line, foreign text) —
+ * the controller treats undefined as UNAVAILABLE-with-retry.
+ */
+export function parseProbeJson(text) {
+    const line = text.split('\n').map((l) => l.trim()).find((l) => l.startsWith('{'));
+    if (line === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    const p = parsed;
+    if (typeof p['era'] !== 'string' || typeof p['sid'] !== 'string' || typeof p['osBuild'] !== 'number')
+        return undefined;
+    if (typeof p['derive'] !== 'object' || p['derive'] === null)
+        return undefined;
+    if (typeof p['registered'] !== 'object' || p['registered'] === null)
+        return undefined;
+    if (typeof p['tryLaunch'] !== 'object' || p['tryLaunch'] === null)
+        return undefined;
+    return parsed;
+}
+/**
+ * The in-memory probe cache key. The launcher hash covers code changes, the
+ * OS build covers kernel-side behavior changes; context is deliberately NOT
+ * in the key because the cache never leaves the process (see header).
+ */
+export function probeCacheKey(launcherHash, probe) {
+    return `${launcherHash}@${probe.osBuild}`;
+}
+/** Run `launcher --probe` and parse its verdict. Undefined = launcher unusable. */
+export function runProbe(exePath, timeoutMs = 60_000) {
+    return new Promise((resolve) => {
+        execFile(exePath, ['--probe'], { windowsHide: true, timeout: timeoutMs, maxBuffer: 1 << 20 }, (error, stdout) => {
+            if (error !== undefined && error !== null) {
+                resolve(undefined); // crash/timeout: UNAVAILABLE, retried on next ensure
+                return;
+            }
+            resolve(parseProbeJson(String(stdout ?? '')));
+        });
+    });
+}
+/** Human-attributable one-liner for deny logs (which resolution level failed). */
+export function probeAttribution(probe) {
+    const derive = `${probe.derive.name}(${probe.derive.module}) hr=0x${(probe.derive.hr >>> 0).toString(16)}`;
+    const launch = probe.tryLaunch.attempted
+        ? `tryLaunch win32Err=${probe.tryLaunch.win32Err}${probe.tryLaunch.childExit !== null ? ` childExit=${probe.tryLaunch.childExit}` : ''}`
+        : 'tryLaunch skipped';
+    return `era=${probe.era} derive=${derive} registered=${probe.registered.state} ${launch}`;
+}

package/lib/appcontainer/sid.d.ts

@@ -0,0 +1,23 @@
+/**
+ * sid.ts —— AppContainer 容器 SID 的形状校验与容器名常量。
+ *
+ * 派生**不在 Node 侧做**：自造 S-1-15-2 SID（sha256 排序等任何手工形状）会被
+ * `NtCreateLowBoxToken` 以 STATUS_INVALID_SID (0xC0000030) 拒绝——容器 SID 必须由
+ * OS 自己的推导产生（launcher 的 `--print-sid` 走官方
+ * `DeriveAppContainerSidFromName`，Win8+，名字确定则 SID 确定，机器内稳定，
+ * 回环豁免与 ACL 授予因此终身复用）。本模块只保留：容器名（改名字 = 换 SID =
+ * 旧豁免/旧 ACE 全部脱靶）与 SID 字符串形状校验。
+ */
+/** The fixed AppContainer container name — changing it invalidates every
+ * standing exemption/ACE (it derives a brand-new SID). */
+export declare const APPCONTAINER_NAME = "dsh-perm-gate.ac";
+export declare const APPCONTAINER_AUTHORITY = "S-1-15-2";
+/**
+ * Structural check for an AppContainer SID string — an OPAQUE handle check.
+ *
+ * 实测（2026-10-05，26200）：经典派生为 4 子权限，新代 moniker 派生与真实
+ * UWP 包 SID 为 7 子权限，且**非单调**——校验只认 `S-1-15-2` 权威前缀 +
+ * ≥4 个 uint32 子权限，绝不假设数量或排序（自造 SID 本就被内核拒收，
+ * 这里只是形状门，不是派生器）。
+ */
+export declare function isAppContainerSid(sid: string): boolean;

package/lib/appcontainer/sid.js

@@ -0,0 +1,33 @@
+/**
+ * sid.ts —— AppContainer 容器 SID 的形状校验与容器名常量。
+ *
+ * 派生**不在 Node 侧做**：自造 S-1-15-2 SID（sha256 排序等任何手工形状）会被
+ * `NtCreateLowBoxToken` 以 STATUS_INVALID_SID (0xC0000030) 拒绝——容器 SID 必须由
+ * OS 自己的推导产生（launcher 的 `--print-sid` 走官方
+ * `DeriveAppContainerSidFromName`，Win8+，名字确定则 SID 确定，机器内稳定，
+ * 回环豁免与 ACL 授予因此终身复用）。本模块只保留：容器名（改名字 = 换 SID =
+ * 旧豁免/旧 ACE 全部脱靶）与 SID 字符串形状校验。
+ */
+/** The fixed AppContainer container name — changing it invalidates every
+ * standing exemption/ACE (it derives a brand-new SID). */
+export const APPCONTAINER_NAME = 'dsh-perm-gate.ac';
+export const APPCONTAINER_AUTHORITY = 'S-1-15-2';
+/**
+ * Structural check for an AppContainer SID string — an OPAQUE handle check.
+ *
+ * 实测（2026-10-05，26200）：经典派生为 4 子权限，新代 moniker 派生与真实
+ * UWP 包 SID 为 7 子权限，且**非单调**——校验只认 `S-1-15-2` 权威前缀 +
+ * ≥4 个 uint32 子权限，绝不假设数量或排序（自造 SID 本就被内核拒收，
+ * 这里只是形状门，不是派生器）。
+ */
+export function isAppContainerSid(sid) {
+    const parts = sid.split('-');
+    if (parts.length < 8 || parts[0] !== 'S' || parts[1] !== '1' || parts[2] !== '15' || parts[3] !== '2')
+        return false;
+    for (const part of parts.slice(4)) {
+        const n = Number(part);
+        if (!Number.isInteger(n) || n < 0 || n > 0xFFFF_FFFF)
+            return false;
+    }
+    return true;
+}

package/lib/appcontainer/wrap.d.ts

@@ -0,0 +1,22 @@
+/** One sandboxed-execution plan: everything the launcher needs, on disk. */
+export interface SandboxLaunchConfig {
+    /** The session workspace the command runs in (cwd + ACL grant root). */
+    readonly workspace: string;
+    /** Per-call scratch dir created by the Node side; the launcher gets it via env. */
+    readonly tempDir: string;
+    /** 'read-only' grants RX on the workspace; 'workspace-write' adds Modify. */
+    readonly mode: 'read-only' | 'workspace-write';
+    /** Exact env overrides for the child (HTTPS_PROXY etc.). Empty keys delete. */
+    readonly proxyEnv: Readonly<Record<string, string>>;
+}
+/** Serialize + persist one launch config, returning the path to hand the launcher. */
+export declare function writeLaunchConfig(config: SandboxLaunchConfig, configDir: string): Promise<string>;
+/** base64url-free standard base64 of the UTF-8 command text. */
+export declare function encodeCommand(command: string): string;
+export declare function decodeCommand(encoded: string): string;
+/**
+ * The command line the outer shell executes instead of the original one.
+ * Single quoted-exe invocation; `=` padding and the alnum base64 body are
+ * inert in cmd.exe and POSIX shells alike.
+ */
+export declare function buildWrappedCommand(launcherPath: string, configPath: string, command: string): string;

package/lib/appcontainer/wrap.js

@@ -0,0 +1,40 @@
+/**
+ * wrap.ts —— 允许调用 → AppContainer 启动器命令行的重写（纯逻辑，可单测）。
+ *
+ * 关键决策：原命令 **base64 编码**后交给启动器，外层 shell 只见
+ * `<launcher> --config <cfg> --exec-b64 <b64>` 一个普通进程调用——管道/
+ * `&&`/重定向是外层 shell 语法，若把原命令裸拼在后面，它们会在**容器外**
+ * 被解析执行，沙盒即被绕过。base64 字母表（A-Za-z0-9+/=）在 cmd 与 POSIX
+ * shell 里都是惰性字符，无需再转义。
+ *
+ * 配置文件每次调用落盘一份（JSON），启动器读它拿 workspace/temp/代理环境；
+ * 与命令行传参相比少一层引就地狱。env 覆盖采用宿主 windows-acl 验证过的
+ * 形态：**启动器先改自身环境再 CreateProcess（继承），不传显式 env block**
+ * （koffi 实测显式 env 在 CreateProcessAsUserW 上报 ERROR_INVALID_PARAMETER；
+ * C# 路径虽然标准，继承形态少一层封送，风险为零）。
+ */
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+/** Serialize + persist one launch config, returning the path to hand the launcher. */
+export async function writeLaunchConfig(config, configDir) {
+    await mkdir(configDir, { recursive: true });
+    const file = path.join(configDir, `ac-${randomUUID()}.json`);
+    await writeFile(file, JSON.stringify(config, null, 2) + '\n', 'utf8');
+    return file;
+}
+/** base64url-free standard base64 of the UTF-8 command text. */
+export function encodeCommand(command) {
+    return Buffer.from(command, 'utf8').toString('base64');
+}
+export function decodeCommand(encoded) {
+    return Buffer.from(encoded, 'base64').toString('utf8');
+}
+/**
+ * The command line the outer shell executes instead of the original one.
+ * Single quoted-exe invocation; `=` padding and the alnum base64 body are
+ * inert in cmd.exe and POSIX shells alike.
+ */
+export function buildWrappedCommand(launcherPath, configPath, command) {
+    return `"${launcherPath}" --config "${configPath}" --exec-b64 ${encodeCommand(command)}`;
+}

package/lib/bridge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * settings bridge — T12（spec webServer 数据桥规范）：describe/mutate 两端点。
+ *
+ * 桥只是 HTTP 皮：读 = svc.describe 取自家 ns 描述符；写 = svc.mutate 转 ops 落
+ * 宿主 settings 服务（不落盘不缓存第二份，天然规避双写/锁竞争）。mutate 成功即
+ * describe 回填，带 expectedRevision 乐观并发。守卫：POST-only + ns 硬编码自家
+ * allowlist + 秘密不回读（redactSecrets）。
+ *
+ * 数据面消费方 = client BridgeDocHandle（T13b 双轨数据源：0.1.7+ 原生句柄优先，
+ * ≤0.1.5 settingsScope 不解析时落到本桥——free-search 同架构）。
+ *
+ * T20-b 泛化（2026-10-08）：路由从 ns 参数派生（bridgeRoutesFor），一个宿主进程
+ * 可为多个 ns 各注册一对端点（steward 双 ns：会话管家 + 搜索索引）——客户端与
+ * 服务端各自持同一派生式，测试钉死两半一致，URL 契约不可能漂移。
+ */
+interface SettingsServiceLike {
+    update(ns: string, patch: object): Promise<void>;
+    register?(ns: string, schema: unknown, options?: {
+        base?: unknown;
+    }): unknown;
+    installSection?(owner: unknown, ns: string, schema: unknown, entry: unknown, hooks: unknown): unknown;
+    describe?(o?: {
+        redactSecrets?: boolean;
+    }): Array<{
+        ns: unknown;
+        [k: string]: unknown;
+    }>;
+    mutate?(ns: string, ops: Array<{
+        op: string;
+        path: string[];
+        value?: unknown;
+    }>, expectedRevision?: number): Promise<unknown>;
+    writable?: boolean;
+}
+/** 一个 settings ns 的桥路由对——client 与 server 必须同式派生（测试钉死一致）。 */
+export declare function bridgeRoutesFor(ns: string): {
+    describe: string;
+    mutate: string;
+};
+export declare function registerSettingsBridgeRoutes(server: unknown, getSettingsSvc: () => SettingsServiceLike | undefined, ns: string): Array<() => void>;
+export {};

package/lib/bridge.js

@@ -0,0 +1,128 @@
+/** 一个 settings ns 的桥路由对——client 与 server 必须同式派生（测试钉死一致）。 */
+export function bridgeRoutesFor(ns) {
+    return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` };
+}
+function readJsonBody(reqRaw, limit = 256 * 1024) {
+    const req = reqRaw;
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            const buf = chunk;
+            size += buf.length;
+            if (size > limit) {
+                reject(new Error('bridge body too large'));
+                req.resume?.();
+                return;
+            }
+            chunks.push(buf);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (raw === '') {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function sendJson(res, code, body) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' });
+    res.end(JSON.stringify(body));
+}
+function isConflict(e) {
+    return e instanceof Error && /conflict|revision/i.test(e.message);
+}
+export function registerSettingsBridgeRoutes(server, getSettingsSvc, ns) {
+    if (typeof server !== 'object' || server === null)
+        return [];
+    const ws = typeof server.register === 'function' ? server : undefined;
+    if (ws === undefined)
+        return [];
+    const offs = [];
+    const routes = bridgeRoutesFor(ns);
+    offs.push(ws.register({
+        kind: 'exact',
+        path: routes.describe,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, code: 'method-not-allowed' });
+                return;
+            }
+            const svc = getSettingsSvc();
+            if (svc === undefined || typeof svc.describe !== 'function') {
+                sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service not resolved yet' });
+                return;
+            }
+            try {
+                const descriptor = svc
+                    .describe({ redactSecrets: true })
+                    .find((d) => d.ns === ns);
+                if (descriptor === undefined) {
+                    sendJson(res, 200, { ok: false, code: 'ns-not-registered', message: `settings namespace "${ns}" is not registered` });
+                    return;
+                }
+                sendJson(res, 200, { ok: true, value: { descriptor, writable: svc.writable !== false } });
+            }
+            catch (e) {
+                sendJson(res, 200, { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) });
+            }
+        },
+    }));
+    offs.push(ws.register({
+        kind: 'exact',
+        path: routes.mutate,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, code: 'method-not-allowed' });
+                return;
+            }
+            const svc = getSettingsSvc();
+            const mutate = svc === undefined ? undefined : svc.mutate;
+            if (typeof mutate !== 'function') {
+                sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service mutate not available' });
+                return;
+            }
+            readJsonBody(req).then((body) => {
+                const ops = body.ops;
+                if (!Array.isArray(ops) || ops.some((op) => !op || typeof op !== 'object' || !(op.op in { set: 1, unset: 1 }))) {
+                    sendJson(res, 200, { ok: false, code: 'settings-rejected', message: 'malformed bridge mutate ops' });
+                    return;
+                }
+                const expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : undefined;
+                mutate
+                    .call(svc, ns, ops, expectedRevision)
+                    .then(() => {
+                    // mutate 成功即 describe 回填（规范：写路径仍归口宿主服务，无第二份状态）
+                    const descriptor = svc
+                        .describe({ redactSecrets: true })
+                        .find((d) => d.ns === ns);
+                    if (descriptor === undefined) {
+                        sendJson(res, 200, { ok: false, code: 'internal', message: `namespace "${ns}" disposed after mutate` });
+                        return;
+                    }
+                    sendJson(res, 200, { ok: true, value: { descriptor } });
+                })
+                    .catch((e) => {
+                    sendJson(res, 200, isConflict(e)
+                        ? { ok: false, code: 'settings-conflict', message: e instanceof Error ? e.message : String(e) }
+                        : { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) });
+                });
+            }).catch((e) => {
+                sendJson(res, 200, { ok: false, code: 'bad-request', message: e instanceof Error ? e.message : String(e) });
+            });
+        },
+    }));
+    return offs;
+}