@dsh-cove/dsh-web-all 0.0.0-stage → 0.4.3

package/lib/types/host/services/remote-web-ui/server.js

@@ -0,0 +1,492 @@
+/**
+ * dsh-remote-web-ui — server-mode plugin entry (host half).
+ *
+ * Server mode replaces the QR pairing model: this plugin turns `dsh web`
+ * into a deployable server on the LAN (and, with TLS configured, addressable
+ * from anywhere) without ever trusting the SDK's /api transport fence to be
+ * an authentication layer. The plugin owns ONE public listener — the
+ * gateway (default 0.0.0.0:3082, optional built-in TLS) — in front of the
+ * loopback webServer. Every request passes the account/session wall and the
+ * role check, then the gateway re-issues it to 127.0.0.1 as a loopback-shaped
+ * call (Host rewritten to loopback, same-origin marker, client cookies and
+ * Origin stripped), so the full host surface — including the SDK's
+ * loopback-pinned privileged methods — is reachable exactly as far as the
+ * role policy allows.
+ *
+ * Loopback-only surfaces stay on the webServer (never reachable directly
+ * from the LAN without the gateway): the /api/gateway admin surface
+ * (accounts + sessions, first-admin bootstrap). The gateway proxies every
+ * other path after the wall.
+ */
+import { join } from 'node:path';
+import { setInterval as nodeSetInterval, setTimeout as nodeSetTimeout } from 'node:timers';
+import z from 'schemastery';
+import { familyNamespace, onFamilyConfigChange, registerFamilyNamespace } from "../family-config.js";
+import { registerResources } from "../resources.js";
+import { AccountStore, randomSalt } from "./server-mode/accounts.js";
+import { DEFAULT_IDLE_EXPIRE_MS, DEFAULT_MAX_AGE_MS, randomSessionId, SessionStore, } from "./server-mode/sessions.js";
+import { GATEWAY_API_PREFIX, isPreAuthGatewayPath, LoginLimiter, makeGatewayRequestHandler, } from "./server-mode/gateway-routes.js";
+import { Gateway } from "./server-mode/gateway.js";
+import { dshHome } from "./server-mode/dsh-home.js";
+import { isLoopbackAdmin } from "./server-mode/fence.js";
+import { claimPostureKey, postureTargets, probePosture, releasePostureKey } from "./server-mode/posture.js";
+import { lanIPv4Addresses } from "./server-mode/lan.js";
+import { SERVER_BOOT_SCRIPT } from "./server-mode/server-boot.js";
+import { writeJson } from "./server-mode/http.js";
+import { installIntegratedBrowserAuth, } from "./server-mode/integrated-auth.js";
+import { makeSetCookie, readCookie } from "./server-mode/cookie.js";
+import { ExternalAuthService, externalAccountName, } from "./server-mode/external-auth.js";
+import { safeLoginTarget } from "./server-mode/integrated-auth.js";
+/** Stable cordis plugin name. */
+/** Services required before the server-mode surfaces can mount. */
+/**
+ * Settings namespace of the remote-control capability — the section the web
+ * settings surface edits. Spelled here rather than imported: the browser
+ * half spells the same value and must not depend on a Host package.
+ */
+export const REMOTE_WEB_UI_SETTINGS_NAMESPACE = 'remote-web-ui';
+export const Config = z.object({
+    enabled: z.boolean().default(true),
+    integratedAuthEnabled: z.boolean().default(true),
+    legacyGatewayEnabled: z.boolean().default(false),
+    serverHost: z.string().min(1).default('0.0.0.0'),
+    serverPort: z.number().step(1).min(0).max(65_535).default(3082),
+    serverTlsCert: z.string(),
+    // This is a filesystem path, not private-key content. Keep it readable so
+    // settings round-trips do not erase a configured path behind secret redaction.
+    serverTlsKey: z.string(),
+    cookieName: z.string().min(1).default('dsh_gw_session'),
+    idleExpireMs: z.number().step(1).min(60_000).default(DEFAULT_IDLE_EXPIRE_MS),
+    maxAgeMs: z.number().step(1).min(60_000).default(DEFAULT_MAX_AGE_MS),
+    accountsFile: z.string(),
+    sessionsFile: z.string(),
+    bootstrapAdminUsername: z.string(),
+    bootstrapAdminPassword: z.string().role('secret'),
+    publicBaseUrl: z.string(),
+    oidcProviders: z.array(z.object({
+        id: z.string(),
+        label: z.string(),
+        issuer: z.string(),
+        clientId: z.string(),
+        clientSecret: z.string().role('secret'),
+        scopes: z.array(z.string()).default(['openid', 'profile', 'email']),
+        allowedSubjects: z.array(z.string()).default([]),
+        allowedEmailDomains: z.array(z.string()).default([]),
+        defaultRole: z.union(['admin', 'user']).default('user'),
+    })).default([]),
+    feishuAuth: z.object({
+        id: z.string().default('feishu'),
+        label: z.string().default('飞书'),
+        appId: z.string(),
+        appSecret: z.string().role('secret'),
+        authorizationUrl: z.string().default('https://accounts.feishu.cn/open-apis/authen/v1/authorize'),
+        baseUrl: z.string().default('https://open.feishu.cn'),
+        allowedOpenIds: z.array(z.string()).default([]),
+        defaultRole: z.union(['admin', 'user']).default('user'),
+    }),
+});
+registerFamilyNamespace(REMOTE_WEB_UI_SETTINGS_NAMESPACE, Config);
+/** The whole host-half behavior, factored for tests. */
+export function registerServerMode(ctx, config = {}, env = { dshHome: dshHome() }) {
+    return registerResources(own => registerOwnedServerMode(ctx, config, env, own));
+}
+function registerOwnedServerMode(ctx, config, env, own) {
+    let disposed = false;
+    own(() => { disposed = true; });
+    const home = env.dshHome;
+    const DEFAULTS = {
+        enabled: true,
+        integratedAuthEnabled: true,
+        legacyGatewayEnabled: false,
+        serverHost: '0.0.0.0',
+        serverPort: 3082,
+        cookieName: 'dsh_gw_session',
+        idleExpireMs: DEFAULT_IDLE_EXPIRE_MS,
+        maxAgeMs: DEFAULT_MAX_AGE_MS,
+        accountsFile: join(home, 'remote-web-ui-accounts.json'),
+        sessionsFile: join(home, 'remote-web-ui-sessions.json'),
+        oidcProviders: [],
+    };
+    // The live source the surfaces read: the settings section once the web
+    // settings surface is served, the composition entry otherwise.
+    let current = () => config ?? {};
+    const resolve = () => {
+        const value = current();
+        return {
+            enabled: value.enabled ?? DEFAULTS.enabled,
+            integratedAuthEnabled: value.integratedAuthEnabled ?? DEFAULTS.integratedAuthEnabled,
+            legacyGatewayEnabled: value.legacyGatewayEnabled ?? DEFAULTS.legacyGatewayEnabled,
+            serverHost: value.serverHost ?? DEFAULTS.serverHost,
+            serverPort: value.serverPort ?? DEFAULTS.serverPort,
+            serverTlsCert: value.serverTlsCert,
+            serverTlsKey: value.serverTlsKey,
+            cookieName: value.cookieName ?? DEFAULTS.cookieName,
+            idleExpireMs: value.idleExpireMs ?? DEFAULTS.idleExpireMs,
+            maxAgeMs: value.maxAgeMs ?? DEFAULTS.maxAgeMs,
+            accountsFile: value.accountsFile ?? DEFAULTS.accountsFile,
+            sessionsFile: value.sessionsFile ?? DEFAULTS.sessionsFile,
+            bootstrapAdminUsername: value.bootstrapAdminUsername,
+            bootstrapAdminPassword: value.bootstrapAdminPassword,
+            publicBaseUrl: value.publicBaseUrl,
+            oidcProviders: value.oidcProviders ?? DEFAULTS.oidcProviders,
+            feishuAuth: value.feishuAuth?.appId && value.feishuAuth.appSecret ? value.feishuAuth : undefined,
+        };
+    };
+    // ── stores (rebuilt when a configured file path changes) ────────────────
+    let accountsFile = '';
+    let sessionsFile = '';
+    let accounts = new AccountStore(DEFAULTS.accountsFile, { now: () => Date.now(), randomSalt });
+    let sessions = new SessionStore(DEFAULTS.sessionsFile, { now: () => Date.now(), randomId: randomSessionId }, { idleExpireMs: DEFAULTS.idleExpireMs, maxAgeMs: DEFAULTS.maxAgeMs });
+    let externalAuthKey = '';
+    let externalAuth = new ExternalAuthService({});
+    const limiter = new LoginLimiter();
+    const ensureStores = () => {
+        const value = resolve();
+        if (value.accountsFile === accountsFile && value.sessionsFile === sessionsFile)
+            return;
+        accountsFile = value.accountsFile;
+        sessionsFile = value.sessionsFile;
+        const now = () => Date.now();
+        accounts = new AccountStore(accountsFile, { now, randomSalt });
+        sessions = new SessionStore(sessionsFile, { now, randomId: randomSessionId }, { idleExpireMs: value.idleExpireMs, maxAgeMs: value.maxAgeMs });
+        sessions.bindAccounts(accounts);
+    };
+    sessions.bindAccounts(accounts);
+    const ensureExternalAuth = () => {
+        const value = resolve();
+        const key = JSON.stringify({ oidc: value.oidcProviders, feishu: value.feishuAuth });
+        if (key !== externalAuthKey) {
+            externalAuthKey = key;
+            externalAuth = new ExternalAuthService({ oidc: value.oidcProviders, feishu: value.feishuAuth });
+        }
+        return externalAuth;
+    };
+    // Compose the account session into DSH's own BrowserAuth. Connection keeps
+    // owning Host/Origin trust and the launch-token break-glass flow; its native
+    // index, HTTP RPC and /api/remote.mux paths all consult these methods.
+    const connection = ctx.connection
+        ?? ctx.get?.call(ctx, 'connection', false);
+    if (connection === undefined)
+        throw new Error('remote-web-ui: connection service unavailable for integrated WebAuth');
+    own(installIntegratedBrowserAuth(connection, {
+        enabled: () => resolve().enabled && resolve().integratedAuthEnabled,
+        hasSession: (request) => {
+            ensureStores();
+            const sessionId = readCookie(request.headers.cookie, resolve().cookieName);
+            try {
+                return sessionId !== undefined && sessions.touch(sessionId) !== undefined;
+            }
+            catch {
+                return false;
+            }
+        },
+    }));
+    // ── first-run bootstrap ─────────────────────────────────────────────────
+    const applyBootstrap = () => {
+        const value = resolve();
+        if (accounts.canBootstrap()
+            && value.bootstrapAdminUsername !== undefined
+            && value.bootstrapAdminPassword !== undefined
+            && value.bootstrapAdminPassword.length >= 8) {
+            accounts.create(value.bootstrapAdminUsername, value.bootstrapAdminPassword, 'admin');
+            console.log(`remote-web-ui: bootstrapped the first admin account "${value.bootstrapAdminUsername}"`);
+        }
+    };
+    // ── gateway lifecycle ───────────────────────────────────────────────────
+    const webServerPort = ctx.webServer.port;
+    const tlsConfiguredOf = (value) => value.serverTlsCert !== undefined && value.serverTlsCert !== ''
+        && value.serverTlsKey !== undefined && value.serverTlsKey !== '';
+    const buildStatus = () => {
+        const value = resolve();
+        return {
+            loginRequired: true,
+            cookieName: value.cookieName,
+            tls: false,
+            noAccounts: accounts.isEmpty(),
+            port: value.serverPort,
+            host: value.serverHost,
+            secure: tlsConfiguredOf(value),
+        };
+    };
+    let status = buildStatus();
+    let gateway;
+    let gatewayKey = '';
+    let gatewayTail = Promise.resolve();
+    own(() => {
+        disposed = true;
+        // Drain already queued starts too: an in-flight start may not yet have
+        // published its Gateway into `gateway` when synchronous rollback runs.
+        gatewayTail = gatewayTail.catch(() => { }).then(async () => {
+            const old = gateway;
+            gateway = undefined;
+            if (old !== undefined)
+                await old.close();
+        });
+        void gatewayTail.catch(error => { console.error('remote-web-ui: gateway cleanup failed:', error); });
+    });
+    let noAccountsLogged = false;
+    const sessionRoutes = () => {
+        const value = resolve();
+        ensureStores();
+        return makeGatewayRequestHandler('session', {
+            accounts,
+            sessions,
+            cookieName: value.cookieName,
+            secure: tlsConfiguredOf(value),
+            limiter,
+            status,
+            onAccountsChanged: applyGateway,
+        });
+    };
+    const loopbackRoutes = () => {
+        ensureStores();
+        return makeGatewayRequestHandler('loopback', {
+            accounts,
+            sessions,
+            cookieName: resolve().cookieName,
+            secure: false,
+            limiter,
+            status,
+            onAccountsChanged: applyGateway,
+        });
+    };
+    /** (Re)apply the listener after config/store changes. Serialized. */
+    const applyGateway = () => {
+        if (disposed)
+            return;
+        const value = resolve();
+        const tlsOn = tlsConfiguredOf(value);
+        const key = `${value.serverHost}|${value.serverPort}|${tlsOn}|${value.cookieName}|${value.accountsFile}|${value.sessionsFile}`;
+        gatewayTail = gatewayTail.then(async () => {
+            if (disposed)
+                return;
+            const shouldRun = resolve().enabled && resolve().legacyGatewayEnabled && !accounts.isEmpty();
+            if (gateway !== undefined && (!shouldRun || key !== gatewayKey)) {
+                const old = gateway;
+                gateway = undefined;
+                gatewayKey = '';
+                await old.close();
+            }
+            if (disposed)
+                return;
+            if (shouldRun && gateway === undefined) {
+                const next = new Gateway({
+                    host: value.serverHost,
+                    port: value.serverPort,
+                    tlsCert: tlsOn ? value.serverTlsCert : undefined,
+                    tlsKey: tlsOn ? value.serverTlsKey : undefined,
+                    upstreamPort: webServerPort,
+                    cookieName: value.cookieName,
+                    routes: sessionRoutes(),
+                    // Integrated WebAuth owns login/session on the DSH origin. The legacy
+                    // listener stays a pure transport for those paths so the login page,
+                    // provider list and cookies always describe the real browser origin.
+                    proxyAuthRoutes: value.integratedAuthEnabled,
+                }, sessions);
+                try {
+                    await next.start();
+                    if (disposed) {
+                        await next.close();
+                        return;
+                    }
+                    gateway = next;
+                    gatewayKey = key;
+                    console.log(`remote-web-ui: gateway listening on ${tlsOn ? 'https' : 'http'}://${value.serverHost}:${String(next.port)}${tlsOn ? ' (TLS)' : ' — WARNING: no TLS, plaintext LAN session'}`);
+                    const scheme = next.secure ? 'https' : 'http';
+                    const urls = lanIPv4Addresses().map(ip => `${scheme}://${ip}:${String(next.port)}/`).join(' , ');
+                    console.log(`remote-web-ui: server reachable on the LAN at ${urls}`);
+                    status.noAccounts = false;
+                }
+                catch (error) {
+                    // start() may already have allocated its server before rejecting.
+                    await next.close().catch(cleanupError => { console.error('remote-web-ui: failed gateway cleanup:', cleanupError); });
+                    console.error(`remote-web-ui: gateway failed to start on ${value.serverHost}:${String(value.serverPort)}:`, error);
+                }
+            }
+            // Refresh the status probe the admin surface and boot redirect read.
+            status = buildStatus();
+            if (gateway !== undefined)
+                status.secure = gateway.secure;
+            const empty = accounts.isEmpty();
+            status.noAccounts = empty;
+            if (empty && resolve().enabled && (resolve().integratedAuthEnabled || resolve().legacyGatewayEnabled) && !noAccountsLogged) {
+                noAccountsLogged = true;
+                console.error('remote-web-ui: FAIL-CLOSED — no accounts exist, the gateway is held. Create the first admin account at http://127.0.0.1:3080/api/gateway/accounts (loopback only) or set bootstrapAdminUsername/bootstrapAdminPassword in the plugin config.');
+            }
+        });
+    };
+    const requestOrigin = (request) => {
+        const configured = resolve().publicBaseUrl;
+        if (configured !== undefined && configured !== '')
+            return new URL(configured).origin;
+        const host = request.headers.host;
+        if (typeof host !== 'string' || host === '')
+            throw new Error('missing request Host');
+        const forwarded = request.headers['x-forwarded-proto'];
+        const protocol = typeof forwarded === 'string' && forwarded.split(',')[0].trim() === 'https' ? 'https' : 'http';
+        return `${protocol}://${host}`;
+    };
+    const externalAuthHandler = async (request, response) => {
+        try {
+            const url = new URL(request.url ?? '/', 'http://dsh.invalid');
+            const match = /^\/auth\/([a-z][a-z0-9-]{1,31})\/(start|callback)$/.exec(url.pathname);
+            if (request.method !== 'GET' || match === null) {
+                response.writeHead(404);
+                response.end();
+                return;
+            }
+            const providerId = match[1];
+            const action = match[2];
+            const callback = `${requestOrigin(request)}/auth/${providerId}/callback`;
+            if (action === 'start') {
+                const next = safeLoginTarget(url.searchParams.get('next') ?? '/');
+                const target = await ensureExternalAuth().begin(providerId, callback, next);
+                response.writeHead(302, { location: target.href, 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' });
+                response.end();
+                return;
+            }
+            if (url.searchParams.get('error') !== null)
+                throw new Error('external authorization was declined');
+            const code = url.searchParams.get('code');
+            const stateValue = url.searchParams.get('state');
+            if (code === null || stateValue === null)
+                throw new Error('authorization callback is missing code or state');
+            const result = await ensureExternalAuth().callback(providerId, callback, code, stateValue);
+            ensureStores();
+            const username = externalAccountName(result.principal);
+            const account = accounts.ensureExternal(username, result.principal.role);
+            if (!account.enabled)
+                throw new Error('external account is disabled');
+            const session = sessions.issue(username, account.role, { userAgent: request.headers['user-agent'], ip: request.socket.remoteAddress });
+            response.writeHead(303, {
+                location: safeLoginTarget(result.next),
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+                'set-cookie': makeSetCookie(resolve().cookieName, session.id, { secure: requestOrigin(request).startsWith('https:'), maxAgeSeconds: Math.floor(resolve().maxAgeMs / 1000) }),
+            });
+            response.end();
+        }
+        catch (error) {
+            response.writeHead(400, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'referrer-policy': 'no-referrer' });
+            response.end(`<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>登录失败</title><main><h1>登录失败</h1><p>${String(error instanceof Error ? error.message : error).replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character] ?? character))}</p><p><a href="/login">返回登录</a></p></main>`);
+        }
+    };
+    const providerListHandler = (_request, response) => {
+        writeJson(response, 200, { ok: true, providers: ensureExternalAuth().list() });
+    };
+    const originStatus = (request) => {
+        const origin = requestOrigin(request);
+        const address = new URL(origin);
+        return {
+            ...status,
+            host: address.hostname,
+            port: address.port === '' ? (address.protocol === 'https:' ? 443 : 80) : Number(address.port),
+            tls: address.protocol === 'https:',
+            secure: address.protocol === 'https:',
+        };
+    };
+    const integratedSessionHandler = (request) => makeGatewayRequestHandler('session', {
+        accounts,
+        sessions,
+        cookieName: resolve().cookieName,
+        secure: requestOrigin(request).startsWith('https:'),
+        limiter,
+        status: originStatus(request),
+        onAccountsChanged: sync,
+    });
+    const integratedLoginHandler = async (request, response) => {
+        await integratedSessionHandler(request)(request, response);
+    };
+    const integratedGatewayHandler = async (request, response) => {
+        const url = new URL(request.url ?? '/', 'http://webserver.local');
+        const method = request.method ?? 'GET';
+        if (isPreAuthGatewayPath(method, url.pathname) || !isLoopbackAdmin(request)) {
+            await integratedSessionHandler(request)(request, response);
+            return;
+        }
+        await loopbackRoutes()(request, response);
+    };
+    /** Every webServer route, rebuilt when settings change. */
+    const routes = () => [
+        { kind: 'exact', path: '/login', handler: integratedLoginHandler },
+        { kind: 'exact', path: '/api/gateway/auth/providers', handler: providerListHandler },
+        { kind: 'prefix', path: '/auth', handler: externalAuthHandler },
+        { kind: 'prefix', path: GATEWAY_API_PREFIX, handler: integratedGatewayHandler },
+    ];
+    // ── posture probe ───────────────────────────────────────────────────────
+    // Guardrail for the seam this plugin cannot close itself: the SDK's /api
+    // Host fence. Forged-Host probes against every LAN literal make a
+    // re-opened /api (a re-added --trusted-host, or the SDK's LAN auto-trust
+    // under 0.0.0.0) visible on the log instead of silently trusted.
+    let postureKey;
+    let postureWasExposed = false;
+    const runPostureProbe = () => {
+        if (disposed || !resolve().enabled)
+            return;
+        const targets = postureTargets(undefined, lanIPv4Addresses(), webServerPort);
+        if (targets.length === 0) {
+            postureKey = undefined;
+            return;
+        }
+        const key = targets.join('|');
+        const claim = claimPostureKey(postureKey, key);
+        if (!claim.run)
+            return;
+        postureKey = claim.next;
+        void probePosture({ port: webServerPort, targets }).then((snapshot) => {
+            const exposedHosts = snapshot.hosts.filter(host => host.exposed).map(host => host.host);
+            const exposed = exposedHosts.length > 0;
+            if (exposed && !postureWasExposed) {
+                console.error(`remote-web-ui: CRITICAL — the /api fence is OPEN for [${exposedHosts.join(', ')}]: requests that bypass the gateway reach the full host API. Remove --trusted-host for these hosts or bind loopback (the gateway is the only public door).`);
+            }
+            else if (!exposed && postureWasExposed) {
+                console.log('remote-web-ui: the /api posture probe is clean again (every LAN literal refused with 403).');
+            }
+            postureWasExposed = exposed;
+        }).catch(() => {
+            postureKey = releasePostureKey(postureKey, key);
+        });
+    };
+    // The first round waits for the connection plugin's /api route: a probe
+    // before it mounts would read the SPA fallback and false-positive.
+    const initialPostureTimer = nodeSetTimeout(() => { runPostureProbe(); }, 5_000);
+    own(() => { clearTimeout(initialPostureTimer); });
+    initialPostureTimer.unref();
+    // ── sync: register routes + (re)apply the gateway on every change ──────
+    let disposeRoutes;
+    own(() => { disposeRoutes?.(); disposeRoutes = undefined; });
+    const sync = () => {
+        if (disposed)
+            return;
+        ensureStores();
+        applyBootstrap();
+        if (disposeRoutes !== undefined) {
+            disposeRoutes();
+            disposeRoutes = undefined;
+        }
+        if (resolve().enabled) {
+            disposeRoutes = registerResources(ownRoute => {
+                for (const route of routes())
+                    ownRoute(ctx.webServer.register(route));
+            });
+        }
+        applyGateway();
+    };
+    // Session sweep cadence: drop expired sessions promptly so the store file
+    // and the admin list never show dead rows.
+    const sessionSweepTimer = nodeSetInterval(() => { sessions.sweep(); }, 60_000);
+    own(() => { clearInterval(sessionSweepTimer); });
+    sessionSweepTimer.unref();
+    // Inject the server-mode boot script that declares gateway host ownership
+    // (with a login redirect for unsigned sessions). The shared remote-access
+    // domain owns the remote-entry boot row plus the plain-HTTP shims, so this
+    // domain adds only its gateway-specific row.
+    own(ctx.on('webserver/index-inject', (table) => {
+        table.push({ kind: 'script', placement: 'head', text: SERVER_BOOT_SCRIPT });
+    }));
+    // 0.2：命名空间值取自聚合条目 Config 的 volatile 引用；设置变更由 loader 原地
+    // 热更新，userspace 只需在文档变更事件上重新 apply。
+    current = () => familyNamespace(REMOTE_WEB_UI_SETTINGS_NAMESPACE) ?? config ?? {};
+    own(onFamilyConfigChange(() => { sync(); }));
+    sync();
+}

package/lib/types/host/services/resources.d.ts

@@ -0,0 +1,9 @@
+/** Registration transactions for resources owned by one service domain. */
+import type { ServiceDisposer } from './lifecycle.ts';
+/** Record a disposer immediately after acquiring its resource. */
+export type OwnResource<T extends ServiceDisposer = ServiceDisposer> = <D extends T>(dispose: D) => D;
+/** Roll back partial synchronous setup and dispose every resource in reverse order. */
+export declare function registerResources(setup: (own: OwnResource<() => void>) => void): () => void;
+/** Await rollback before rejecting asynchronous setup; disposal is single-shot and awaitable. */
+export declare function registerAsyncResources(setup: (own: OwnResource) => Promise<void>): Promise<() => Promise<void>>;
+//# sourceMappingURL=resources.d.ts.map

package/lib/types/host/services/resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resources.d.ts","sourceRoot":"","sources":["../../../../src/host/services/resources.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAErD,kEAAkE;AAClE,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,eAAe,IAAI,CAAC,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;AAMrG,uFAAuF;AACvF,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC,MAAM,IAAI,CAAC,KAAK,IAAI,GAAG,MAAM,IAAI,CAyB3F;AAED,iGAAiG;AACjG,wBAAsB,sBAAsB,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAsCrH"}

package/lib/types/host/services/resources.js

@@ -0,0 +1,98 @@
+function failure(errors) {
+    if (errors.length > 0)
+        throw new AggregateError(errors, 'service resource cleanup failed');
+}
+/** Roll back partial synchronous setup and dispose every resource in reverse order. */
+export function registerResources(setup) {
+    const resources = [];
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        const errors = [];
+        for (const release of resources.splice(0).reverse()) {
+            try {
+                release();
+            }
+            catch (error) {
+                errors.push(error);
+            }
+        }
+        failure(errors);
+    };
+    try {
+        setup(release => {
+            if (disposed)
+                release();
+            else
+                resources.push(release);
+            return release;
+        });
+        return dispose;
+    }
+    catch (error) {
+        try {
+            dispose();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'service registration and rollback failed');
+        }
+        throw error;
+    }
+}
+/** Await rollback before rejecting asynchronous setup; disposal is single-shot and awaitable. */
+export async function registerAsyncResources(setup) {
+    const resources = [];
+    let disposing;
+    const dispose = () => {
+        disposing ??= (async () => {
+            const errors = [];
+            for (const release of resources.splice(0).reverse()) {
+                try {
+                    await release();
+                }
+                catch (error) {
+                    errors.push(error);
+                }
+            }
+            failure(errors);
+        })();
+        return disposing;
+    };
+    try {
+        await setup(release => {
+            if (disposing === undefined)
+                resources.push(release);
+            else {
+                // A failed setup may still have uncancelled asynchronous callbacks.
+                // Own their late acquisitions instead of stranding them after rollback.
+                let cleanup;
+                try {
+                    cleanup = release();
+                }
+                catch (error) {
+                    cleanup = Promise.reject(error);
+                }
+                const late = Promise.resolve(cleanup);
+                void late.catch(() => { });
+                disposing = Promise.allSettled([disposing, late]).then(results => {
+                    const errors = results.flatMap(result => result.status === 'rejected' ? [result.reason] : []);
+                    failure(errors);
+                });
+                void disposing.catch(() => { });
+            }
+            return release;
+        });
+        return dispose;
+    }
+    catch (error) {
+        try {
+            await dispose();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], 'service registration and rollback failed');
+        }
+        throw error;
+    }
+}

package/lib/types/host/services/right-pane/browser.d.ts

@@ -0,0 +1,42 @@
+export declare function extractFrameAncestors(csp: string | null): string[] | undefined;
+export interface BrowserProbe {
+    url: string;
+    status: number;
+    ok: boolean;
+    xFrameOptions?: string;
+    frameAncestors?: string[];
+    embeddable: boolean;
+}
+/** A refused destination, or the normalized URL the probe may fetch. */
+export type ProbeTargetVerdict = {
+    kind: 'ok';
+    url: string;
+} | {
+    kind: 'blocked';
+    reason: string;
+};
+/** Redirect hops the probe follows before it reports the last response as-is. */
+export declare const MAX_PROBE_REDIRECTS = 3;
+/**
+ * Whether the HOST may fetch this URL on a caller's behalf.
+ *
+ * The probe is an outbound request the caller never sees the body of, but its
+ * status and embeddability answer still make it a reconnaissance primitive:
+ * only public http(s) destinations are allowed, and every redirect hop is
+ * judged by the same rule.
+ * @param raw - the caller-supplied URL.
+ * @returns the normalized URL, or the reason the destination is refused.
+ */
+export declare function evaluateProbeTarget(raw: string): ProbeTargetVerdict;
+/**
+ * Probe one public URL for embeddability.
+ *
+ * Redirects are followed manually so each hop passes the destination policy;
+ * after {@link MAX_PROBE_REDIRECTS} hops the last response is reported as-is.
+ * @param raw - the caller-supplied URL.
+ * @param fetchImpl - fetch implementation (injected for tests).
+ * @param signal - abort signal bounding the whole probe.
+ * @returns the probe result for the final response.
+ */
+export declare function probeBrowserUrl(raw: string, fetchImpl?: typeof fetch, signal?: AbortSignal): Promise<BrowserProbe>;
+//# sourceMappingURL=browser.d.ts.map

package/lib/types/host/services/right-pane/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../../../../src/host/services/right-pane/browser.ts"],"names":[],"mappings":"AAEA,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,SAAS,CAI9E;AACD,MAAM,WAAW,YAAY;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE;AAElJ,wEAAwE;AACxE,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAElG,iFAAiF;AACjF,eAAO,MAAM,mBAAmB,IAAI,CAAA;AA6BpC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAkBnE;AASD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,KAAa,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAgB/H"}