@songsid/agend 2.1.5 → 2.1.6-beta.2

package/dist/tunnel/lease.js

@@ -0,0 +1,209 @@
+/**
+ * The record that says "a tunnel process may exist right now".
+ *
+ * It is written before anything is spawned and removed only after a death has
+ * been proven, so the file's presence is the pessimistic answer: a lease we
+ * cannot resolve blocks the next managed tunnel rather than being assumed
+ * stale. That is the whole point — a tunnel nobody is tracking is a public
+ * entrance nobody is watching.
+ *
+ * Deliberately free of any dependency on the fleet: the pre-fleet setup host
+ * has to run the reaper too, and it runs in a process where no FleetManager
+ * exists. Everything here takes a data directory and nothing else.
+ */
+import { closeSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { probeProcess } from "../web-terminal.js";
+import { TUNNEL_STOP_GRACE_MS } from "./types.js";
+export function leasePath(dataDir) {
+    return join(dataDir, "tunnel.lease");
+}
+/**
+ * Atomic, owner-only, and on disk before the call returns.
+ *
+ * The fsync is not ceremony: the lease has to survive the crash that makes it
+ * matter, and a rename that is only in page cache does not.
+ */
+export function writeLease(dataDir, lease) {
+    mkdirSync(dataDir, { recursive: true });
+    const path = leasePath(dataDir);
+    const temp = `${path}.tmp-${process.pid}-${randomBytes(6).toString("hex")}`;
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+        writeSync(fd, JSON.stringify(lease));
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(temp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(temp);
+        }
+        catch { /* already gone */ }
+        throw err;
+    }
+}
+export function readLease(dataDir) {
+    let raw;
+    try {
+        raw = readFileSync(leasePath(dataDir), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        // Unreadable is not absent. Saying "no lease" here would let a second
+        // tunnel start beside one we simply could not see.
+        throw err;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.provider !== "string" || typeof parsed.ownerPid !== "number")
+            return CORRUPT;
+        return {
+            sid: String(parsed.sid ?? ""),
+            provider: parsed.provider,
+            originPort: Number(parsed.originPort ?? 0),
+            providerPid: typeof parsed.providerPid === "number" ? parsed.providerPid : null,
+            strongIdentity: typeof parsed.strongIdentity === "string" ? parsed.strongIdentity : null,
+            expiresAt: Number(parsed.expiresAt ?? 0),
+            ownerPid: parsed.ownerPid,
+            ownerIdentity: typeof parsed.ownerIdentity === "string" ? parsed.ownerIdentity : null,
+        };
+    }
+    catch {
+        return CORRUPT;
+    }
+}
+/**
+ * A lease we cannot parse still means a tunnel may exist.
+ *
+ * Returning null would be "no tunnel", which is the one answer a damaged file
+ * cannot justify. This stands in as an unresolvable lease, so the reaper asks
+ * for a human instead of clearing the way.
+ */
+const CORRUPT = {
+    sid: "", provider: "unknown", originPort: 0,
+    providerPid: null, strongIdentity: null, expiresAt: 0, ownerPid: 0, ownerIdentity: null,
+};
+export function clearLease(dataDir) {
+    try {
+        unlinkSync(leasePath(dataDir));
+    }
+    catch { /* already gone */ }
+}
+/**
+ * Resolve whatever the last run left behind, before anything new is started.
+ *
+ * Runs from any process — the fleet at startup and the pre-fleet setup host
+ * both call it, which is why it takes a directory rather than a manager.
+ */
+export async function reapStaleTunnel(dataDir, opts = {}) {
+    const now = opts.now ?? Date.now;
+    const probe = opts.probe ?? probeProcess;
+    const kill = opts.kill ?? ((pid, signal) => { process.kill(pid, signal); });
+    const wait = opts.wait ?? ((ms) => new Promise(r => setTimeout(r, ms)));
+    const graceMs = opts.graceMs ?? TUNNEL_STOP_GRACE_MS;
+    let lease;
+    try {
+        lease = readLease(dataDir);
+    }
+    catch (err) {
+        // A lease we cannot read is not a lease that is absent. Letting this throw
+        // meant an unreadable file took the whole start down instead of closing it:
+        // the caller asks "may I open a tunnel", and the honest answer here is no.
+        return {
+            kind: "manual",
+            reason: `the lease file could not be read (${err.code ?? "unknown error"})`,
+            pid: null,
+            leasePath: leasePath(dataDir),
+        };
+    }
+    if (!lease)
+        return { kind: "clear" };
+    // Someone else is using it right now. An expired lease held by a live owner
+    // is still theirs: the owner is the one that will prove its child's death,
+    // and reaping underneath it would race that proof.
+    //
+    // "Alive" means the same process, not the same number. A pid that outlived
+    // its owner and was handed to something unrelated would otherwise hold this
+    // lease forever — which is exactly how ticket 5's setup-host lock became
+    // unreclaimable.
+    if (lease.ownerPid > 0 && lease.ownerPid !== process.pid) {
+        const owner = probe(lease.ownerPid);
+        const sameOwner = owner.kind === "identified" && lease.ownerIdentity
+            ? owner.identity === lease.ownerIdentity
+            : owner.kind !== "gone";
+        if (sameOwner)
+            return { kind: "held", ownerPid: lease.ownerPid };
+    }
+    void now;
+    if (lease.providerPid === null) {
+        // Reserved but never recorded: either nothing was ever spawned, or the
+        // owner died in the instant between the spawn returning and the pid being
+        // written. The second case leaves a child we cannot name, and guessing is
+        // exactly what this whole file exists to avoid.
+        return {
+            kind: "manual",
+            reason: "the lease names no process, so a tunnel may exist that cannot be identified",
+            pid: null,
+            leasePath: leasePath(dataDir),
+        };
+    }
+    const before = probe(lease.providerPid);
+    if (before.kind === "gone") {
+        clearLease(dataDir);
+        return { kind: "reaped", how: "already-gone", pid: lease.providerPid };
+    }
+    if (before.kind === "identified" && lease.strongIdentity && before.identity !== lease.strongIdentity) {
+        // The pid belongs to something else now, which proves the original died.
+        // Signalling it would kill an innocent process — the single most damaging
+        // thing a reaper can do, and the reason the fingerprint is recorded at all.
+        clearLease(dataDir);
+        return { kind: "reaped", how: "pid-reused", pid: lease.providerPid };
+    }
+    if (before.kind === "unknown" || !lease.strongIdentity) {
+        return {
+            kind: "manual",
+            reason: before.kind === "unknown"
+                ? "this platform cannot prove which process holds that pid"
+                : "the lease carries no fingerprint, so the pid cannot be matched to the original process",
+            pid: lease.providerPid,
+            leasePath: leasePath(dataDir),
+        };
+    }
+    for (const signal of ["SIGTERM", "SIGKILL"]) {
+        try {
+            kill(lease.providerPid, signal);
+        }
+        catch { /* it may have just exited */ }
+        await wait(graceMs);
+        const after = probe(lease.providerPid);
+        if (after.kind === "gone") {
+            clearLease(dataDir);
+            return { kind: "reaped", how: "killed", pid: lease.providerPid };
+        }
+        if (after.kind === "identified" && after.identity !== lease.strongIdentity) {
+            clearLease(dataDir);
+            return { kind: "reaped", how: "pid-reused", pid: lease.providerPid };
+        }
+    }
+    return {
+        kind: "manual",
+        reason: "the process did not exit after SIGTERM and SIGKILL",
+        pid: lease.providerPid,
+        leasePath: leasePath(dataDir),
+    };
+}
+/** What to tell a human when a lease could not be resolved. Never "closed safely". */
+export function manualCleanupMessage(outcome) {
+    const target = outcome.pid === null ? "the tunnel process" : `pid ${outcome.pid}`;
+    return `A tunnel could not be confirmed closed: ${outcome.reason}. `
+        + `No new tunnel will be opened until this is resolved. Check ${target}, kill it if it is still running, `
+        + `then delete ${outcome.leasePath}.`;
+}
+//# sourceMappingURL=lease.js.map

package/dist/tunnel/lease.js.map

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

package/dist/tunnel/manager.d.ts

@@ -0,0 +1,56 @@
+import { probeProcess } from "../web-terminal.js";
+import { type ReapOptions, type ReapOutcome } from "./lease.js";
+import { type TunnelHandle, type TunnelProvider, type TunnelStartContext, type TunnelStopResult } from "./types.js";
+export interface ManagedTunnelOptions extends ReapOptions {
+    dataDir: string;
+    log?: (message: string) => void;
+}
+export type ManagedStartResult = {
+    readonly ok: true;
+    readonly handle: TunnelHandle;
+} | {
+    readonly ok: false;
+    readonly errorKind: string;
+    readonly message: string;
+    readonly leaseHeld: boolean;
+};
+/**
+ * Owns the fleet-wide managed-tunnel lease.
+ *
+ * Fleet-wide rather than per-caller: the lease outlives the process that wrote
+ * it, so "am I already running one" is a question about the machine, not about
+ * this object.
+ */
+export declare class ManagedTunnel {
+    private readonly opts;
+    private inFlight;
+    private active;
+    /** Set when a stop could not be proven; blocks every later start in this process. */
+    private blocked;
+    constructor(opts: ManagedTunnelOptions);
+    private log;
+    /** Our own fingerprint, so a reaper can tell this owner from a reused pid. */
+    private ownerIdentity;
+    get handle(): TunnelHandle | null;
+    /** Clear whatever a previous run left behind. Safe to call from any process. */
+    reap(): Promise<ReapOutcome>;
+    /**
+     * Single-flight: two concurrent callers get the same attempt, not two tunnels.
+     *
+     * The guard is set synchronously before the first await, because "check then
+     * await then set" is how two callers both find it free.
+     */
+    start(provider: TunnelProvider, ctx: TunnelStartContext): Promise<ManagedStartResult>;
+    private doStart;
+    /**
+     * Stop the active tunnel and release the lease — but only on proof.
+     *
+     * An unconfirmed stop keeps the lease and blocks the next start. The caller
+     * gets the result rather than an exception precisely so it cannot forget to
+     * say so out loud.
+     */
+    stop(reason: string): Promise<TunnelStopResult>;
+}
+/** A tunnel's opaque id. Not a credential — it identifies, it does not authorize. */
+export declare function newTunnelSid(): string;
+export { probeProcess };

package/dist/tunnel/manager.js

@@ -0,0 +1,167 @@
+/**
+ * One managed tunnel at a time, and never one nobody is tracking.
+ *
+ * The provider knows how to run cloudflared. This knows the two rules that make
+ * running it safe: the lease is written before a child can exist and removed
+ * only after a death is proven, and a start that fails does not report failure
+ * until it has proven the child it created is gone. A "clean" fallback running
+ * beside a live tunnel is the failure this exists to prevent.
+ */
+import { randomBytes } from "node:crypto";
+import { probeProcess } from "../web-terminal.js";
+import { clearLease, manualCleanupMessage, reapStaleTunnel, writeLease } from "./lease.js";
+import { TunnelStartError, } from "./types.js";
+/**
+ * Owns the fleet-wide managed-tunnel lease.
+ *
+ * Fleet-wide rather than per-caller: the lease outlives the process that wrote
+ * it, so "am I already running one" is a question about the machine, not about
+ * this object.
+ */
+export class ManagedTunnel {
+    opts;
+    inFlight = null;
+    active = null;
+    /** Set when a stop could not be proven; blocks every later start in this process. */
+    blocked = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    log(message) { (this.opts.log ?? (() => { }))(message); }
+    /** Our own fingerprint, so a reaper can tell this owner from a reused pid. */
+    ownerIdentity() {
+        const probe = (this.opts.probe ?? probeProcess)(process.pid);
+        return probe.kind === "identified" ? probe.identity : null;
+    }
+    get handle() { return this.active; }
+    /** Clear whatever a previous run left behind. Safe to call from any process. */
+    async reap() {
+        const outcome = await reapStaleTunnel(this.opts.dataDir, this.opts);
+        if (outcome.kind === "manual") {
+            this.blocked = manualCleanupMessage(outcome);
+            this.log(this.blocked);
+        }
+        return outcome;
+    }
+    /**
+     * Single-flight: two concurrent callers get the same attempt, not two tunnels.
+     *
+     * The guard is set synchronously before the first await, because "check then
+     * await then set" is how two callers both find it free.
+     */
+    start(provider, ctx) {
+        if (this.inFlight)
+            return this.inFlight;
+        const run = this.doStart(provider, ctx).finally(() => { this.inFlight = null; });
+        this.inFlight = run;
+        return run;
+    }
+    async doStart(provider, ctx) {
+        if (this.blocked) {
+            return { ok: false, errorKind: "lease-held", message: this.blocked, leaseHeld: true };
+        }
+        if (this.active) {
+            return { ok: false, errorKind: "lease-held", message: "a managed tunnel is already running", leaseHeld: true };
+        }
+        const outcome = await this.reap();
+        if (outcome.kind === "held") {
+            return {
+                ok: false, errorKind: "lease-held", leaseHeld: true,
+                message: `another process (pid ${outcome.ownerPid}) already owns the managed tunnel`,
+            };
+        }
+        if (outcome.kind === "manual") {
+            return { ok: false, errorKind: "lease-held", message: manualCleanupMessage(outcome), leaseHeld: true };
+        }
+        // Reserved before the spawn, not after: between these two writes a child
+        // may come into existence, and a crash in that window must leave evidence
+        // rather than silence.
+        writeLease(this.opts.dataDir, {
+            sid: ctx.sid,
+            provider: provider.name,
+            originPort: Number(ctx.origin.port),
+            providerPid: null,
+            strongIdentity: null,
+            expiresAt: ctx.expiresAt,
+            ownerPid: process.pid,
+            ownerIdentity: this.ownerIdentity(),
+        });
+        let handle;
+        try {
+            handle = await provider.start(ctx);
+        }
+        catch (err) {
+            const startError = err instanceof TunnelStartError ? err : null;
+            if (startError?.unconfirmed) {
+                // A child exists and we cannot prove otherwise. The lease stays, and so
+                // does the block: this is the one case where doing nothing further is
+                // the correct, and only honest, behaviour.
+                writeLease(this.opts.dataDir, {
+                    sid: ctx.sid,
+                    provider: provider.name,
+                    originPort: Number(ctx.origin.port),
+                    providerPid: startError.unconfirmed.pid,
+                    strongIdentity: startError.unconfirmed.identity,
+                    expiresAt: ctx.expiresAt,
+                    ownerPid: process.pid,
+                    ownerIdentity: this.ownerIdentity(),
+                });
+                this.blocked = `A tunnel process could not be confirmed stopped after a failed start`
+                    + `${startError.unconfirmed.pid !== null ? ` (pid ${startError.unconfirmed.pid})` : ""}. `
+                    + "No new tunnel will be opened until it is resolved.";
+                this.log(this.blocked);
+                return { ok: false, errorKind: startError.errorKind, message: this.blocked, leaseHeld: true };
+            }
+            // The provider proved its child is gone (or never made one), so the lease
+            // describes nothing and may go.
+            clearLease(this.opts.dataDir);
+            return {
+                ok: false,
+                errorKind: startError?.errorKind ?? "spawn-failed",
+                message: err.message,
+                leaseHeld: false,
+            };
+        }
+        writeLease(this.opts.dataDir, {
+            sid: ctx.sid,
+            provider: provider.name,
+            originPort: Number(ctx.origin.port),
+            providerPid: handle.pid,
+            strongIdentity: handle.identity,
+            expiresAt: ctx.expiresAt,
+            ownerPid: process.pid,
+            ownerIdentity: this.ownerIdentity(),
+        });
+        this.active = handle;
+        return { ok: true, handle };
+    }
+    /**
+     * Stop the active tunnel and release the lease — but only on proof.
+     *
+     * An unconfirmed stop keeps the lease and blocks the next start. The caller
+     * gets the result rather than an exception precisely so it cannot forget to
+     * say so out loud.
+     */
+    async stop(reason) {
+        const handle = this.active;
+        if (!handle)
+            return { confirmed: true };
+        const result = await handle.stop(reason);
+        this.active = null;
+        if (result.confirmed) {
+            clearLease(this.opts.dataDir);
+            return result;
+        }
+        this.blocked = `A tunnel could not be confirmed closed`
+            + `${result.pid !== null ? ` (pid ${result.pid})` : ""}: ${result.reason}. `
+            + "No new tunnel will be opened until it is resolved.";
+        this.log(this.blocked);
+        return result;
+    }
+}
+/** A tunnel's opaque id. Not a credential — it identifies, it does not authorize. */
+export function newTunnelSid() {
+    return randomBytes(16).toString("hex");
+}
+export { probeProcess };
+//# sourceMappingURL=manager.js.map

package/dist/tunnel/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../../src/tunnel/manager.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,oBAAoB,EAAE,eAAe,EAAE,UAAU,EAAsC,MAAM,YAAY,CAAC;AAC/H,OAAO,EACL,gBAAgB,GAKjB,MAAM,YAAY,CAAC;AAWpB;;;;;;GAMG;AACH,MAAM,OAAO,aAAa;IAMK;IALrB,QAAQ,GAAuC,IAAI,CAAC;IACpD,MAAM,GAAwB,IAAI,CAAC;IAC3C,qFAAqF;IAC7E,OAAO,GAAkB,IAAI,CAAC;IAEtC,YAA6B,IAA0B;QAA1B,SAAI,GAAJ,IAAI,CAAsB;IAAG,CAAC;IAEnD,GAAG,CAAC,OAAe,IAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9E,8EAA8E;IACtE,aAAa;QACnB,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC7D,OAAO,KAAK,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;IAC7D,CAAC;IAED,IAAI,MAAM,KAA0B,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;IAEzD,gFAAgF;IAChF,KAAK,CAAC,IAAI;QACR,MAAM,OAAO,GAAG,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QACpE,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,IAAI,CAAC,OAAO,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;YAC7C,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,QAAwB,EAAE,GAAuB;QACrD,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC,QAAQ,CAAC;QACxC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QACjF,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC;QACpB,OAAO,GAAG,CAAC;IACb,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,QAAwB,EAAE,GAAuB;QACrE,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACxF,CAAC;QACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,qCAAqC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACjH,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,IAAI,EAAE,CAAC;QAClC,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC5B,OAAO;gBACL,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,EAAE,IAAI;gBACnD,OAAO,EAAE,wBAAwB,OAAO,CAAC,QAAQ,mCAAmC;aACrF,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,oBAAoB,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACzG,CAAC;QAED,yEAAyE;QACzE,0EAA0E;QAC1E,uBAAuB;QACvB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;YAC5B,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,QAAQ,EAAE,QAAQ,CAAC,IAAI;YACvB,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YACnC,WAAW,EAAE,IAAI;YACjB,cAAc,EAAE,IAAI;YACpB,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,QAAQ,EAAE,OAAO,CAAC,GAAG;YACrB,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE;SACpC,CAAC,CAAC;QAEH,IAAI,MAAoB,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,GAAG,YAAY,gBAAgB,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAChE,IAAI,UAAU,EAAE,WAAW,EAAE,CAAC;gBAC5B,wEAAwE;gBACxE,sEAAsE;gBACtE,2CAA2C;gBAC3C,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;oBAC5B,GAAG,EAAE,GAAG,CAAC,GAAG;oBACZ,QAAQ,EAAE,QAAQ,CAAC,IAAI;oBACvB,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;oBACnC,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,GAAG;oBACvC,cAAc,EAAE,UAAU,CAAC,WAAW,CAAC,QAAQ;oBAC/C,SAAS,EAAE,GAAG,CAAC,SAAS;oBACxB,QAAQ,EAAE,OAAO,CAAC,GAAG;oBACrB,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE;iBACpC,CAAC,CAAC;gBACH,IAAI,CAAC,OAAO,GAAG,sEAAsE;sBACjF,GAAG,UAAU,CAAC,WAAW,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,WAAW,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI;sBACxF,oDAAoD,CAAC;gBACzD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACvB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,UAAU,CAAC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;YAChG,CAAC;YACD,0EAA0E;YAC1E,gCAAgC;YAChC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC9B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,SAAS,EAAE,UAAU,EAAE,SAAS,IAAI,cAAc;gBAClD,OAAO,EAAG,GAAa,CAAC,OAAO;gBAC/B,SAAS,EAAE,KAAK;aACjB,CAAC;QACJ,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE;YAC5B,GAAG,EAAE,GAAG,CAAC,GAAG;YACZ,QAAQ,EAAE,QAAQ,CAAC,IAAI;YACvB,UAAU,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;YACnC,WAAW,EAAE,MAAM,CAAC,GAAG;YACvB,cAAc,EAAE,MAAM,CAAC,QAAQ;YAC/B,SAAS,EAAE,GAAG,CAAC,SAAS;YACxB,QAAQ,EAAE,OAAO,CAAC,GAAG;YACrB,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE;SACpC,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,CAAC,MAAc;QACvB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;QACxC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;YACrB,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC9B,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,wCAAwC;cACnD,GAAG,MAAM,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,MAAM,CAAC,MAAM,IAAI;cAC1E,oDAAoD,CAAC;QACzD,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvB,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,qFAAqF;AACrF,MAAM,UAAU,YAAY;IAC1B,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/tunnel/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * What a tunnel provider can do, and nothing about how.
+ *
+ * The contract exists so the thing that owns a listener never learns a
+ * provider's command line. It is deliberately narrow: a provider can be asked
+ * whether it could run, asked to expose one already-listening loopback origin,
+ * and asked to stop — and the answer to "did it stop" is a first-class value,
+ * not an exception, because "we could not tell" is a state the caller has to
+ * record and act on rather than a failure to handle.
+ *
+ * See `docs/design/setup-host-tunnel.zh-TW.md` for the envelope these types
+ * serve, and `docs/design/web-terminal-tunnel-provider.zh-TW.md` (sol) for the
+ * original provider design.
+ */
+export type TunnelVisibility = "public" | "tailnet" | "loopback" | "manual";
+/** Why a provider cannot run, in bounded terms — never a vendor error string. */
+export type TunnelErrorKind = "binary-missing" | "binary-not-executable" | "not-logged-in" | "spawn-failed" | "no-url" | "bad-url" | "readiness-failed" | "timeout" | "cancelled" | "lease-held";
+export type PreflightResult = {
+    readonly ok: true;
+    readonly binaryPath: string;
+} | {
+    readonly ok: false;
+    readonly errorKind: TunnelErrorKind;
+    readonly detail: string;
+};
+export interface TunnelStartContext {
+    /** Opaque id for logs and the lease; never a credential. */
+    readonly sid: string;
+    /** The origin to expose. Must be the loopback address the server really bound. */
+    readonly origin: URL;
+    /** Page path under the origin, trailing slash kept so relative assets resolve. */
+    readonly pagePath: string;
+    /**
+     * A string that must appear in the page fetched back over the public URL.
+     *
+     * Readiness is not "the process is alive" or "we saw a URL" — it is "the edge
+     * reaches the exact listener we meant", and only the caller knows what that
+     * listener serves.
+     */
+    readonly readinessMarker: string;
+    /** Wall clock. The tunnel may not outlive what it is fronting. */
+    readonly expiresAt: number;
+    readonly signal: AbortSignal;
+    /**
+     * The hostname this tunnel will answer on, as soon as it is known to be
+     * well-formed and before anything is fetched through it.
+     *
+     * A provider that forwards the browser's Host — which cloudflared does by
+     * default — makes the readiness probe arrive at the origin under the public
+     * hostname. An origin with a host allowlist will refuse it, and the tunnel
+     * that would have worked reports itself unreachable. Handing the exact
+     * validated string over at this point lets the origin expect it without
+     * loosening anything: it is the same host the provider is about to publish,
+     * one step earlier.
+     *
+     * The caller must undo whatever it did with this if `start` does not resolve.
+     */
+    readonly onCandidateHost?: (host: string) => void;
+}
+export interface TunnelExit {
+    readonly code: number | null;
+    readonly signal: NodeJS.Signals | null;
+}
+/**
+ * `confirmed: false` is an outcome, not an error.
+ *
+ * A caller that treats it as one will write "closed safely" in a log next to a
+ * process that is still running. It carries what a human needs to finish the
+ * job by hand.
+ */
+export type TunnelStopResult = {
+    readonly confirmed: true;
+} | {
+    readonly confirmed: false;
+    readonly reason: string;
+    readonly pid: number | null;
+    readonly identity: string | null;
+};
+export interface TunnelHandle {
+    readonly provider: string;
+    readonly visibility: TunnelVisibility;
+    /** Validated base, e.g. `https://<label>.trycloudflare.com`. No trailing slash. */
+    readonly baseUrl: string;
+    /** Where the page actually is, trailing slash intact. */
+    readonly pageUrl: string;
+    readonly pid: number | null;
+    /** The strong fingerprint recorded at spawn, for proving death later. */
+    readonly identity: string | null;
+    stop(reason: string): Promise<TunnelStopResult>;
+    /** Returns an unsubscribe. Fires only for an exit nobody asked for. */
+    onUnexpectedExit(listener: (exit: TunnelExit) => void): () => void;
+}
+export interface TunnelProvider {
+    readonly name: string;
+    /** Can this run at all? Bounded, read-only: never installs, never logs in. */
+    preflight(signal: AbortSignal): Promise<PreflightResult>;
+    /** Expose one loopback origin. Rejects with a `TunnelStartError`. */
+    start(ctx: TunnelStartContext): Promise<TunnelHandle>;
+}
+export declare class TunnelStartError extends Error {
+    readonly errorKind: TunnelErrorKind;
+    /** Present when a child was created and its death could not be confirmed. */
+    readonly unconfirmed?: {
+        readonly pid: number | null;
+        readonly identity: string | null;
+    } | undefined;
+    constructor(errorKind: TunnelErrorKind, message: string, 
+    /** Present when a child was created and its death could not be confirmed. */
+    unconfirmed?: {
+        readonly pid: number | null;
+        readonly identity: string | null;
+    } | undefined);
+}
+/** One wall-clock budget for spawn, URL and readiness together — not per step. */
+export declare const TUNNEL_STARTUP_DEADLINE_MS = 30000;
+/** Preflight is a stat, not a network call. */
+export declare const TUNNEL_PREFLIGHT_TIMEOUT_MS = 5000;
+/** How long a polite stop is given before escalating, and again before giving up. */
+export declare const TUNNEL_STOP_GRACE_MS = 5000;

package/dist/tunnel/types.js

@@ -0,0 +1,33 @@
+/**
+ * What a tunnel provider can do, and nothing about how.
+ *
+ * The contract exists so the thing that owns a listener never learns a
+ * provider's command line. It is deliberately narrow: a provider can be asked
+ * whether it could run, asked to expose one already-listening loopback origin,
+ * and asked to stop — and the answer to "did it stop" is a first-class value,
+ * not an exception, because "we could not tell" is a state the caller has to
+ * record and act on rather than a failure to handle.
+ *
+ * See `docs/design/setup-host-tunnel.zh-TW.md` for the envelope these types
+ * serve, and `docs/design/web-terminal-tunnel-provider.zh-TW.md` (sol) for the
+ * original provider design.
+ */
+export class TunnelStartError extends Error {
+    errorKind;
+    unconfirmed;
+    constructor(errorKind, message, 
+    /** Present when a child was created and its death could not be confirmed. */
+    unconfirmed) {
+        super(message);
+        this.errorKind = errorKind;
+        this.unconfirmed = unconfirmed;
+        this.name = "TunnelStartError";
+    }
+}
+/** One wall-clock budget for spawn, URL and readiness together — not per step. */
+export const TUNNEL_STARTUP_DEADLINE_MS = 30_000;
+/** Preflight is a stat, not a network call. */
+export const TUNNEL_PREFLIGHT_TIMEOUT_MS = 5_000;
+/** How long a polite stop is given before escalating, and again before giving up. */
+export const TUNNEL_STOP_GRACE_MS = 5_000;
+//# sourceMappingURL=types.js.map

package/dist/tunnel/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tunnel/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoGH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IAE9B;IAGA;IAJX,YACW,SAA0B,EACnC,OAAe;IACf,6EAA6E;IACpE,WAA+E;QAExF,KAAK,CAAC,OAAO,CAAC,CAAC;QALN,cAAS,GAAT,SAAS,CAAiB;QAG1B,gBAAW,GAAX,WAAW,CAAoE;QAGxF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAM,CAAC;AACjD,+CAA+C;AAC/C,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AACjD,qFAAqF;AACrF,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,CAAC"}

package/dist/ui/dashboard.html

@@ -277,7 +277,8 @@
 </div>
 
 <script>
-const T = new URLSearchParams(location.search).get("token") || "";
+// No token in the URL: the gate redeemed it for an HttpOnly session cookie,
+// which the browser attaches to these same-origin requests on its own.
 const UI_LANG = localStorage.getItem("agend_lang") || (navigator.language?.toLowerCase().startsWith("zh") ? "zh-TW" : "en");
 const UI_TEXT = {
   en: {
@@ -308,7 +309,7 @@ const msgs = {};
 async function api(m, p, b) {
   const o = { method: m, headers: { "Content-Type": "application/json" } };
   if (b) o.body = JSON.stringify(b);
-  const r = await fetch(`${p}${p.includes("?") ? "&" : "?"}token=${T}`, o);
+  const r = await fetch(p, o);
   return r.json();
 }
 function esc(s) { const d = document.createElement("div"); d.textContent = s || ""; return d.innerHTML; }
@@ -318,7 +319,7 @@ function toast(msg, ok=true) {
   document.body.appendChild(el); setTimeout(() => el.remove(), 3000);
 }
 
-const sse = new EventSource(`/ui/events?token=${T}`);
+const sse = new EventSource("/ui/events");
 sse.addEventListener("status", e => {
   const d = JSON.parse(e.data); instances = d.instances;
   document.getElementById("uptime").textContent = fmtUp(d.uptime);