ftown 0.19.56 → 0.19.58

package/dist/update-effects.d.ts

@@ -0,0 +1,20 @@
+import type { SecureExecutionObserver } from './security/bridge/execution-observer.js';
+import type { ApplicationJson, VerifiedApplication } from './security/protocol.js';
+import { UpdateAdmission, UpdateResponseTicket } from './update-admission.js';
+import type { ServerResponse } from 'node:http';
+/** Tracks only authenticated in-process requests. Transport completion releases their admission fence. */
+export declare class UpdateEffects implements SecureExecutionObserver {
+    private readonly admission;
+    private readonly entries;
+    constructor(admission: UpdateAdmission);
+    admitted(message: VerifiedApplication): void;
+    attachTicket(message: VerifiedApplication, ticket: UpdateResponseTicket): void;
+    sealed(message: VerifiedApplication, data: ApplicationJson): void;
+    delivered(requestId: string): void;
+    failed(requestId: string): void;
+    private finish;
+}
+/** Per-envelope guard prevents unauthenticated collisions from completing another request. */
+export declare function scopedUpdateObserver(observer?: SecureExecutionObserver): SecureExecutionObserver | undefined;
+/** Bind transport signals before writing, but never release a running dispatch on close. */
+export declare function observeHttpDelivery(response: ServerResponse, observer: SecureExecutionObserver | undefined, requestId: string): (executionSucceeded: boolean) => void;

package/dist/update-effects.js

@@ -0,0 +1,117 @@
+import { classifyCommand, classifyHttp, classifyTerminal } from './security/bridge/permissions.js';
+const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Tracks only authenticated in-process requests. Transport completion releases their admission fence. */
+export class UpdateEffects {
+    admission;
+    entries = new Map();
+    constructor(admission) {
+        this.admission = admission;
+    }
+    admitted(message) {
+        const route = message.application.route;
+        const body = message.application.data;
+        const permission = route.kind === 'command' ? (route.command === 'security_activate_mcp' ? { mutating: true } : classifyCommand(route.command, record(body) ? body.payload : undefined))
+            : route.kind === 'http' ? classifyHttp(route.method, route.path)
+                : route.kind === 'terminal' ? classifyTerminal(route.frameType) : null;
+        const key = message.envelope.messageId;
+        if (!key || this.entries.has(key))
+            throw new Error('Duplicate secure request');
+        const release = permission?.mutating ? this.admission.enter() : () => { };
+        this.entries.set(key, { message, release, sealed: false });
+    }
+    attachTicket(message, ticket) {
+        const entry = this.entries.get(message.envelope.messageId);
+        if (!entry || entry.message !== message || entry.ticket || message.application.route.kind !== 'command' || message.application.route.command !== 'update_bridge') {
+            ticket.cancel();
+            throw new Error('Update response ticket is not bound to an admitted request');
+        }
+        entry.ticket = ticket;
+        entry.timer = setTimeout(() => {
+            if (entry.ticket !== ticket)
+                return;
+            ticket.cancel();
+            entry.ticket = undefined;
+            if (entry.sealed)
+                this.finish(message.envelope.messageId, false);
+        }, 30_000);
+        entry.timer.unref();
+    }
+    sealed(message, data) {
+        const entry = this.entries.get(message.envelope.messageId);
+        if (!entry || entry.message !== message)
+            throw new Error('Secure request is not admitted');
+        entry.sealed = true;
+        if (!entry.ticket)
+            return;
+        const route = message.application.route;
+        const input = message.application.data;
+        const response = record(data) && data.type === 'command_response' && record(data.response) ? data.response : null;
+        const accepted = response && record(response.data) ? response.data : null;
+        const op = accepted && record(accepted.operation) ? accepted.operation : null;
+        const payload = record(input) && record(input.payload) ? input.payload : null;
+        if (route.kind !== 'command' || route.command !== 'update_bridge' || !record(input) || input.requestId !== route.requestId
+            || !response || response.requestId !== route.requestId || response.success !== true
+            || !payload || !accepted || accepted.bridgeId !== payload.bridgeId || !op || op.id !== payload.operationId || op.targetVersion !== payload.targetVersion) {
+            this.finish(message.envelope.messageId, false);
+            return;
+        }
+        entry.ticket.markSealed();
+    }
+    delivered(requestId) { this.finish(requestId, true); }
+    failed(requestId) { this.finish(requestId, false); }
+    finish(key, delivered) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return;
+        this.entries.delete(key);
+        if (entry.timer)
+            clearTimeout(entry.timer);
+        entry.release();
+        if (delivered && entry.sealed)
+            entry.ticket?.markDelivered();
+        else
+            entry.ticket?.cancel();
+    }
+}
+/** Per-envelope guard prevents unauthenticated collisions from completing another request. */
+export function scopedUpdateObserver(observer) {
+    if (!observer)
+        return undefined;
+    let key;
+    return {
+        admitted(message) { observer.admitted(message); key = message.envelope.messageId; },
+        sealed(message, data) { if (key !== message.envelope.messageId)
+            throw new Error('Secure request identity changed'); observer.sealed(message, data); },
+        delivered(id) { if (key === id) {
+            key = undefined;
+            observer.delivered(id);
+        } },
+        failed(id) { if (key === id) {
+            key = undefined;
+            observer.failed(id);
+        } },
+    };
+}
+/** Bind transport signals before writing, but never release a running dispatch on close. */
+export function observeHttpDelivery(response, observer, requestId) {
+    let executionDone = false;
+    let closed = response.destroyed;
+    let finished = false;
+    let done = false;
+    const finalize = () => {
+        if (done || !executionDone || (!finished && !closed))
+            return;
+        done = true;
+        if (finished && !closed)
+            observer?.delivered(requestId);
+        else
+            observer?.failed(requestId);
+    };
+    response.once('finish', () => { finished = true; finalize(); });
+    response.once('close', () => { if (!finished)
+        closed = true; finalize(); });
+    response.once('error', () => { closed = true; finalize(); });
+    return succeeded => { executionDone = true; if (!succeeded)
+        closed = true; finalize(); };
+}
+//# sourceMappingURL=update-effects.js.map

package/dist/update-effects.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-effects.js","sourceRoot":"","sources":["../src/update-effects.ts"],"names":[],"mappings":"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"}

package/dist/update-handoff.d.ts

@@ -0,0 +1,38 @@
+import { type ChildProcess } from 'node:child_process';
+import type { PreparedHandoff, PreparedRelease, RestartDescriptor, UpdateReceipt, UpdateReservation, UpdateRestartContext } from './update-runtime-contract.js';
+export declare class UpdateHandoffUncertainError extends Error {
+    readonly code: "handoff_uncertain";
+    constructor();
+}
+export declare function reserveUpdate(home: string, operationId: string): Promise<UpdateReservation>;
+export declare function assertUpdateReservationAllowed(home: string): void;
+export declare function readUpdateRestartContext(): UpdateRestartContext | null;
+export declare function reportUpdateReady(identity: {
+    version: string;
+    bridgeId: string;
+    ownerId: string;
+    endpointId: string;
+}): Promise<void>;
+export declare function readUpdateReceipt(stagingRoot: string): Promise<UpdateReceipt | null>;
+export declare function writeUpdateReceipt(stagingRoot: string, receipt: UpdateReceipt): Promise<void>;
+/** Forward only ordinary runtime settings and the explicit trusted-LAN opt-in. */
+export declare function selectUpdateLaunchEnvironment(source: Record<string, unknown>): Record<string, string>;
+/** The ACK is an irreversible attempt: the replacement might receive it even if sending fails. */
+export declare function finalizeUpdateReady(steps: {
+    persist: () => Promise<void>;
+    markAckAttempted: () => void;
+    acknowledge: () => Promise<void>;
+    release: () => Promise<void>;
+}): Promise<void>;
+/** After an ACK attempt, preserve the replacement and reservation on any uncertainty. */
+export declare function protectOrStopReplacement(ackAttempted: boolean, steps: {
+    stop: () => Promise<void>;
+    retain: () => Promise<void>;
+}): Promise<void>;
+export declare function prepareHandoff(prepared: PreparedRelease, restart: RestartDescriptor, signal: AbortSignal): Promise<PreparedHandoff>;
+export declare class UpdateProcessUncertainError extends Error {
+    readonly code: "update_process_uncertain";
+    constructor();
+}
+/** Bounded termination proof for helper-owned setup processes. */
+export declare function waitForUpdateChild(child: ChildProcess, stop: () => void, timeoutMs: number, proofMs: number): Promise<void>;