@rynx-ai/server 0.1.9 → 0.1.10-beta.2

package/dist/machine-session-service.js

@@ -46,6 +46,9 @@ export class MachineSessionService {
     maxSnapshotItemLimit;
     snapshotPageMaxBytes;
     directoryScanLimit;
+    pendingMessageRetryMs;
+    pendingDeliveries = new Map();
+    cancelledPendingDeliveries = new Set();
     constructor(ports, options = {}) {
         this.ports = ports;
         this.maxListLimit = boundedInteger(options.maxListLimit ?? MAX_LIST_LIMIT, 1, MAX_LIST_LIMIT, "maxListLimit");
@@ -53,6 +56,8 @@ export class MachineSessionService {
         this.maxSnapshotItemLimit = boundedInteger(options.maxSnapshotItemLimit ?? MAX_SNAPSHOT_ITEM_LIMIT, 1, MAX_SNAPSHOT_ITEM_LIMIT, "maxSnapshotItemLimit");
         this.snapshotPageMaxBytes = boundedInteger(options.snapshotPageMaxBytes ?? DEFAULT_SNAPSHOT_PAGE_MAX_BYTES, MIN_PAGE_MAX_BYTES, MAX_PAGE_MAX_BYTES, "snapshotPageMaxBytes");
         this.directoryScanLimit = boundedInteger(options.directoryScanLimit ?? DEFAULT_DIRECTORY_SCAN_LIMIT, 1, MAX_DIRECTORY_SCAN_LIMIT, "directoryScanLimit");
+        this.pendingMessageRetryMs = boundedInteger(options.pendingMessageRetryMs ?? 1_000, 10, 60_000, "pendingMessageRetryMs");
+        void this.resumePendingDeliveries();
     }
     async list(input = {}) {
         const limit = requestLimit(input.limit, DEFAULT_LIST_LIMIT, this.maxListLimit, "limit");
@@ -63,14 +68,18 @@ export class MachineSessionService {
         const metas = [...allMetas]
             .sort(compareMetaRecency)
             .slice(0, this.directoryScanLimit);
-        const logged = await this.ports.log.listSessions({ limit: this.directoryScanLimit + 1 });
+        const [logged, pendingMessages] = await Promise.all([
+            this.ports.log.listSessions({ limit: this.directoryScanLimit + 1 }),
+            this.ports.pendingMessages?.list() ?? [],
+        ]);
         const directoryTruncated = allMetas.length > this.directoryScanLimit || logged.length > this.directoryScanLimit;
         const boundedLogs = logged.slice(0, this.directoryScanLimit);
         const metaById = new Map(metas.map((meta) => [meta.id, meta]));
         const logById = new Map(boundedLogs.map((entry) => [entry.sessionId, entry]));
+        const pendingById = new Map(pendingMessages.map((entry) => [entry.sessionId, entry.state]));
         const ids = new Set([...metaById.keys(), ...logById.keys()]);
         const summaries = [...ids]
-            .map((id) => sessionSummary(id, metaById.get(id), logById.get(id), this.ports.runtimeState))
+            .map((id) => sessionSummary(id, metaById.get(id), logById.get(id), this.ports.runtimeState, pendingById.get(id)))
             .sort(compareSummaryRecency);
         const afterCursor = cursor === undefined
             ? summaries
@@ -186,11 +195,7 @@ export class MachineSessionService {
         }
         else {
             if (!isSessionProviderId(input.provider)) {
-                throw new MachineSessionServiceInputError("provider must be codex or claude");
-            }
-            const readiness = await this.runtimeReadiness(input.provider);
-            if (!readiness.ready) {
-                throw new MachineSessionServiceFailure("failed_precondition", readiness.reason ?? "provider is not ready");
+                throw new MachineSessionServiceInputError("provider must be codex, traex, or claude");
             }
             target = { provider: input.provider };
         }
@@ -209,31 +214,188 @@ export class MachineSessionService {
     /** Inject one turn through the target daemon's native single-writer runner. */
     async sendMessage(sessionIdInput, messageInput) {
         const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
-        if (typeof messageInput !== "string" || messageInput.length === 0) {
+        const request = typeof messageInput === "string"
+            ? { message: messageInput }
+            : messageInput;
+        const hasMessage = request.message !== undefined;
+        const hasContent = request.content !== undefined;
+        if (hasMessage === hasContent) {
+            throw new MachineSessionServiceInputError("provide exactly one of message or content");
+        }
+        if (hasMessage && (typeof request.message !== "string" || request.message.length === 0)) {
             throw new MachineSessionServiceInputError("message must be a non-empty string");
         }
+        if (hasContent && (!Array.isArray(request.content) || request.content.length === 0)) {
+            throw new MachineSessionServiceInputError("content must be a non-empty array");
+        }
         const meta = this.ports.registry.get(sessionId);
         const consoleMeta = meta?.source === "console" ? meta : undefined;
+        let prepared;
+        const needsPreparedOperation = hasContent || request.clientMessageId !== undefined;
+        if (needsPreparedOperation) {
+            const resources = this.ports.resources;
+            if (!resources) {
+                throw new MachineSessionServiceFailure("failed_precondition", "Session resources are unavailable");
+            }
+            if (hasContent &&
+                request.content.some((part) => part.type === "input_image") &&
+                !request.clientMessageId) {
+                throw new MachineSessionServiceInputError("clientMessageId is required for image input");
+            }
+            prepared = await resources.prepareInput(sessionId, hasContent
+                ? request.content
+                : [{ type: "input_text", text: request.message }], request.clientMessageId);
+            if (prepared.operationState === "injecting" ||
+                prepared.operationState === "outcome_unknown") {
+                throw new MachineSessionServiceFailure("outcome_unknown", "message delivery outcome is unknown");
+            }
+            if (prepared.operationState === "injected" ||
+                prepared.operationState === "mirrored") {
+                return { ok: true, injected: true };
+            }
+        }
+        else {
+            prepared = {
+                input: {
+                    content: [{ type: "text", text: request.message }],
+                    ...(request.clientMessageId
+                        ? { clientMessageId: request.clientMessageId }
+                        : {}),
+                },
+                title: request.message,
+            };
+        }
         if (consoleMeta && !consoleMeta.title) {
-            this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(messageInput));
+            this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(prepared.title));
+        }
+        const resources = this.ports.resources;
+        if (request.clientMessageId) {
+            await resources?.markMessageInjecting(sessionId, request.clientMessageId);
+        }
+        let execution;
+        try {
+            execution = await this.ensureLiveSession(sessionId, meta);
+        }
+        catch (error) {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, error instanceof Error ? error.message : String(error));
+            }
+            throw error;
+        }
+        let outcome;
+        try {
+            outcome = await execution.runner.injectMessage(sessionId, hasMessage && !needsPreparedOperation ? request.message : prepared.input);
+        }
+        catch (error) {
+            if (request.clientMessageId) {
+                await Promise.resolve(resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, error instanceof Error ? error.message : String(error))).catch(() => undefined);
+            }
+            throw new MachineSessionServiceFailure("outcome_unknown", "live injection outcome is unknown");
         }
-        const execution = await this.ensureLiveSession(sessionId, meta);
-        const outcome = await execution.runner.injectMessage(sessionId, messageInput);
         if (outcome === "failed") {
+            if (request.clientMessageId) {
+                await resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, `live injection ${outcome}`);
+            }
             throw new MachineSessionServiceFailure("outcome_unknown", `live injection ${outcome}`);
         }
         if (outcome !== "injected") {
+            if (request.clientMessageId) {
+                await resources?.markMessageFailedNotStarted(sessionId, request.clientMessageId, `live injection ${outcome}`);
+            }
             throw new MachineSessionServiceFailure("failed_precondition", `live injection ${outcome}`);
         }
+        if (request.clientMessageId) {
+            try {
+                await resources?.markMessageInjected(sessionId, request.clientMessageId);
+            }
+            catch {
+                await Promise.resolve(resources?.markMessageOutcomeUnknown(sessionId, request.clientMessageId, "message state could not be persisted after injection")).catch(() => undefined);
+                throw new MachineSessionServiceFailure("outcome_unknown", "message was injected but its delivery state could not be persisted");
+            }
+        }
         return { ok: true, injected: true };
     }
+    resourcePolicy(sessionIdInput) {
+        const sessionId = this.requireResourceSession(sessionIdInput);
+        return this.requireResources().policy(sessionId);
+    }
+    async beginResourceUpload(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().beginUpload({ ...input, sessionId });
+    }
+    async writeResourceUploadChunk(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().writeUploadChunk({ ...input, sessionId });
+    }
+    async commitResourceUpload(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().commitUpload({ ...input, sessionId });
+    }
+    async getResource(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().getResource({ ...input, sessionId });
+    }
+    async readResource(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().readResource({ ...input, sessionId });
+    }
+    async deleteResource(input) {
+        const sessionId = this.requireResourceSession(input.sessionId);
+        return this.requireResources().deleteResource({ ...input, sessionId });
+    }
+    /** Persist the first task while login/onboarding owns the Provider TUI. The
+     * delivery worker starts the pane now, waits for a real native thread, then
+     * injects exactly once. `failed` is fenced as outcome_unknown and never retried. */
+    async enqueueMessage(sessionIdInput, messageInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        if (typeof messageInput !== "string" || messageInput.length === 0) {
+            throw new MachineSessionServiceInputError("message must be a non-empty string");
+        }
+        const meta = this.ports.registry.get(sessionId);
+        if (!meta)
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        const pending = this.ports.pendingMessages;
+        if (!pending) {
+            throw new MachineSessionServiceFailure("failed_precondition", "Provider setup task queue is unavailable");
+        }
+        const inserted = await pending.put({
+            sessionId,
+            message: messageInput,
+            createdAt: new Date().toISOString(),
+        });
+        if (!inserted) {
+            throw new MachineSessionServiceFailure("failed_precondition", "This Session already has a task waiting for Provider setup");
+        }
+        if (meta.source === "console" && !meta.title) {
+            this.ports.registry.setTitle(sessionId, synthesizeSessionTitle(messageInput));
+        }
+        this.schedulePendingDelivery(sessionId);
+        // Best effort: delivery also starts/retries the pane, but awaiting this path
+        // makes the setup Terminal attachable as soon as the enqueue RPC returns.
+        await this.startTerminal(sessionId).catch(() => undefined);
+        return { ok: true, queued: true };
+    }
     /** Explicitly restore the target daemon's live runner without starting a turn. */
     async startTerminal(sessionIdInput) {
         const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
-        await this.ensureLiveSession(sessionId);
+        const request = await this.liveSessionRequest(sessionId);
+        const start = request.execution.runner.startLiveSession?.bind(request.execution.runner) ??
+            request.execution.runner.ensureLiveSession.bind(request.execution.runner);
+        const started = await start(sessionId, request.options);
+        if (!started) {
+            throw new MachineSessionServiceFailure("failed_precondition", `Provider terminal unavailable (${request.liveRuntime})`, request.execution.runner.lastLiveSessionError?.(sessionId));
+        }
         return { ok: true };
     }
     async ensureLiveSession(sessionId, meta = this.ports.registry.get(sessionId)) {
+        const request = await this.liveSessionRequest(sessionId, meta);
+        const live = await request.execution.runner.ensureLiveSession(sessionId, request.options);
+        if (!live) {
+            throw new MachineSessionServiceFailure("failed_precondition", `live session unavailable (${request.liveRuntime})`, request.execution.runner.lastLiveSessionError?.(sessionId));
+        }
+        return request.execution;
+    }
+    async liveSessionRequest(sessionId, meta = this.ports.registry.get(sessionId)) {
         const execution = this.requireExecution();
         const consoleMeta = meta?.source === "console" ? meta : undefined;
         const bound = consoleMeta ? null : ((await execution.sessionStore?.get(sessionId)) ?? null);
@@ -245,18 +407,19 @@ export class MachineSessionService {
             agentSpec: consoleMeta?.config,
             provider: meta?.provider ?? bound?.runtime,
         });
-        if (liveRuntime === "codex") {
+        if (liveRuntime === "codex" || liveRuntime === "traex") {
             const codexRecord = await execution.sessionStore?.get(sessionId);
             if (codexRecord?.codexSessionId) {
                 ensureCodexResumeRollout({
                     sessionId,
+                    runtime: liveRuntime,
                     threadId: codexRecord.codexSessionId,
                     cwd: codexRecord.cwd ?? process.cwd(),
                     items: await this.ports.log.snapshot(sessionId),
                 });
             }
         }
-        const live = await execution.runner.ensureLiveSession(sessionId, {
+        const options = {
             ...(bound?.cwd
                 ? { cwd: bound.cwd }
                 : consoleMeta?.config?.osEnv?.cwd
@@ -268,11 +431,8 @@ export class MachineSessionService {
                 : {}),
             ...(consoleMeta?.agent ? { agentName: consoleMeta.agent } : {}),
             ...(consoleMeta?.config ? { agentSpec: consoleMeta.config } : {}),
-        });
-        if (!live) {
-            throw new MachineSessionServiceFailure("failed_precondition", `live session unavailable (${liveRuntime})`, execution.runner.lastLiveSessionError?.(sessionId));
-        }
-        return execution;
+        };
+        return { execution, liveRuntime, options };
     }
     async resolveInteraction(sessionIdInput, interactionIdInput, resolution) {
         const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
@@ -287,8 +447,11 @@ export class MachineSessionService {
         catch (error) {
             throw new MachineSessionServiceFailure("failed_precondition", "Session-owned resources could not be fenced before deletion", error instanceof Error ? error.message : String(error));
         }
+        this.cancelledPendingDeliveries.add(sessionId);
         this.ports.execution?.runner.stopRunner(sessionId);
         this.ports.events.close?.(sessionId);
+        await this.ports.pendingMessages?.delete(sessionId);
+        await this.ports.resources?.deleteSession(sessionId);
         this.ports.registry.remove(sessionId);
         await this.ports.log.deleteSession(sessionId);
         this.ports.runtimeState.remove?.(sessionId);
@@ -306,6 +469,93 @@ export class MachineSessionService {
         }
         return this.ports.agents;
     }
+    requireResources() {
+        if (!this.ports.resources) {
+            throw new MachineSessionServiceFailure("failed_precondition", "Session resources are unavailable");
+        }
+        return this.ports.resources;
+    }
+    requireResourceSession(sessionIdInput) {
+        const sessionId = validOpaqueToken(sessionIdInput, "sessionId", MAX_SESSION_ID_CHARS);
+        if (!this.ports.registry.get(sessionId)) {
+            throw new MachineSessionServiceFailure("not_found", "session not found");
+        }
+        return sessionId;
+    }
+    async resumePendingDeliveries() {
+        const pending = this.ports.pendingMessages;
+        if (!pending)
+            return;
+        try {
+            for (const message of await pending.list()) {
+                if (message.state === "queued")
+                    this.schedulePendingDelivery(message.sessionId);
+            }
+        }
+        catch {
+            // A later enqueue or daemon restart retries recovery; startup remains usable.
+        }
+    }
+    schedulePendingDelivery(sessionId) {
+        if (this.pendingDeliveries.has(sessionId))
+            return;
+        this.cancelledPendingDeliveries.delete(sessionId);
+        const delivery = this.deliverPendingMessage(sessionId)
+            .catch(() => undefined)
+            .finally(() => {
+            if (this.pendingDeliveries.get(sessionId) === delivery) {
+                this.pendingDeliveries.delete(sessionId);
+            }
+        });
+        this.pendingDeliveries.set(sessionId, delivery);
+    }
+    async deliverPendingMessage(sessionId) {
+        const pendingStore = this.ports.pendingMessages;
+        if (!pendingStore)
+            return;
+        for (;;) {
+            if (this.cancelledPendingDeliveries.has(sessionId))
+                return;
+            const pending = await pendingStore.get(sessionId);
+            if (!pending || pending.state !== "queued")
+                return;
+            let injectionAttempted = false;
+            try {
+                const execution = await this.ensureLiveSession(sessionId);
+                if (this.cancelledPendingDeliveries.has(sessionId))
+                    return;
+                const current = await pendingStore.get(sessionId);
+                if (!current ||
+                    current.state !== "queued" ||
+                    current.createdAt !== pending.createdAt ||
+                    current.message !== pending.message)
+                    return;
+                injectionAttempted = true;
+                const outcome = await execution.runner.injectMessage(sessionId, pending.message);
+                if (outcome === "injected") {
+                    await Promise.resolve(pendingStore.delete(sessionId)).catch(async () => {
+                        await Promise.resolve(pendingStore.markOutcomeUnknown(sessionId)).catch(() => undefined);
+                    });
+                    return;
+                }
+                if (outcome === "failed") {
+                    await pendingStore.markOutcomeUnknown(sessionId);
+                    return;
+                }
+            }
+            catch (error) {
+                if (injectionAttempted) {
+                    await Promise.resolve(pendingStore.markOutcomeUnknown(sessionId)).catch(() => undefined);
+                    return;
+                }
+                if (error instanceof MachineSessionServiceFailure && error.code === "not_found") {
+                    await pendingStore.delete(sessionId);
+                    return;
+                }
+            }
+            await retryDelay(this.pendingMessageRetryMs);
+        }
+    }
     runtimeReadiness(runtime, cache) {
         const cached = cache?.get(runtime);
         if (cached)
@@ -368,6 +618,12 @@ function runtimeSetupReason(runtime, status) {
     return status.issues.find((issue) => issue.trim().length > 0) ??
         `${name} needs setup before it can start Sessions.`;
 }
+function retryDelay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
 function listPage(sessions, hasMore, directoryTruncated) {
     return {
         sessions,
@@ -432,7 +688,7 @@ function snapshotPage(sessionId, items, runtime, hasMore) {
         ...(hasMore && items.length > 0 ? { nextAfterId: items.at(-1).id } : {}),
     };
 }
-function sessionSummary(id, meta, log, runtimeState) {
+function sessionSummary(id, meta, log, runtimeState, pendingState) {
     const createdAt = meta?.createdAt ?? timestampFromEpoch(log?.createdAt, "createdAt");
     const updatedAt = log
         ? timestampFromEpoch(log.updatedAt, "updatedAt")
@@ -443,6 +699,13 @@ function sessionSummary(id, meta, log, runtimeState) {
         ...(meta?.agent === undefined ? {} : { agent: meta.agent }),
         ...(meta?.title === undefined ? {} : { title: normalizeSessionTitle(meta.title) }),
         status: runtimeState.snapshot(id).status,
+        ...(pendingState === undefined
+            ? {}
+            : {
+                setupStatus: pendingState === "queued"
+                    ? "waiting_for_provider"
+                    : "delivery_unknown",
+            }),
         createdAt: validTimestamp(createdAt, "createdAt"),
         source: meta?.source ?? "unknown",
         updatedAt: validTimestamp(updatedAt, "updatedAt"),

package/dist/remote-runtime-dispatcher.d.ts

@@ -25,7 +25,7 @@ export interface RemoteRuntimeDispatcherOptions {
     /** Optional diagnostic sink. Wire errors deliberately omit internal details. */
     onError?: (error: unknown, request: RemoteRuntimeRpcRequest) => void;
 }
-export type RemoteRuntimeSessionHost = Pick<MachineSessionService, "list" | "snapshot" | "watch" | "interrupt" | "agentOptions" | "launchOptions" | "create" | "sendMessage" | "startTerminal" | "delete" | "resolveInteraction">;
+export type RemoteRuntimeSessionHost = Pick<MachineSessionService, "list" | "snapshot" | "watch" | "interrupt" | "agentOptions" | "launchOptions" | "create" | "sendMessage" | "resourcePolicy" | "beginResourceUpload" | "writeResourceUploadChunk" | "commitResourceUpload" | "getResource" | "readResource" | "deleteResource" | "enqueueMessage" | "startTerminal" | "delete" | "resolveInteraction">;
 export type RemoteRuntimeBrowserHost = Pick<SessionBrowserService, "getState" | "open" | "close" | "createPage" | "closePage" | "activatePage" | "navigatePage" | "goBack" | "goForward" | "reload">;
 export type RemoteRuntimeSessionEmulatorHost = Pick<SessionEmulatorService, "getState" | "listDevices" | "attach" | "detach" | "tap" | "type" | "button" | "rotate" | "launch" | "gesture" | "releaseDevice" | "stopDevice">;
 export interface OpenRemoteRuntimeSessionEvents {

package/dist/remote-runtime-dispatcher.js

@@ -103,7 +103,28 @@ export class RemoteRuntimeDispatcher {
                 case "session.create":
                     return await this.withSessions(request, (sessions) => sessions.create(request.params));
                 case "session.message.send":
-                    return await this.withSessions(request, (sessions) => sessions.sendMessage(request.params.sessionId, request.params.message));
+                    return await this.withSessions(request, (sessions) => {
+                        const { sessionId, ...input } = request.params;
+                        return sessions.sendMessage(sessionId, input.content === undefined && input.clientMessageId === undefined
+                            ? input.message
+                            : input);
+                    });
+                case "session.resource.policy.get":
+                    return await this.withSessions(request, async (sessions) => sessions.resourcePolicy(request.params.sessionId));
+                case "session.resource.upload.begin":
+                    return await this.withSessions(request, (sessions) => sessions.beginResourceUpload(request.params));
+                case "session.resource.upload.chunk":
+                    return await this.withSessions(request, (sessions) => sessions.writeResourceUploadChunk(request.params));
+                case "session.resource.upload.commit":
+                    return await this.withSessions(request, (sessions) => sessions.commitResourceUpload(request.params));
+                case "session.resource.get":
+                    return await this.withSessions(request, (sessions) => sessions.getResource(request.params));
+                case "session.resource.read":
+                    return await this.withSessions(request, (sessions) => sessions.readResource(request.params));
+                case "session.resource.delete":
+                    return await this.withSessions(request, (sessions) => sessions.deleteResource(request.params));
+                case "session.message.enqueue":
+                    return await this.withSessions(request, (sessions) => sessions.enqueueMessage(request.params.sessionId, request.params.message));
                 case "session.terminal.start":
                     return await this.withSessions(request, (sessions) => sessions.startTerminal(request.params.sessionId));
                 case "session.delete":
@@ -274,7 +295,9 @@ function mapHostError(request, error) {
             ? "Remote Session resource was not found"
             : error.code === "failed_precondition"
                 ? "Remote Session operation is unavailable"
-                : "Remote Session operation may have been applied";
+                : error.code === "conflict"
+                    ? "Remote Session resource conflicts with existing state"
+                    : "Remote Session operation may have been applied";
         return { code: error.code, message };
     }
     if (request.method === "session.interrupt") {

package/dist/remote-runtime-session-projection.js

@@ -94,6 +94,16 @@ function projectRuntimeSnapshot(value) {
 /** Project one canonical durable item, preserving every identity and array entry. */
 export function projectRemoteRuntimeSessionItem(item) {
     const projected = structuredClone(item);
+    // Older Traex sessions used an empty model string to mean "use the CLI
+    // default". Model is optional in the canonical item, but Direct Runtime's
+    // bounded wire string is deliberately non-empty; preserve the meaning by
+    // projecting that legacy sentinel as an absent optional field.
+    if ((projected.type === "message" ||
+        projected.type === "function_call" ||
+        projected.type === "reasoning") &&
+        projected.data.model === "") {
+        delete projected.data.model;
+    }
     boundHistoricalInteractionRouting(projected);
     const refs = collectItemPayloadRefs(projected);
     boundPayloads(refs);

package/dist/runtime-web-auth.d.ts

@@ -10,6 +10,10 @@ export interface RuntimeWebAuthorizationFailure {
     status: 401 | 403;
     error: "loopback_only" | "invalid_host" | "cross_origin" | "invalid_runtime_capability";
 }
+export interface RuntimeWebAccessPolicy {
+    mode: "loopback" | "host";
+}
+export declare function runtimeWebAccessPolicyForBindHost(bindHost: string): RuntimeWebAccessPolicy;
 /**
  * Authorize a browser request before any Runtime lease or terminal is opened.
  * Socket address and the original Host header are both checked to resist DNS
@@ -18,4 +22,5 @@ export interface RuntimeWebAuthorizationFailure {
 export declare function authorizeRuntimeWebRequest(request: IncomingMessage, options?: {
     mutation?: boolean;
     capability?: string;
+    access?: RuntimeWebAccessPolicy;
 }): RuntimeWebAuthorizationFailure | undefined;

package/dist/runtime-web-auth.js

@@ -1,4 +1,5 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
+import { isIP } from "node:net";
 export const RUNTIME_WEB_CAPABILITY_HEADER = "x-rynx-runtime-capability";
 export const RUNTIME_WEB_CAPABILITY_QUERY = "capability";
 /**
@@ -6,17 +7,26 @@ export const RUNTIME_WEB_CAPABILITY_QUERY = "capability";
  * browser WebSocket upgrades. It is not a daemon-management credential.
  */
 export const RUNTIME_WEB_CAPABILITY = randomBytes(32).toString("base64url");
+export function runtimeWebAccessPolicyForBindHost(bindHost) {
+    const normalized = normalizeAddress(bindHost.trim().replace(/^\[|\]$/g, ""))?.toLowerCase();
+    return {
+        mode: normalized === "127.0.0.1" || normalized === "::1" || normalized === "localhost"
+            ? "loopback"
+            : "host",
+    };
+}
 /**
  * Authorize a browser request before any Runtime lease or terminal is opened.
  * Socket address and the original Host header are both checked to resist DNS
  * rebinding; mutation metadata and the capability provide the CSRF fence.
  */
 export function authorizeRuntimeWebRequest(request, options = {}) {
-    if (!isLoopbackAddress(request.socket.remoteAddress)) {
+    const access = options.access ?? { mode: "loopback" };
+    if (access.mode === "loopback" && !isLoopbackAddress(request.socket.remoteAddress)) {
         return { status: 403, error: "loopback_only" };
     }
     const host = originalHostHeader(request);
-    if (!host || !isLoopbackHostAuthority(host)) {
+    if (!host || !isAllowedHostAuthority(request, host, access)) {
         return { status: 403, error: "invalid_host" };
     }
     if (!options.mutation)
@@ -30,9 +40,12 @@ export function authorizeRuntimeWebRequest(request, options = {}) {
     return undefined;
 }
 function isLoopbackAddress(value) {
-    const normalized = value?.startsWith("::ffff:") ? value.slice("::ffff:".length) : value;
+    const normalized = normalizeAddress(value);
     return normalized === "127.0.0.1" || normalized === "::1";
 }
+function normalizeAddress(value) {
+    return value?.startsWith("::ffff:") ? value.slice("::ffff:".length) : value;
+}
 /** Read the HTTP/1 Host header exactly as received; duplicate Hosts fail closed. */
 function originalHostHeader(request) {
     let host;
@@ -46,6 +59,17 @@ function originalHostHeader(request) {
     }
     return host;
 }
+function isAllowedHostAuthority(request, host, access) {
+    if (isLoopbackHostAuthority(host)) {
+        return isLoopbackAddress(request.socket.remoteAddress);
+    }
+    if (access.mode !== "host")
+        return false;
+    const hostAddress = ipHostAuthorityAddress(host);
+    const localAddress = normalizeAddress(request.socket.localAddress);
+    return hostAddress !== undefined && localAddress !== undefined &&
+        hostAddress.toLowerCase() === localAddress.toLowerCase();
+}
 function isLoopbackHostAuthority(value) {
     if (value.length === 0 || value !== value.trim())
         return false;
@@ -57,6 +81,22 @@ function isLoopbackHostAuthority(value) {
     const port = Number(match[1]);
     return Number.isInteger(port) && port >= 1 && port <= 65_535;
 }
+function ipHostAuthorityAddress(value) {
+    if (value.length === 0 || value !== value.trim())
+        return undefined;
+    const match = /^(?:([0-9.]+)|\[([0-9a-f:.]+)\])(?::(\d{1,5}))?$/i.exec(value);
+    if (!match)
+        return undefined;
+    const address = match[1] ?? match[2];
+    if (isIP(address) === 0)
+        return undefined;
+    if (match[3] !== undefined) {
+        const port = Number(match[3]);
+        if (!Number.isInteger(port) || port < 1 || port > 65_535)
+            return undefined;
+    }
+    return address;
+}
 function isSameOriginBrowserMutation(request, host) {
     const fetchSite = singleHeader(request.headers["sec-fetch-site"]).trim().toLowerCase();
     if (fetchSite && fetchSite !== "same-origin")