@tomflow/proflow-dev-tunnel 0.1.0

package/README.md

@@ -0,0 +1,27 @@
+# dev-tunnel
+
+Domain Owner: deployment-governance
+Module Kind: external-resource
+Service: none
+Process: none (except the managed `devtunnel host` external CLI child)
+Business Fact Owner: none
+
+## Owner
+
+Deployment Governance
+
+## Consumers
+
+- agent-gateway
+
+## Does NOT own
+
+- Agent Gateway
+- Gateway routing
+- Gateway auth
+- Task/Agent facts
+
+## Purpose
+
+Manages the Microsoft Dev Tunnel (`devtunnel`) public HTTPS ingress. Login is a
+user external-account fact and is never faked.

package/conformance.json

@@ -0,0 +1 @@
+{ "contract": "proflow.conformance.v1", "levels": ["C1", "C2", "C3"] }

package/dist/deployment/adapter.d.ts

@@ -0,0 +1,130 @@
+import type { ModuleOperationResult } from "@tomflow/proflow-module-contract";
+import type { DevTunnelRuntime, ErrorSemanticsProof, FileRelayProof } from "../src/resource-adapter.ts";
+export declare function createBehaviorAdapter(input?: {
+    runtime: DevTunnelRuntime;
+    verifyErrorSemantics?: () => Promise<ErrorSemanticsProof>;
+    verifyFileRelay?: () => Promise<FileRelayProof>;
+}): {
+    describe: () => {
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    };
+    preflight: () => {
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    };
+    status: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    }>;
+    verify: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "ACTION_REQUIRED" | "BLOCKED" | "FAILED" | "SUCCEEDED";
+            moduleRef: string;
+            moduleVersion: string;
+            actionRequired?: {
+                action: string;
+                description: string;
+            } | undefined;
+            error?: {
+                code: "APPLY_FAILED" | "COMMAND_FAILED" | "COMPATIBILITY_MISMATCH" | "CONFIG_REQUIRED" | "CONFORMANCE_FAILED" | "CONTRACT_INVALID" | "CORE_PACKAGE_REQUIRED" | "DEPENDENCY_UNRESOLVED" | "DOCTOR_FAILED" | "EXTERNAL_RESOURCE_UNAVAILABLE" | "INVALID_REQUEST" | "LIFECYCLE_UNSUPPORTED" | "MODULE_NOT_FOUND" | "PLAN_INVALID" | "PLAN_STALE" | "REQUIREMENT_UNMET" | "UNINSTALL_FAILED" | "UPGRADE_FAILED" | "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            } | undefined;
+            resourceVersion?: string | undefined;
+            data?: unknown;
+            checks: import("../src/resource-adapter.ts").IngressCheck[];
+        };
+        observedEffects: string[];
+    }>;
+    doctor: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    }>;
+    start: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+    stop: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+    uninstall: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+    restart: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+};
+export declare const behaviorAdapter: {
+    describe: () => {
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    };
+    preflight: () => {
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    };
+    status: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    }>;
+    verify: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    } | {
+        result: {
+            contract: "deployment.result.v1";
+            ok: boolean;
+            status: "ACTION_REQUIRED" | "BLOCKED" | "FAILED" | "SUCCEEDED";
+            moduleRef: string;
+            moduleVersion: string;
+            actionRequired?: {
+                action: string;
+                description: string;
+            } | undefined;
+            error?: {
+                code: "APPLY_FAILED" | "COMMAND_FAILED" | "COMPATIBILITY_MISMATCH" | "CONFIG_REQUIRED" | "CONFORMANCE_FAILED" | "CONTRACT_INVALID" | "CORE_PACKAGE_REQUIRED" | "DEPENDENCY_UNRESOLVED" | "DOCTOR_FAILED" | "EXTERNAL_RESOURCE_UNAVAILABLE" | "INVALID_REQUEST" | "LIFECYCLE_UNSUPPORTED" | "MODULE_NOT_FOUND" | "PLAN_INVALID" | "PLAN_STALE" | "REQUIREMENT_UNMET" | "UNINSTALL_FAILED" | "UPGRADE_FAILED" | "VERIFY_FAILED";
+                message: string;
+                retryable: boolean;
+            } | undefined;
+            resourceVersion?: string | undefined;
+            data?: unknown;
+            checks: import("../src/resource-adapter.ts").IngressCheck[];
+        };
+        observedEffects: string[];
+    }>;
+    doctor: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: never[];
+    }>;
+    start: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+    stop: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+    uninstall: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+    restart: () => Promise<{
+        result: ModuleOperationResult;
+        observedEffects: string[];
+    }>;
+};
+export declare function createProductionBinding(input: {
+    moduleRef: string;
+    config: Record<string, string>;
+}): Promise<{
+    behaviorAdapter: Record<string, unknown>;
+} | undefined>;

package/dist/deployment/adapter.js

@@ -0,0 +1,266 @@
+import { verifyPublicIngress } from "../src/resource-adapter.js";
+import { descriptor } from "./descriptor.js";
+const success = (data) => ({
+    contract: "deployment.result.v1",
+    ok: true,
+    status: "SUCCEEDED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+    ...(data === undefined ? {} : { data }),
+});
+const actionRequired = (action, description) => ({
+    contract: "deployment.result.v1",
+    ok: false,
+    status: "ACTION_REQUIRED",
+    moduleRef: descriptor.moduleRef,
+    moduleVersion: descriptor.moduleVersion,
+    actionRequired: { action, description },
+});
+export function createBehaviorAdapter(input) {
+    return {
+        describe: () => ({
+            result: success({
+                publicApi: ["status", "verify", "doctor", "start", "stop", "restart"],
+            }),
+            observedEffects: [],
+        }),
+        preflight: () => ({
+            result: input
+                ? success()
+                : actionRequired("configure-tunnel", "Bind a dev-tunnel resource with login status and a public HTTPS ingress"),
+            observedEffects: [],
+        }),
+        status: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "No dev-tunnel resource is bound"),
+                    observedEffects: [],
+                };
+            }
+            const observation = await input.runtime.status();
+            return {
+                result: {
+                    ...success(),
+                    checks: [
+                        {
+                            id: "tunnel-status",
+                            status: observation.state === "RUNNING"
+                                ? "PASS"
+                                : "WARN",
+                            message: `dev-tunnel state is ${observation.state}`,
+                        },
+                    ],
+                },
+                observedEffects: [],
+            };
+        },
+        verify: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "A live dev-tunnel resource is required for public ingress verification"),
+                    observedEffects: [],
+                };
+            }
+            if ((await input.runtime.loginStatus()) !== "LOGGED_IN") {
+                return {
+                    result: actionRequired("complete-tunnel-login", "Complete the interactive dev-tunnel login before verifying public ingress"),
+                    observedEffects: [],
+                };
+            }
+            const publicBaseUrl = input.runtime.publicBaseUrl();
+            if (publicBaseUrl === undefined) {
+                return {
+                    result: actionRequired("configure-tunnel", "publicBaseUrl must be configured before public ingress verification"),
+                    observedEffects: [],
+                };
+            }
+            const verification = await verifyPublicIngress(publicBaseUrl, {
+                ...(input.verifyErrorSemantics === undefined
+                    ? {}
+                    : { verifyErrorSemantics: input.verifyErrorSemantics }),
+                ...(input.verifyFileRelay === undefined
+                    ? {}
+                    : { verifyFileRelay: input.verifyFileRelay }),
+            });
+            return {
+                result: verification.ok
+                    ? { ...success(), checks: verification.checks }
+                    : {
+                        ...actionRequired("repair-tunnel-ingress", failureReason(verification)),
+                        checks: verification.checks,
+                    },
+                observedEffects: verification.reachable
+                    ? ["Probes the dev-tunnel public HTTPS ingress"]
+                    : [],
+            };
+        },
+        doctor: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "dev-tunnel login and public ingress configuration are required for diagnostics"),
+                    observedEffects: [],
+                };
+            }
+            const login = await input.runtime.loginStatus();
+            const status = await input.runtime.status();
+            const publicBaseUrl = input.runtime.publicBaseUrl();
+            const checks = [
+                {
+                    id: "tunnel-login",
+                    status: login === "LOGGED_IN" ? "PASS" : "FAIL",
+                    message: `login status is ${login}`,
+                },
+                {
+                    id: "tunnel-state",
+                    status: status.state === "RUNNING"
+                        ? "PASS"
+                        : status.state === "STOPPED"
+                            ? "WARN"
+                            : "FAIL",
+                    message: `tunnel state is ${status.state}`,
+                },
+                {
+                    id: "tunnel-public-url",
+                    status: publicBaseUrl === undefined ? "FAIL" : "PASS",
+                    message: publicBaseUrl === undefined
+                        ? "publicBaseUrl is not configured"
+                        : `publicBaseUrl is ${publicBaseUrl}`,
+                },
+            ];
+            const healthy = login === "LOGGED_IN" &&
+                status.state === "RUNNING" &&
+                publicBaseUrl !== undefined;
+            return {
+                result: healthy
+                    ? { ...success(), checks }
+                    : {
+                        ...actionRequired("repair-tunnel", "dev-tunnel resource is not healthy"),
+                        checks,
+                    },
+                observedEffects: [],
+            };
+        },
+        start: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "Cannot start without a bound dev-tunnel resource"),
+                    observedEffects: [],
+                };
+            }
+            if ((await input.runtime.loginStatus()) !== "LOGGED_IN") {
+                return {
+                    result: actionRequired("complete-tunnel-login", "Complete the interactive dev-tunnel login before starting the tunnel"),
+                    observedEffects: [],
+                };
+            }
+            try {
+                const observation = await input.runtime.start();
+                return {
+                    result: success(observation),
+                    observedEffects: ["Manage the dev-tunnel public ingress process"],
+                };
+            }
+            catch (error) {
+                return {
+                    result: actionRequired("start-tunnel", error instanceof Error
+                        ? error.message
+                        : "failed to start the dev-tunnel process"),
+                    observedEffects: [],
+                };
+            }
+        },
+        stop: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "No bound dev-tunnel resource to stop"),
+                    observedEffects: [],
+                };
+            }
+            const stopped = await input.runtime.stop();
+            if (stopped.state === "STOPPED") {
+                return {
+                    result: success(),
+                    observedEffects: ["Manage the dev-tunnel public ingress process"],
+                };
+            }
+            return {
+                result: actionRequired("complete-tunnel-stop", "dev-tunnel stop state is UNKNOWN; cannot confirm the tunnel stopped"),
+                observedEffects: [],
+            };
+        },
+        uninstall: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "No bound dev-tunnel resource to stop before package removal"),
+                    observedEffects: [],
+                };
+            }
+            const stopped = await input.runtime.stop();
+            if (stopped.state === "STOPPED") {
+                return {
+                    result: success(),
+                    observedEffects: ["Manage the dev-tunnel public ingress process"],
+                };
+            }
+            return {
+                result: actionRequired("complete-tunnel-stop", "dev-tunnel stop state is UNKNOWN; package removal cannot continue"),
+                observedEffects: [],
+            };
+        },
+        restart: async () => {
+            if (!input) {
+                return {
+                    result: actionRequired("configure-tunnel", "No bound dev-tunnel resource to restart"),
+                    observedEffects: [],
+                };
+            }
+            if ((await input.runtime.loginStatus()) !== "LOGGED_IN") {
+                return {
+                    result: actionRequired("complete-tunnel-login", "Complete the interactive dev-tunnel login before restarting the tunnel"),
+                    observedEffects: [],
+                };
+            }
+            const stopped = await input.runtime.stop();
+            if (stopped.state !== "STOPPED") {
+                return {
+                    result: actionRequired("complete-tunnel-stop", "Cannot restart: dev-tunnel stop state is UNKNOWN"),
+                    observedEffects: [],
+                };
+            }
+            try {
+                const observation = await input.runtime.start();
+                return {
+                    result: success(observation),
+                    observedEffects: ["Manage the dev-tunnel public ingress process"],
+                };
+            }
+            catch (error) {
+                return {
+                    result: actionRequired("start-tunnel", error instanceof Error
+                        ? error.message
+                        : "failed to start the dev-tunnel process"),
+                    observedEffects: [],
+                };
+            }
+        },
+    };
+}
+function failureReason(verification) {
+    const failed = verification.checks.find((check) => check.status === "FAIL");
+    return failed?.message ?? "public ingress verification did not pass";
+}
+export const behaviorAdapter = createBehaviorAdapter();
+export async function createProductionBinding(input) {
+    const publicBaseUrl = input.config.publicBaseUrl;
+    if (!publicBaseUrl)
+        return undefined;
+    const { createDevTunnelRuntime } = await import("../src/resource-adapter.js");
+    return {
+        behaviorAdapter: createBehaviorAdapter({
+            runtime: createDevTunnelRuntime({
+                publicBaseUrl,
+                ...(input.config.tunnelId ? { tunnelId: input.config.tunnelId } : {}),
+            }),
+        }),
+    };
+}

package/dist/deployment/descriptor.d.ts

@@ -0,0 +1,75 @@
+export declare const descriptor: {
+    readonly contract: "module";
+    readonly contractVersion: "1.0.0";
+    readonly moduleRef: "dev-tunnel";
+    readonly packageName: "@tomflow/proflow-dev-tunnel";
+    readonly moduleVersion: "0.1.0";
+    readonly kind: "external-resource";
+    readonly templateVersion: "1.0.0";
+    readonly platformCompatibility: ">=1.0.0 <2.0.0";
+    readonly installClass: "core";
+    readonly identity: {
+        readonly domain: "deployment-governance";
+        readonly summary: "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.";
+    };
+    readonly provides: readonly [];
+    readonly requires: readonly [];
+    readonly requirements: readonly [{
+        readonly kind: "executable";
+        readonly command: "devtunnel";
+    }, {
+        readonly kind: "human";
+        readonly action: "Complete Microsoft Dev Tunnel login when required";
+    }];
+    readonly configSlots: readonly [{
+        readonly key: "publicBaseUrl";
+        readonly type: "url";
+        readonly required: true;
+        readonly description: "Public HTTPS URL supplied by the dev-tunnel resource";
+    }, {
+        readonly key: "tunnelId";
+        readonly type: "string";
+        readonly required: false;
+        readonly description: "Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop";
+    }];
+    readonly lifecycle: {
+        readonly supported: readonly ["describe", "preflight", "status", "verify", "doctor", "start", "stop", "restart", "uninstall"];
+    };
+    readonly verification: {
+        readonly checks: readonly [{
+            readonly id: "tunnel-status";
+            readonly description: "dev-tunnel process reports a real running or stopped state";
+            readonly lifecycle: "status";
+        }, {
+            readonly id: "tunnel-public-ingress";
+            readonly description: "public HTTPS ingress passes the frozen TLS/port/size/latency contract";
+            readonly lifecycle: "verify";
+        }, {
+            readonly id: "tunnel-file-relay";
+            readonly description: "file relay behind the public ingress is reachable";
+            readonly lifecycle: "verify";
+        }, {
+            readonly id: "tunnel-diagnostics";
+            readonly description: "dev-tunnel configuration has actionable diagnostics";
+            readonly lifecycle: "doctor";
+        }];
+    };
+    readonly effects: readonly [{
+        readonly kind: "process";
+        readonly description: "Manage the dev-tunnel public ingress process";
+        readonly retention: "remove";
+    }, {
+        readonly kind: "network";
+        readonly description: "Probes the dev-tunnel public HTTPS ingress";
+        readonly retention: "preserve";
+    }, {
+        readonly kind: "external-resource";
+        readonly description: "Exposes the local platform via a public HTTPS tunnel";
+        readonly retention: "preserve";
+    }];
+    readonly documentation: readonly [{
+        readonly id: "overview";
+        readonly path: "./README.md";
+        readonly description: "Dev Tunnel module overview";
+    }];
+};

package/dist/deployment/descriptor.js

@@ -0,0 +1,99 @@
+export const descriptor = {
+    contract: "module",
+    contractVersion: "1.0.0",
+    moduleRef: "dev-tunnel",
+    packageName: "@tomflow/proflow-dev-tunnel",
+    moduleVersion: "0.1.0",
+    kind: "external-resource",
+    templateVersion: "1.0.0",
+    platformCompatibility: ">=1.0.0 <2.0.0",
+    installClass: "core",
+    identity: {
+        domain: "deployment-governance",
+        summary: "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.",
+    },
+    provides: [],
+    requires: [],
+    requirements: [
+        { kind: "executable", command: "devtunnel" },
+        {
+            kind: "human",
+            action: "Complete Microsoft Dev Tunnel login when required",
+        },
+    ],
+    configSlots: [
+        {
+            key: "publicBaseUrl",
+            type: "url",
+            required: true,
+            description: "Public HTTPS URL supplied by the dev-tunnel resource",
+        },
+        {
+            key: "tunnelId",
+            type: "string",
+            required: false,
+            description: "Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop",
+        },
+    ],
+    lifecycle: {
+        supported: [
+            "describe",
+            "preflight",
+            "status",
+            "verify",
+            "doctor",
+            "start",
+            "stop",
+            "restart",
+            "uninstall",
+        ],
+    },
+    verification: {
+        checks: [
+            {
+                id: "tunnel-status",
+                description: "dev-tunnel process reports a real running or stopped state",
+                lifecycle: "status",
+            },
+            {
+                id: "tunnel-public-ingress",
+                description: "public HTTPS ingress passes the frozen TLS/port/size/latency contract",
+                lifecycle: "verify",
+            },
+            {
+                id: "tunnel-file-relay",
+                description: "file relay behind the public ingress is reachable",
+                lifecycle: "verify",
+            },
+            {
+                id: "tunnel-diagnostics",
+                description: "dev-tunnel configuration has actionable diagnostics",
+                lifecycle: "doctor",
+            },
+        ],
+    },
+    effects: [
+        {
+            kind: "process",
+            description: "Manage the dev-tunnel public ingress process",
+            retention: "remove",
+        },
+        {
+            kind: "network",
+            description: "Probes the dev-tunnel public HTTPS ingress",
+            retention: "preserve",
+        },
+        {
+            kind: "external-resource",
+            description: "Exposes the local platform via a public HTTPS tunnel",
+            retention: "preserve",
+        },
+    ],
+    documentation: [
+        {
+            id: "overview",
+            path: "./README.md",
+            description: "Dev Tunnel module overview",
+        },
+    ],
+};

package/dist/deployment/requirements.d.ts

@@ -0,0 +1,7 @@
+export declare const requirements: readonly [{
+    readonly kind: "executable";
+    readonly command: "devtunnel";
+}, {
+    readonly kind: "human";
+    readonly action: "Complete Microsoft Dev Tunnel login when required";
+}];

package/dist/deployment/requirements.js

@@ -0,0 +1,2 @@
+import { descriptor } from "./descriptor.js";
+export const requirements = descriptor.requirements;

package/dist/deployment/verification.d.ts

@@ -0,0 +1,19 @@
+export declare const verification: {
+    readonly checks: readonly [{
+        readonly id: "tunnel-status";
+        readonly description: "dev-tunnel process reports a real running or stopped state";
+        readonly lifecycle: "status";
+    }, {
+        readonly id: "tunnel-public-ingress";
+        readonly description: "public HTTPS ingress passes the frozen TLS/port/size/latency contract";
+        readonly lifecycle: "verify";
+    }, {
+        readonly id: "tunnel-file-relay";
+        readonly description: "file relay behind the public ingress is reachable";
+        readonly lifecycle: "verify";
+    }, {
+        readonly id: "tunnel-diagnostics";
+        readonly description: "dev-tunnel configuration has actionable diagnostics";
+        readonly lifecycle: "doctor";
+    }];
+};

package/dist/deployment/verification.js

@@ -0,0 +1,2 @@
+import { descriptor } from "./descriptor.js";
+export const verification = descriptor.verification;

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+export { behaviorAdapter, createBehaviorAdapter, } from "../deployment/adapter.ts";
+export { descriptor } from "../deployment/descriptor.ts";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+export { behaviorAdapter, createBehaviorAdapter, } from "../deployment/adapter.js";
+export { descriptor } from "../deployment/descriptor.js";

package/dist/src/resource-adapter.d.ts

@@ -0,0 +1,57 @@
+export type DevTunnelState = "STOPPED" | "RUNNING" | "UNKNOWN";
+export type DevTunnelLoginStatus = "LOGGED_IN" | "NOT_LOGGED_IN" | "UNKNOWN";
+export interface DevTunnelObservation {
+    state: DevTunnelState;
+    login: DevTunnelLoginStatus;
+    publicBaseUrl?: string;
+}
+export interface CommandResult {
+    exitCode: number | null;
+    stdout: string;
+    stderr: string;
+}
+export type CommandRunner = (command: string, args: string[], options?: {
+    timeoutMs?: number;
+}) => Promise<CommandResult>;
+export interface DevTunnelRuntime {
+    readonly command: string;
+    status(): Promise<DevTunnelObservation>;
+    loginStatus(): Promise<DevTunnelLoginStatus>;
+    publicBaseUrl(): string | undefined;
+    start(): Promise<DevTunnelObservation>;
+    stop(): Promise<DevTunnelObservation>;
+    restart(): Promise<DevTunnelObservation>;
+}
+export declare function createDevTunnelRuntime(input: {
+    command?: string;
+    tunnelId?: string;
+    publicBaseUrl?: string;
+    runCommand?: CommandRunner;
+}): DevTunnelRuntime;
+export interface IngressCheck {
+    id: string;
+    status: "PASS" | "FAIL" | "WARN" | "SKIP";
+    message: string;
+}
+export interface PublicIngressVerification {
+    reachable: boolean;
+    ok: boolean;
+    checks: IngressCheck[];
+}
+export interface ErrorSemanticsProof {
+    rateLimit429Verified: boolean;
+    server5xxVerified: boolean;
+    message: string;
+}
+export interface FileRelayProof {
+    verified: boolean;
+    message: string;
+}
+export interface PublicIngressVerifyOptions {
+    verifyErrorSemantics?: () => Promise<ErrorSemanticsProof>;
+    verifyFileRelay?: () => Promise<FileRelayProof>;
+    timeoutMs?: number;
+}
+export declare function probeTlsProtocol(host: string, port: number, timeoutMs: number): Promise<string | undefined>;
+export declare function readResponseChars(response: Response, ceiling: number): Promise<number | undefined>;
+export declare function verifyPublicIngress(publicBaseUrl: string, options?: PublicIngressVerifyOptions): Promise<PublicIngressVerification>;

package/dist/src/resource-adapter.js

@@ -0,0 +1,309 @@
+import { execFile, spawn } from "node:child_process";
+import { connect } from "node:tls";
+const LOGIN_ARGS = ["user", "show"];
+const LOGIN_TIMEOUT_MS = 10_000;
+const START_CONFIRM_MS = 500;
+function defaultCommandRunner(command, args, options) {
+    return new Promise((resolve) => {
+        execFile(command, args, { timeout: options?.timeoutMs ?? 10_000 }, (error, stdout, stderr) => {
+            if (error) {
+                const err = error;
+                if (err.killed === true) {
+                    resolve({
+                        exitCode: null,
+                        stdout: String(stdout ?? ""),
+                        stderr: "command timed out",
+                    });
+                    return;
+                }
+                resolve({
+                    exitCode: typeof err.code === "number" ? err.code : null,
+                    stdout: String(stdout ?? ""),
+                    stderr: String(stderr ?? ""),
+                });
+                return;
+            }
+            resolve({
+                exitCode: 0,
+                stdout: String(stdout ?? ""),
+                stderr: String(stderr ?? ""),
+            });
+        });
+    });
+}
+export function createDevTunnelRuntime(input) {
+    const command = input.command ?? "devtunnel";
+    const tunnelId = input.tunnelId;
+    const publicBaseUrl = input.publicBaseUrl;
+    const run = input.runCommand ?? defaultCommandRunner;
+    let child;
+    const observeLogin = async () => {
+        let result;
+        try {
+            result = await run(command, LOGIN_ARGS, { timeoutMs: LOGIN_TIMEOUT_MS });
+        }
+        catch {
+            return "UNKNOWN";
+        }
+        if (result.exitCode === 0) {
+            return result.stdout.trim().length > 0 ? "LOGGED_IN" : "NOT_LOGGED_IN";
+        }
+        return result.exitCode === null ? "UNKNOWN" : "NOT_LOGGED_IN";
+    };
+    const observe = async (state) => {
+        const login = await observeLogin();
+        return {
+            state,
+            login,
+            ...(publicBaseUrl === undefined ? {} : { publicBaseUrl }),
+        };
+    };
+    return {
+        command,
+        // A live owned child is RUNNING; without one we cannot prove the
+        // external tunnel has stopped, so we report UNKNOWN rather than a
+        // deterministic STOPPED.
+        status: () => observe(child ? "RUNNING" : "UNKNOWN"),
+        loginStatus: () => observeLogin(),
+        publicBaseUrl: () => publicBaseUrl,
+        async start() {
+            const login = await observeLogin();
+            if (login !== "LOGGED_IN")
+                return observe("UNKNOWN");
+            if (tunnelId === undefined) {
+                throw new TypeError("tunnelId is required to host the configured persistent tunnel");
+            }
+            if (child)
+                return observe("RUNNING");
+            child = spawn(command, ["host", tunnelId], { stdio: "ignore" });
+            const confirmed = await new Promise((resolve) => {
+                let settled = false;
+                const fail = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    child = undefined;
+                    resolve("FAILED");
+                };
+                child?.once("error", fail);
+                child?.once("exit", fail);
+                setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve("RUNNING");
+                }, START_CONFIRM_MS);
+            });
+            if (confirmed === "FAILED") {
+                throw new Error("devtunnel host process failed to start");
+            }
+            return observe("RUNNING");
+        },
+        async stop() {
+            if (child) {
+                child.kill();
+                child = undefined;
+                return observe("STOPPED");
+            }
+            return observe("UNKNOWN");
+        },
+        async restart() {
+            const stopped = await this.stop();
+            if (stopped.state !== "STOPPED")
+                return stopped;
+            return this.start();
+        },
+    };
+}
+const TLS_PROTOCOL_RANK = {
+    TLSv1: 10,
+    "TLSv1.1": 11,
+    "TLSv1.2": 12,
+    "TLSv1.3": 13,
+};
+function tlsProtocolAtLeast(protocol, minimum) {
+    return ((TLS_PROTOCOL_RANK[protocol] ?? 0) >= (TLS_PROTOCOL_RANK[minimum] ?? 0));
+}
+export function probeTlsProtocol(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = (protocol) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            socket.destroy();
+            resolve(protocol);
+        };
+        const socket = connect({ host, port, servername: host, rejectUnauthorized: true }, () => finish(socket.getProtocol() ?? undefined));
+        timer = setTimeout(() => finish(undefined), timeoutMs);
+        socket.once("error", () => finish(undefined));
+    });
+}
+export async function readResponseChars(response, ceiling) {
+    const body = response.body;
+    if (body === null)
+        return 0;
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let chars = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                chars += decoder.decode().length;
+                break;
+            }
+            chars += decoder.decode(value, { stream: true }).length;
+            if (chars >= ceiling) {
+                await reader.cancel();
+                break;
+            }
+        }
+        return chars;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function verifyPublicIngress(publicBaseUrl, options) {
+    const timeoutMs = options?.timeoutMs ?? 45_000;
+    const checks = [];
+    let url;
+    try {
+        url = new URL(publicBaseUrl);
+    }
+    catch {
+        return {
+            reachable: false,
+            ok: false,
+            checks: [
+                {
+                    id: "public-https-url",
+                    status: "FAIL",
+                    message: `publicBaseUrl is not a valid URL: ${publicBaseUrl}`,
+                },
+            ],
+        };
+    }
+    const isHttps = url.protocol === "https:";
+    const port = url.port === "" ? 443 : Number(url.port);
+    const isPort443 = port === 443;
+    checks.push({
+        id: "public-https-port-443",
+        status: isHttps && isPort443 ? "PASS" : "FAIL",
+        message: isHttps && isPort443
+            ? "public ingress is public HTTPS on port 443"
+            : `public ingress must be HTTPS on port 443 (got ${url.protocol}// port ${port})`,
+    });
+    if (!isHttps) {
+        return { reachable: false, ok: false, checks };
+    }
+    const tlsProtocol = await probeTlsProtocol(url.hostname, port, timeoutMs);
+    const tlsOk = tlsProtocol !== undefined && tlsProtocolAtLeast(tlsProtocol, "TLSv1.2");
+    checks.push({
+        id: "tls-version",
+        status: tlsProtocol === undefined ? "FAIL" : tlsOk ? "PASS" : "FAIL",
+        message: tlsProtocol === undefined
+            ? "could not negotiate a TLS connection to the public ingress within the timeout"
+            : tlsOk
+                ? `TLS handshake negotiated ${tlsProtocol} (>= TLSv1.2)`
+                : `TLS handshake negotiated ${tlsProtocol} (< TLSv1.2)`,
+    });
+    let statusCode = 0;
+    let responseChars = 0;
+    let roundTripMs;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    const startedAt = Date.now();
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            signal: controller.signal,
+        });
+        statusCode = response.status;
+        const chars = await readResponseChars(response, 100_000);
+        if (chars === undefined) {
+            roundTripMs = undefined;
+        }
+        else {
+            responseChars = chars;
+            roundTripMs = Date.now() - startedAt;
+        }
+    }
+    catch {
+        roundTripMs = undefined;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const httpReachable = roundTripMs !== undefined && statusCode > 0;
+    checks.push({
+        id: "round-trip-ceiling",
+        status: httpReachable && roundTripMs !== undefined && roundTripMs <= timeoutMs
+            ? "PASS"
+            : "FAIL",
+        message: httpReachable && roundTripMs !== undefined
+            ? `probe round-trip completed in ${roundTripMs}ms (ceiling ${timeoutMs}ms)`
+            : "public ingress did not respond within the round-trip ceiling",
+    });
+    const sizeOk = responseChars < 100_000;
+    checks.push({
+        id: "request-response-size",
+        status: !httpReachable ? "FAIL" : sizeOk ? "PASS" : "FAIL",
+        message: !httpReachable
+            ? "could not measure the probe response size"
+            : sizeOk
+                ? `probe response is ${responseChars} chars (< 100,000)`
+                : `probe response is ${responseChars} chars (>= 100,000)`,
+    });
+    // File relay is a frozen hard contract; a missing real proof is a FAIL, never SKIP.
+    if (options?.verifyFileRelay === undefined) {
+        checks.push({
+            id: "file-relay-reachable",
+            status: "FAIL",
+            message: "file relay proof is not injected; relay reachability is unverified",
+        });
+    }
+    else {
+        const proof = await options.verifyFileRelay();
+        checks.push({
+            id: "file-relay-reachable",
+            status: proof.verified ? "PASS" : "FAIL",
+            message: proof.message,
+        });
+    }
+    // Real 429/5xx semantics are a frozen hard contract; missing proof is a FAIL.
+    if (options?.verifyErrorSemantics === undefined) {
+        checks.push({
+            id: "real-status-429",
+            status: "FAIL",
+            message: "429 proof is not injected; rate-limit semantics are unverified",
+        }, {
+            id: "real-status-5xx",
+            status: "FAIL",
+            message: "5xx proof is not injected; server-error semantics are unverified",
+        });
+    }
+    else {
+        const proof = await options.verifyErrorSemantics();
+        checks.push({
+            id: "real-status-429",
+            status: proof.rateLimit429Verified ? "PASS" : "FAIL",
+            message: proof.rateLimit429Verified
+                ? "429 rate-limit semantics verified"
+                : "429 rate-limit semantics unverified",
+        }, {
+            id: "real-status-5xx",
+            status: proof.server5xxVerified ? "PASS" : "FAIL",
+            message: proof.server5xxVerified
+                ? "5xx server-error semantics verified"
+                : "5xx server-error semantics unverified",
+        });
+    }
+    const reachable = httpReachable;
+    const ok = checks.every((check) => check.status === "PASS");
+    return { reachable, ok, checks };
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@tomflow/proflow-dev-tunnel",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./deployment/adapter": "./dist/deployment/adapter.js",
+    "./deployment/descriptor": "./dist/deployment/descriptor.js"
+  },
+  "files": [
+    "dist",
+    "proflow.module.json",
+    "conformance.json",
+    "README.md",
+    "self-install.mjs"
+  ],
+  "dependencies": {
+    "@tomflow/proflow-module-contract": "^0.1.0"
+  },
+  "devDependencies": {
+    "@tomflow/proflow-deployment-conformance": "^0.1.0"
+  },
+  "description": "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process.",
+  "keywords": [
+    "proflow",
+    "proflow-module",
+    "deployment-governance"
+  ],
+  "proflow": {
+    "module": true,
+    "installClass": "core",
+    "installRequires": [
+      "@tomflow/proflow-module-contract"
+    ],
+    "descriptor": "./dist/deployment/descriptor.js",
+    "manifest": "./proflow.module.json"
+  },
+  "bin": {
+    "proflow-dev-tunnel": "./self-install.mjs"
+  },
+  "scripts": {
+    "test": "node --test tests/**/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/proflow.module.json

@@ -0,0 +1,102 @@
+{
+	"contract": "module",
+	"contractVersion": "1.0.0",
+	"moduleRef": "dev-tunnel",
+	"packageName": "@tomflow/proflow-dev-tunnel",
+	"moduleVersion": "0.1.0",
+	"kind": "external-resource",
+	"templateVersion": "1.0.0",
+	"platformCompatibility": ">=1.0.0 <2.0.0",
+	"installClass": "core",
+	"identity": {
+		"domain": "deployment-governance",
+		"summary": "Governs the Microsoft Dev Tunnel public HTTPS ingress resource and its managed local host process."
+	},
+	"provides": [],
+	"requires": [],
+	"requirements": [
+		{
+			"kind": "executable",
+			"command": "devtunnel"
+		},
+		{
+			"kind": "human",
+			"action": "Complete Microsoft Dev Tunnel login when required"
+		}
+	],
+	"configSlots": [
+		{
+			"key": "publicBaseUrl",
+			"type": "url",
+			"required": true,
+			"description": "Public HTTPS URL supplied by the dev-tunnel resource"
+		},
+		{
+			"key": "tunnelId",
+			"type": "string",
+			"required": false,
+			"description": "Persistent Microsoft Dev Tunnel identifier used when this adapter owns lifecycle start/stop"
+		}
+	],
+	"lifecycle": {
+		"supported": [
+			"describe",
+			"preflight",
+			"status",
+			"verify",
+			"doctor",
+			"start",
+			"stop",
+			"restart",
+			"uninstall"
+		]
+	},
+	"verification": {
+		"checks": [
+			{
+				"id": "tunnel-status",
+				"description": "dev-tunnel process reports a real running or stopped state",
+				"lifecycle": "status"
+			},
+			{
+				"id": "tunnel-public-ingress",
+				"description": "public HTTPS ingress passes the frozen TLS/port/size/latency contract",
+				"lifecycle": "verify"
+			},
+			{
+				"id": "tunnel-file-relay",
+				"description": "file relay behind the public ingress is reachable",
+				"lifecycle": "verify"
+			},
+			{
+				"id": "tunnel-diagnostics",
+				"description": "dev-tunnel configuration has actionable diagnostics",
+				"lifecycle": "doctor"
+			}
+		]
+	},
+	"effects": [
+		{
+			"kind": "process",
+			"description": "Manage the dev-tunnel public ingress process",
+			"retention": "remove"
+		},
+		{
+			"kind": "network",
+			"description": "Probes the dev-tunnel public HTTPS ingress",
+			"retention": "preserve"
+		},
+		{
+			"kind": "external-resource",
+			"description": "Exposes the local platform via a public HTTPS tunnel",
+			"retention": "preserve"
+		}
+	],
+	"documentation": [
+		{
+			"id": "overview",
+			"path": "./README.md",
+			"description": "Dev Tunnel module overview"
+		}
+	]
+}

package/self-install.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+
+const [command, ...rest] = process.argv.slice(2);
+const usage = "Usage: npx @tomflow/proflow-dev-tunnel install\n";
+if (command === "--help" || command === "-h") {
+	process.stdout.write(usage);
+	process.exit(0);
+}
+if (command !== "install" || rest.length > 0) {
+	process.stderr.write(usage);
+	process.exit(2);
+}
+const executable = process.platform === "win32" ? "npx.cmd" : "npx";
+const result = spawnSync(
+	executable,
+	[
+		"--yes",
+		"@tomflow/proflow-platform-cli",
+		"install",
+		"@tomflow/proflow-dev-tunnel",
+	],
+	{ cwd: process.cwd(), env: process.env, stdio: "inherit" },
+);
+if (result.error) throw result.error;
+process.exit(result.status ?? 1);