@zq-silk/yui 2.8.1 → 2.10.0

package/dist/web/controllerWeb.js

@@ -1,59 +1,111 @@
 import { parseWebCommandOptions, startYuiWebServer } from "./webServer.js";
+import { parseDurableJobCaller } from "../controller/jobControl.js";
+import { requireManagedGlobalCaller } from "../runtime/managedCaller.js";
 /** HTTP listener ownership only, alongside the Controller's one Kernel Host.
  * The authenticated Controller control socket starts/stops the exact listener;
  * no capability identity is accepted through this lifecycle API. */
 export function createControllerWeb(store, dependencies) {
     let current;
-    let starting = false;
-    const close = async () => {
+    let shutdown = false;
+    let startup;
+    let closing;
+    const closeListener = async () => {
+        if (closing)
+            return closing;
         const owned = current;
         if (!owned)
             return;
-        current = undefined;
         owned.server.closeTerminals();
-        await new Promise((resolve, reject) => {
+        closing = new Promise((resolve, reject) => {
             owned.server.close((error) => error ? reject(error) : resolve());
             owned.server.closeAllConnections();
         });
+        try {
+            await closing;
+            current = undefined;
+        }
+        finally {
+            closing = undefined;
+        }
     };
     return {
-        close,
+        async close() {
+            shutdown = true;
+            // A Controller shutdown must also own a bind still in flight.
+            if (startup)
+                await startup.catch(() => undefined);
+            await closeListener();
+        },
         async dispatch(method, value) {
             if (!value || typeof value !== "object" || Array.isArray(value))
                 throw new Error("Invalid Web listener request.");
             const params = value;
+            // The control socket proves the local Home/user boundary. Managed
+            // callers additionally retain their current native identity; no Web
+            // token or browser-user credential is issued by this API.
+            const caller = parseDurableJobCaller(params.caller);
+            if (caller.scope === "user") {
+                if (Object.keys(caller).length !== 1)
+                    throw new Error("Invalid local Web caller.");
+            }
+            else {
+                if (caller.scope !== "global" || caller.role !== "operator" || caller.taskId !== undefined || caller.runId !== undefined) {
+                    throw new Error("Only the current global Operator may manage Web listeners.");
+                }
+                requireManagedGlobalCaller(store, {
+                    YUI_SESSION_SCOPE: "global", YUI_ROLE: caller.role, YUI_AGENT_ID: caller.agentId,
+                    YUI_ADAPTER_ID: caller.adapterId, YUI_NATIVE_SESSION_ID: caller.nativeSessionId
+                });
+            }
             if (method === "web.status") {
-                if (Object.keys(params).length)
+                if (Object.keys(params).some(key => key !== "caller"))
                     throw new Error("Web status takes no arguments.");
-                return current ? { id: current.id, url: current.url } : null;
+                return current ? { ...current.status, state: closing ? "stopping" : "running" }
+                    : startup ? { state: "starting" } : null;
             }
             if (method === "web.stop") {
-                if (Object.keys(params).some((key) => key !== "id") || typeof params.id !== "string")
+                if (Object.keys(params).some((key) => !["id", "caller"].includes(key)) || typeof params.id !== "string")
                     throw new Error("Expected Web listener id.");
+                if (startup)
+                    throw new Error("Web listener is starting; query status before retrying.");
                 if (!current)
                     return { stopped: false };
-                if (current.id !== params.id)
+                if (current.status.id !== params.id)
                     throw new Error("Web listener identity changed.");
-                await close();
+                await closeListener();
                 return { stopped: true };
             }
-            if (method !== "web.start" || Object.keys(params).some((key) => !["id", "host", "port"].includes(key))
+            if (method !== "web.start" || Object.keys(params).some((key) => !["id", "host", "port", "authFile", "caller"].includes(key))
                 || typeof params.id !== "string" || !params.id.trim()
-                || typeof params.host !== "string" || typeof params.port !== "number") {
+                || typeof params.host !== "string" || typeof params.port !== "number"
+                || (params.authFile !== undefined && typeof params.authFile !== "string")) {
                 throw new Error("Expected id, host and port for Web start.");
             }
-            const options = parseWebCommandOptions(["--host", params.host, "--port", String(params.port)]);
-            if (starting || current)
-                throw new Error("A Web listener is already starting or running in this Controller.");
-            starting = true;
+            const options = parseWebCommandOptions(["--host", params.host, "--port", String(params.port),
+                ...(typeof params.authFile === "string" ? ["--auth-file", params.authFile] : [])]);
+            if (shutdown)
+                throw new Error("Controller Web lifecycle is shutting down.");
+            if (startup || closing)
+                throw new Error("Web listener lifecycle is busy; query status before retrying.");
+            if (current) {
+                if (current.status.host === options.host && current.status.port === options.port && current.authFile === options.authFile) {
+                    return { ...current.status, state: "running", alreadyRunning: true };
+                }
+                throw new Error("A different Web listener is already running. Inspect --status and explicitly --stop before changing its configuration.");
+            }
             try {
-                const server = await startYuiWebServer(store, options, dependencies);
-                const url = `http://${options.host === "::1" ? "[::1]" : options.host}:${options.port}`;
-                current = { id: params.id, server, url };
-                return { id: params.id, url };
+                startup = startYuiWebServer(store, options, dependencies);
+                const server = await startup;
+                const { urls, authentication, warnings } = server.access;
+                const status = { id: params.id, host: options.host, port: options.port,
+                    url: urls[0] ?? null, urls, authentication, warnings };
+                current = { status, server, authFile: options.authFile };
+                if (shutdown)
+                    throw new Error("Controller shut down before Web startup completed.");
+                return { ...status, state: "running", alreadyRunning: false };
             }
             finally {
-                starting = false;
+                startup = undefined;
             }
         }
     };

package/dist/web/taskPreviews.js

@@ -13,6 +13,16 @@ export function createTaskPreviews(store, home) {
     const secret = randomBytes(32);
     const key = (taskId, jobId) => createHmac("sha256", secret).update(JSON.stringify([taskId, jobId])).digest("base64url");
     const prefix = (job) => `/preview/${encodeURIComponent(job.taskId)}/${encodeURIComponent(job.id)}/${key(job.taskId, job.id)}/`;
+    const ticketTarget = (request) => {
+        const url = new URL(request.url ?? "/", "http://localhost");
+        const match = /^\/preview\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/(.*)$/.exec(url.pathname);
+        if (!match || (request.method !== "GET" && request.method !== "HEAD"))
+            return undefined;
+        const [, taskId, jobId, ticket, path] = match;
+        const expected = key(taskId, jobId);
+        return ticket.length === expected.length && timingSafeEqual(Buffer.from(ticket), Buffer.from(expected))
+            ? { taskId: taskId, jobId: jobId, path: path, search: url.search } : undefined;
+    };
     const registered = (taskId, jobId) => {
         const job = store.getDurableJob(taskId, jobId);
         if (!store.getTask(taskId) || !job || job.taskId !== taskId || !isHttpPreview(job.env)) {
@@ -52,6 +62,10 @@ export function createTaskPreviews(store, home) {
         return result;
     };
     return {
+        // Issued only by the authenticated list API. This credential authorizes
+        // one preview's reads, not the main page, APIs, writes or Terminal.
+        // Opaque sandbox fetch/module requests intentionally carry no user auth.
+        authenticated(request) { return ticketTarget(request) !== undefined; },
         async list(taskId) {
             if (!store.getTask(taskId))
                 throw new WebRequestRejected("Task not found.");
@@ -102,27 +116,21 @@ export function createTaskPreviews(store, home) {
             });
         },
         async serve(request, response) {
-            const url = new URL(request.url ?? "/", "http://localhost");
-            const match = /^\/preview\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/([A-Za-z0-9_-]+)\/(.*)$/.exec(url.pathname);
             const fail = (status, detail) => {
                 response.statusCode = status;
                 response.setHeader("content-type", "text/plain; charset=utf-8");
                 response.end(detail);
             };
-            if (!match) {
-                fail(403, "Invalid preview ticket.");
+            if (request.method !== "GET" && request.method !== "HEAD") {
+                fail(405, "Preview supports GET and HEAD only.");
                 return;
             }
-            const [, taskId, jobId, ticket, path] = match;
-            const expected = key(taskId, jobId);
-            if (ticket.length !== expected.length || !timingSafeEqual(Buffer.from(ticket), Buffer.from(expected))) {
+            const target = ticketTarget(request);
+            if (!target) {
                 fail(403, "Invalid preview ticket.");
                 return;
             }
-            if (request.method !== "GET" && request.method !== "HEAD") {
-                fail(405, "Preview supports GET and HEAD only.");
-                return;
-            }
+            const { taskId, jobId, path, search } = target;
             let job;
             try {
                 job = registered(taskId, jobId);
@@ -134,7 +142,7 @@ export function createTaskPreviews(store, home) {
                 return;
             }
             try {
-                const result = await read(job, "/" + path + url.search, request.method);
+                const result = await read(job, "/" + path + search, request.method);
                 const base = prefix(job);
                 // No upstream CSP, cookies, auth, redirects, or CORS escape this boundary.
                 const source = `http://${request.headers.host}${base}`;
@@ -155,7 +163,7 @@ export function createTaskPreviews(store, home) {
                         fail(502, "External/absolute redirects are not supported in preview.");
                         return;
                     }
-                    const target = new URL(result.location, "http://preview.invalid/" + path + url.search);
+                    const target = new URL(result.location, "http://preview.invalid/" + path + search);
                     response.setHeader("location", base + target.pathname.slice(1) + target.search + target.hash);
                 }
                 response.statusCode = result.status;

package/dist/web/webAccess.js

@@ -0,0 +1,109 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { closeSync, constants, fstatSync, openSync, readFileSync } from "node:fs";
+import { isIP } from "node:net";
+import { networkInterfaces } from "node:os";
+import { isAbsolute } from "node:path";
+export function isLoopbackAddress(host) {
+    return host === "localhost" || host === "::1" || /^127\./.test(host) && isIP(host) === 4;
+}
+/** Only numeric private addresses are advertised/accepted for LAN access.
+ * DNS aliases and proxy headers are deliberately not an authentication input. */
+export function isPrivateAddress(host) {
+    return isIP(host) === 4
+        ? /^(10\.|192\.168\.|172\.(1[6-9]|2[0-9]|3[01])\.)/.test(host)
+        : isIP(host) === 6 && /^f[cd]/i.test(host);
+}
+export function validateWebAccessOptions(options) {
+    if (!isLoopbackAddress(options.host) && !isPrivateAddress(options.host)
+        && options.host !== "0.0.0.0" && options.host !== "::") {
+        throw new Error("Web host must be localhost, a loopback/private IP address, 0.0.0.0 or ::.");
+    }
+    if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
+        throw new Error("Web port must be an integer between 1 and 65535.");
+    }
+    if (!isLoopbackAddress(options.host) && !options.authFile) {
+        throw new Error("Non-loopback Web access requires --auth-file <absolute-path>.");
+    }
+    if (options.authFile !== undefined && !isAbsolute(options.authFile)) {
+        throw new Error("--auth-file must be an absolute path to an owner-only password file.");
+    }
+}
+function passwordDigest(path) {
+    let fd;
+    try {
+        fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        const stat = fstatSync(fd);
+        if (!stat.isFile() || (stat.mode & 0o077) !== 0 || stat.uid !== process.getuid?.()
+            || stat.size < 32 || stat.size > 256)
+            throw new Error("invalid credential file");
+        const password = readFileSync(fd, "utf8").replace(/\r?\n$/, "");
+        if (!/^[\x21-\x7e]{32,128}$/.test(password))
+            throw new Error("invalid password");
+        return createHash("sha256").update(`Basic ${Buffer.from(`yui:${password}`).toString("base64")}`).digest();
+    }
+    catch {
+        // Never include file contents, OS error text or a submitted credential.
+        throw new Error("Cannot load Web credential: use a regular owner-only (0600) file containing a unique 32–128 character ASCII password. Then restart Web.");
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+export function createWebAccess(options, interfaces = networkInterfaces()) {
+    validateWebAccessOptions(options);
+    const lan = !isLoopbackAddress(options.host);
+    const digest = options.authFile === undefined ? undefined : passwordDigest(options.authFile);
+    const wildcard = options.host === "0.0.0.0" || options.host === "::";
+    const canonicalHost = (host) => isIP(host) === 6
+        ? new URL(`http://[${host}]`).hostname.slice(1, -1) : host;
+    const addresses = (wildcard
+        ? [...new Set(Object.values(interfaces).flatMap(entries => entries ?? [])
+                .filter(entry => isPrivateAddress(entry.address) && (options.host === "::" || entry.family === "IPv4"))
+                .map(entry => entry.address))]
+        : [options.host]).map(canonicalHost);
+    const allowed = new Set(!lan || wildcard ? [...addresses, "127.0.0.1", "::1", "localhost"] : addresses);
+    const urlHost = (host) => isIP(host) === 6 ? `[${host}]` : host;
+    const urls = addresses.map(host => `http://${urlHost(host)}:${options.port}`);
+    const warnings = lan ? [
+        "HTTP is not encrypted. Use only a trusted network; credentials and data are visible to network observers.",
+        ...(wildcard ? ["Wildcard binding listens on all matching interfaces, including public ones. Yui does not open firewall ports or tunnels."] : []),
+        ...(!urls.length ? ["No usable private interface address was found. Check interfaces or bind an explicit private address; reachability is not verified."] : [])
+    ] : [];
+    return {
+        lan,
+        authentication: digest ? "basic" : "local",
+        urls,
+        warnings,
+        acceptsHost(request) {
+            const host = request.headers.host;
+            if (!host)
+                return false;
+            try {
+                const url = new URL(`http://${host}`);
+                const hostname = url.hostname.replace(/^\[|\]$/g, "");
+                return allowed.has(hostname) && host === `${urlHost(hostname)}${request.socket.localPort === 80 ? "" : `:${request.socket.localPort}`}`
+                    && !url.username && !url.password && url.pathname === "/" && !url.search && !url.hash;
+            }
+            catch {
+                return false;
+            }
+        },
+        acceptsOrigin(request, requireOrigin = false, scopedPreview = false) {
+            const origin = request.headers.origin;
+            // Existing preview tickets authenticate only GET/HEAD of one sandboxed
+            // Job. Its opaque-origin modules/fetches must not inherit user credentials.
+            if (scopedPreview && (origin === undefined || origin === "null"))
+                return true;
+            return request.headers["sec-fetch-site"] !== "cross-site"
+                && (origin === undefined ? !requireOrigin : origin === `http://${request.headers.host}`);
+        },
+        authenticated(request) {
+            if (!digest)
+                return true;
+            const authorization = request.headers.authorization;
+            return typeof authorization === "string" && authorization.length <= 512
+                && timingSafeEqual(createHash("sha256").update(authorization).digest(), digest);
+        }
+    };
+}

package/dist/web/webJobs.js

@@ -0,0 +1,52 @@
+import { activeLiveRoleAgentSession } from "../executor/agentExecutor.js";
+import { createJobDefinitionControl } from "../controller/jobDefinitionControl.js";
+import { createScheduleControl } from "../controller/scheduleControl.js";
+import { requireKnownFields } from "../domain/validation.js";
+import { WebRequestRejected, webLocalMutation } from "./webMutation.js";
+/** Local-user ingress only, behind the Web token/origin boundary. Never use
+ * this adapter for managed RPC callers. The route fixes scope; the server
+ * resolves the current Operator binding on every request. No invented Session
+ * or durable second authority: the public services revalidate the binding.
+ */
+export function createWebJobs(store, home) {
+    function invoke(scope, family, value, write, now) {
+        const apply = (tx) => {
+            if (!value || typeof value !== "object" || Array.isArray(value))
+                throw new Error("Expected an operation.");
+            requireKnownFields(value, family === "jobs"
+                ? ["op", "id", "title", "configuration", "expectedRevision", "runId", "requestId"]
+                : ["op", "id", "jobId", "rule", "expectedRevision"], "Web Job/Schedule request");
+            const input = value;
+            const reads = family === "jobs" ? ["list", "show", "runs", "run-get", "logs"] : ["list", "show"];
+            const writes = family === "jobs" ? ["define", "update", "run", "run-cancel"] : ["create", "update", "enable", "disable"];
+            if (!(write ? writes : reads).includes(String(input.op)))
+                throw new Error("Operation is not available on this endpoint.");
+            if (scope.kind === "task" && !tx.getTask(scope.taskId))
+                throw new Error("Task not found.");
+            const session = activeLiveRoleAgentSession(tx.getGlobalRoleSessionSet("operator"));
+            if (!session)
+                throw new Error("A current Operator Session is required for Job management.");
+            const caller = { scope: "global", role: "operator", nativeSessionId: session.nativeSessionId,
+                agentId: session.agentId, adapterId: session.adapterId };
+            const { requestId, ...fields } = input;
+            if (input.op === "run" && (typeof requestId !== "string" || !requestId.trim() || requestId.length > 200)) {
+                throw new Error("Immediate execution requires a stable requestId.");
+            }
+            const params = { ...fields, scope, caller,
+                ...(input.op === "run" ? { trigger: { source: "manual", key: requestId } } : {}) };
+            return (family === "jobs" ? createJobDefinitionControl(tx, home) : createScheduleControl(tx, home))(params, now);
+        };
+        if (write)
+            return webLocalMutation(store, apply);
+        try {
+            return store.transaction(apply);
+        }
+        catch (error) {
+            throw new WebRequestRejected(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return {
+        read: (scope, family, value, now) => invoke(scope, family, value, false, now),
+        mutate: (scope, family, value, now) => invoke(scope, family, value, true, now)
+    };
+}

package/dist/web/webServer.js

@@ -1,6 +1,7 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
 import WebSocket, { WebSocketServer } from "ws";
+import { createWebAccess, validateWebAccessOptions } from "./webAccess.js";
 import { CliError, usageError } from "../errors/cliError.js";
 import { parseTaskCatalogOptions } from "../context/taskCatalog.js";
 import { parseTaskSearchOptions, searchTaskBodies } from "../context/taskSearch.js";
@@ -17,6 +18,7 @@ const MAX_TERMINAL_BUFFERED_BYTES = 1024 * 1024;
 export function parseWebCommandOptions(args) {
     let host = "127.0.0.1";
     let port = 4173;
+    let authFile;
     for (let index = 0; index < args.length; index += 1) {
         const option = args[index];
         const value = args[index + 1];
@@ -28,19 +30,25 @@ export function parseWebCommandOptions(args) {
             port = Number(value);
             index += 1;
         }
+        else if (option === "--auth-file" && value !== undefined) {
+            authFile = value;
+            index += 1;
+        }
         else {
             throw webUsageError();
         }
     }
-    if (!new Set(["127.0.0.1", "::1", "localhost"]).has(host)) {
-        throw usageError("Web host must be a loopback address (127.0.0.1, ::1, or localhost).", webUsage());
+    const options = { host, port, ...(authFile === undefined ? {} : { authFile }) };
+    try {
+        validateWebAccessOptions(options);
     }
-    if (!Number.isInteger(port) || port < 1 || port > 65_535) {
-        throw usageError("Web port must be an integer between 1 and 65535.", webUsage());
+    catch (error) {
+        throw usageError(error.message, webUsage());
     }
-    return { host, port };
+    return options;
 }
-export function createYuiWebServer(store, dependencies = {}) {
+export function createYuiWebServer(store, dependencies = {}, options = { host: "127.0.0.1", port: 4173 }) {
+    const access = createWebAccess(options);
     const now = dependencies.now ?? (() => new Date());
     const token = dependencies.token ?? randomBytes(24).toString("base64url");
     const httpDependencies = { ...dependencies, previews: dependencies.previews?.() };
@@ -50,7 +58,7 @@ export function createYuiWebServer(store, dependencies = {}) {
         maxPayload: MAX_TERMINAL_MESSAGE_BYTES
     });
     const server = createServer((request, response) => {
-        void handleHttpRequest(request, response, store, httpDependencies, token, now).catch(() => {
+        void handleHttpRequest(request, response, store, httpDependencies, token, now, access).catch(() => {
             if (!response.headersSent)
                 setSecurityHeaders(response);
             if (!response.writableEnded) {
@@ -59,7 +67,7 @@ export function createYuiWebServer(store, dependencies = {}) {
         });
     });
     server.on("upgrade", (request, socket, head) => {
-        void handleTerminalUpgrade(request, socket, head, webSocketServer, dependencies.terminal, token);
+        void handleTerminalUpgrade(request, socket, head, webSocketServer, dependencies.terminal, token, access);
     });
     let terminalsClosed = false;
     const closeTerminals = () => {
@@ -71,24 +79,36 @@ export function createYuiWebServer(store, dependencies = {}) {
         webSocketServer.close();
     };
     server.on("close", closeTerminals);
-    return Object.assign(server, { closeTerminals });
+    return Object.assign(server, { closeTerminals, access });
 }
 export async function startYuiWebServer(store, options, dependencies = {}) {
-    const server = createYuiWebServer(store, dependencies);
-    await new Promise((resolve, reject) => {
-        server.once("error", reject);
-        server.listen(options.port, options.host, () => {
-            server.off("error", reject);
-            resolve();
+    const server = createYuiWebServer(store, dependencies, options);
+    try {
+        await new Promise((resolve, reject) => {
+            server.once("error", reject);
+            server.listen(options.port, options.host, () => {
+                server.off("error", reject);
+                resolve();
+            });
         });
-    });
+    }
+    catch (error) {
+        server.closeTerminals();
+        throw error;
+    }
     return server;
 }
-async function handleHttpRequest(request, response, store, dependencies, token, now) {
+async function handleHttpRequest(request, response, store, dependencies, token, now, access) {
     setSecurityHeaders(response);
     const method = request.method ?? "GET";
-    if (!isLoopbackHost(headerValue(request, "host"))) {
-        sendJson(response, 403, { error: "Invalid Host.", disposition: "not-submitted" }, method === "HEAD");
+    const previewAuthenticated = dependencies.previews?.authenticated(request) === true;
+    if (!access.acceptsHost(request) || !access.acceptsOrigin(request, access.lan && method !== "GET" && method !== "HEAD", previewAuthenticated)) {
+        sendJson(response, 403, { error: "Invalid Host or Origin.", disposition: "not-submitted" }, method === "HEAD");
+        return;
+    }
+    if (!previewAuthenticated && !access.authenticated(request)) {
+        response.setHeader("www-authenticate", 'Basic realm="Yui Web", charset="UTF-8"');
+        sendJson(response, 401, { error: "Web authentication required. Use username yui and the configured password. To revoke access, stop Web; to rotate the password, replace the credential file and restart Web.", disposition: "not-submitted" }, method === "HEAD");
         return;
     }
     let pathname;
@@ -99,7 +119,8 @@ async function handleHttpRequest(request, response, store, dependencies, token,
         sendJson(response, 400, { error: "Invalid URL.", disposition: "not-submitted" }, method === "HEAD");
         return;
     }
-    // The loopback page token is the actual user ingress. A request body cannot
+    // Authentication precedes every document/preview. The page token remains
+    // an independent CSRF boundary. A request body cannot
     // select Operator/Leader authority; all API reads use this boundary too.
     if (pathname.startsWith("/api/") && !tokenMatches(headerValue(request, "x-yui-web-token"), token)) {
         sendJson(response, 403, { error: "Invalid Yui web token.", disposition: "not-submitted" }, method === "HEAD");
@@ -252,6 +273,37 @@ async function handleHttpRequest(request, response, store, dependencies, token,
         }
         return;
     }
+    const jobTarget = /^\/api\/(?:settings|(tasks)\/([^/]+))\/(jobs|schedules)$/.exec(pathname);
+    if (jobTarget) {
+        try {
+            if (!dependencies.jobs)
+                throw new WebRequestRejected("Job management unavailable.");
+            const scope = jobTarget[1] ? { kind: "task", taskId: decodeURIComponent(jobTarget[2]) }
+                : { kind: "global" };
+            const family = jobTarget[3];
+            let value;
+            if (method === "GET") {
+                const query = new URL(request.url, "http://localhost").searchParams;
+                if ([...query.keys()].some(key => !["op", "id", "runId"].includes(key)))
+                    throw new WebRequestRejected("Unknown Job query.");
+                value = dependencies.jobs.read(scope, family, Object.fromEntries(query), now());
+            }
+            else if (method === "POST") {
+                if (headerValue(request, "origin") !== `http://${headerValue(request, "host")}`) {
+                    throw new WebRequestRejected("Job changes require a same-origin request.");
+                }
+                value = dependencies.jobs.mutate(scope, family, await readMutationBody(request), now());
+            }
+            else
+                throw new WebRequestRejected("Method not allowed.");
+            sendJson(response, 200, value, false);
+        }
+        catch (error) {
+            sendJson(response, 409, { error: error instanceof Error ? error.message : "Job operation failed.",
+                disposition: error instanceof WebRequestRejected ? "not-submitted" : "unknown" }, false);
+        }
+        return;
+    }
     if (pathname === "/api/settings" || pathname === "/api/settings/group" || pathname === "/api/settings/capabilities") {
         try {
             if (!dependencies.settings)
@@ -683,10 +735,10 @@ async function handleHttpRequest(request, response, store, dependencies, token,
     response.setHeader("allow", "GET, HEAD");
     sendJson(response, 405, { error: "Method not allowed.", disposition: "not-submitted" }, method === "HEAD");
 }
-async function handleTerminalUpgrade(request, socket, head, webSocketServer, terminalPort, token) {
+async function handleTerminalUpgrade(request, socket, head, webSocketServer, terminalPort, token, access) {
     try {
         const url = new URL(request.url ?? "/", "http://localhost");
-        if (!isLoopbackHost(headerValue(request, "host"))) {
+        if (!access.acceptsHost(request) || !access.acceptsOrigin(request, true) || !access.authenticated(request)) {
             rejectUpgrade(socket, 403, "Forbidden");
             return;
         }
@@ -1048,26 +1100,6 @@ function headerValue(request, name) {
     const value = request.headers[name];
     return Array.isArray(value) ? value[0] : value;
 }
-function isLoopbackHost(value) {
-    if (value === undefined)
-        return false;
-    let url;
-    try {
-        url = new URL(`http://${value}`);
-    }
-    catch {
-        return false;
-    }
-    if (url.username.length > 0
-        || url.password.length > 0
-        || url.pathname !== "/"
-        || url.search.length > 0
-        || url.hash.length > 0) {
-        return false;
-    }
-    const hostname = url.hostname.toLowerCase();
-    return hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]";
-}
 function safeIdentity(value, label) {
     if (value === null || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(value)) {
         throw new Error(`${label} is invalid.`);
@@ -1091,8 +1123,8 @@ function escapeHtmlAttribute(value) {
         .replaceAll(">", "&gt;");
 }
 function webUsageError() {
-    return usageError("Web usage: yui web [--host <loopback>] [--port <port>].", webUsage());
+    return usageError("Invalid Web options.", webUsage());
 }
 function webUsage() {
-    return "Usage: yui web [--host <127.0.0.1|::1|localhost>] [--port <1-65535>]";
+    return "Usage: yui web [--host <IP|localhost>] [--port <1-65535>] [--auth-file <absolute-path>]";
 }

package/docs/architecture/capabilities-and-resources.md

@@ -122,12 +122,14 @@ catalog; there is no second catalog or Host. A CLI contribution uses the
 capability's original name. A Web panel accepts only controlled text, an HTTP(S)
 link or a JSON query description — not author scripts or arbitrary HTML.
 
-The Web listener is started and stopped by the Controller and allows loopback
-only (`127.0.0.1`, `::1` or `localhost`; default port 4173). `yui web` opens this
-local surface, not a remote multi-user service or an OS sandbox.
+The Controller owns the single Web listener, defaulting to `127.0.0.1:4173`.
+Explicit trusted-LAN binding requires a private credential file; authentication
+precedes documents, APIs, previews and Terminal. See [controlled Web access](../web-access.md).
+Current Operator lifecycle calls are revalidated separately from browser access.
+This is still a single-user surface, not a multi-user service or an OS sandbox.
 
 The page supplies a token that authenticates all HTTP API reads and writes via
-`x-yui-web-token`; the server also checks the loopback Host. These controls act
+`x-yui-web-token`; the server also checks exact allowed Host/port and Origin. These controls act
 as the trusted local user, not a Role selected by the request body. They support
 Task metadata edits, messages, InputRequest answers, and explicit
 `queue / steer / interrupt` for Task or Global Roles. Managed Agent capability

package/docs/architecture/capabilities-and-resources.zh-CN.md

@@ -88,12 +88,13 @@ Surface contribution 由 Registry 当前获授权目录派生，没有第二份
 CLI contribution 使用能力原名称。Web panel 只接受受控 text、HTTP(S) link 或
 JSON query 描述，不接受作者脚本或任意 HTML。
 
-Web listener 由 Controller 启停，仅允许 loopback（`127.0.0.1`、`::1` 或
-`localhost`；默认端口 4173）。`yui web` 打开的是本地 Surface，不是远程多用户
-服务或 OS 沙箱。
+唯一 Web listener 由 Controller 启停，默认 `127.0.0.1:4173`。显式可信内网
+监听要求私有凭证文件，在页面、API、预览和 Terminal 之前认证。
+当前 Operator 的生命周期权限与浏览器访问分开复核。
+详见[受控 Web 访问](../web-access.md)；它仍是单用户 Surface，不是多用户服务或 OS 沙箱。
 
 页面提供 token，通过 `x-yui-web-token` 认证所有 HTTP API 读取与写入；服务端
-也检查 loopback Host。这些控制使用受信任本地用户身份，不由请求正文选择 Role。
+也检查精确允许的 Host/端口和 Origin。这些控制使用受信任本地用户身份，不由请求正文选择 Role。
 它们支持修改 Task 元数据、发送消息、回答 InputRequest，以及对 Task 或 Global
 Role 显式 `queue / steer / interrupt`。受管 Agent 的能力 RPC 仍使用自身 Session
 认证与范围；浏览器 token 不是 Agent 或插件绕过这些边界的途径。