@bakers-build/addon-ports-cloudflare-quick 0.0.0-stage → 0.1.0-next.38

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @bakers-build/addon-ports-cloudflare-quick
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+bakers.build ports transport: one cloudflared Quick Tunnel process per route, with no fixed name/URL/uptime guarantee. Implements @bakers-build/addon-ports's PortsTransport contract.
+
+Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://git.key-tec.de/bakers-build/bakers-build (bakers-cli/).

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+import type { PortsTransport } from '@bakers-build/addon-ports/transport';
+import { type QuickDeps } from './quick.js';
+export { AmbiguousOwnershipError, buildArgs, configPathFor, generationFromConfigPath, identityEquals, isOwnedArgv, logPathFor, type ManagedProcessIdentity, originEquals, parseLiveUrl, type QuickDeps, type QuickOrigin, type QuickRouteData, reconcileQuick, routeDirFor, sanitizeEnv, } from './quick.js';
+/**
+ * Real I/O deps for the Quick transport. `routeDir` scanning here walks
+ * the WHOLE `/proc` table, which is fine at the process counts this addon
+ * deals with (a handful of routes per machine) — a targeted index would be
+ * the upgrade if that stops being true.
+ * ponytail: full /proc scan per reconcile call, index by routeDir if this
+ * ever needs to run against hundreds of routes.
+ */
+/** Exported for a real-process regression test (R4-M1/I2 ownership
+ *  filtering); not part of the package's public contract. */
+export declare function createNodeDeps(): QuickDeps;
+/**
+ * Default export factory consumed by `@bakers-build/addon-ports`'s
+ * `loadPortsTransport`. No `zone` — Quick has no fixed `<ticket>-<key>.
+ * <zone>` naming, unlike Named Cloudflare/frp.
+ */
+export default function createTransport(settings: unknown, context: {
+    readonly home: string;
+}): Promise<PortsTransport>;

package/dist/src/index.js

@@ -0,0 +1,245 @@
+// BB-681 Task 4 — Quick Tunnel as a `PortsTransport`. See `quick.ts` for
+// the pure reconcile logic; this file only wires real I/O (spawn, `/proc`,
+// fs, clock) into `QuickDeps`, exactly as `addons/ports-cloudflare/src/
+// index.ts` wires real `fetch` into `CloudflareDeps`.
+import { execFile as execFileCallback, spawn as nodeSpawn, } from 'node:child_process';
+import { mkdir as fsMkdir, open as fsOpen, readdir as fsReaddir, readFile as fsReadFile, readlink as fsReadlink, } from 'node:fs/promises';
+import { promisify } from 'node:util';
+import { isOwnedArgv, reconcileQuick, } from './quick.js';
+export { AmbiguousOwnershipError, buildArgs, configPathFor, generationFromConfigPath, identityEquals, isOwnedArgv, logPathFor, originEquals, parseLiveUrl, reconcileQuick, routeDirFor, sanitizeEnv, } from './quick.js';
+const execFile = promisify(execFileCallback);
+const EXEC_TIMEOUT_MS = 5_000;
+/** The `@bakers-build/addon-ports` entry's `with.transport.with` for this transport — empty:
+ *  `cloudflared` is always resolved from `PATH` (BB-681 review I6/over-
+ *  engineering pass: no binary-path setting, per spec). */
+function validateSettings(settings) {
+    if (settings === undefined || settings === null)
+        return;
+    if (typeof settings !== 'object' || Object.keys(settings).length > 0) {
+        throw new Error("the @bakers-build/addon-ports entry's with.transport.with for 'cloudflare-quick' must be empty — cloudflared is resolved from PATH");
+    }
+}
+const DATA_FIELDS = [
+    'pid',
+    'exe',
+    'argv',
+    'uid',
+    'startTime',
+    'bootId',
+    'routeDir',
+    'generation',
+    'origin',
+];
+/** Allowlisted provider state for this transport — thrown, never silently
+ *  coerced, on anything outside this exact shape. */
+function validateData(data) {
+    if (typeof data !== 'object' || data === null) {
+        throw new Error('cloudflare-quick transport data must be an object');
+    }
+    const obj = data;
+    const unknownKeys = Object.keys(obj).filter((k) => !DATA_FIELDS.includes(k));
+    if (unknownKeys.length > 0) {
+        throw new Error(`cloudflare-quick transport data has unknown field(s): ${unknownKeys.join(', ')}`);
+    }
+}
+async function readProcIdentity(pid) {
+    try {
+        const [exeLink, cmdlineRaw, statusRaw, statRaw] = await Promise.all([
+            fsReadlink(`/proc/${pid}/exe`).catch(() => ''),
+            fsReadFile(`/proc/${pid}/cmdline`, 'utf8'),
+            fsReadFile(`/proc/${pid}/status`, 'utf8'),
+            fsReadFile(`/proc/${pid}/stat`, 'utf8'),
+        ]);
+        const argv = cmdlineRaw.split('\0').filter((s) => s.length > 0);
+        const uidMatch = /^Uid:\s+(\d+)/m.exec(statusRaw);
+        const uid = uidMatch?.[1] ? Number(uidMatch[1]) : -1;
+        const afterComm = statRaw.slice(statRaw.lastIndexOf(')') + 2);
+        const startTime = Number(afterComm.split(' ')[19]);
+        return {
+            pid,
+            exe: exeLink.replace(/ \(deleted\)$/, ''),
+            argv,
+            uid,
+            startTime: Number.isFinite(startTime) ? startTime : -1,
+            bootId: await readBootId(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+let cachedBootId = null;
+async function readBootId() {
+    if (cachedBootId)
+        return cachedBootId;
+    try {
+        const stat = await fsReadFile('/proc/stat', 'utf8');
+        const match = /^btime (\d+)/m.exec(stat);
+        cachedBootId = match?.[1] ?? 'unknown';
+    }
+    catch {
+        cachedBootId = 'unknown';
+    }
+    return cachedBootId;
+}
+async function listProcPids() {
+    const { readdir } = await import('node:fs/promises');
+    try {
+        const entries = await readdir('/proc');
+        return entries
+            .map((e) => Number(e))
+            .filter((n) => Number.isInteger(n) && n > 0);
+    }
+    catch {
+        return [];
+    }
+}
+async function findCloudflaredBin() {
+    try {
+        const { stdout } = await execFile('which', ['cloudflared'], {
+            timeout: EXEC_TIMEOUT_MS,
+        });
+        const path = stdout.trim();
+        return path || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Real I/O deps for the Quick transport. `routeDir` scanning here walks
+ * the WHOLE `/proc` table, which is fine at the process counts this addon
+ * deals with (a handful of routes per machine) — a targeted index would be
+ * the upgrade if that stops being true.
+ * ponytail: full /proc scan per reconcile call, index by routeDir if this
+ * ever needs to run against hundreds of routes.
+ */
+/** Exported for a real-process regression test (R4-M1/I2 ownership
+ *  filtering); not part of the package's public contract. */
+export function createNodeDeps() {
+    return {
+        spawn(bin, args, opts) {
+            const child = nodeSpawn(bin, args, {
+                cwd: opts.cwd,
+                env: opts.env,
+                detached: true,
+                stdio: 'ignore',
+            });
+            child.unref();
+            return { pid: child.pid ?? -1 };
+        },
+        findBinary: findCloudflaredBin,
+        now: () => Date.now(),
+        sleep: (ms, signal) => new Promise((resolve) => {
+            if (signal?.aborted)
+                return resolve();
+            const timer = setTimeout(resolve, ms);
+            signal?.addEventListener('abort', () => {
+                clearTimeout(timer);
+                resolve();
+            }, { once: true });
+        }),
+        readFile: async (path) => {
+            try {
+                // ponytail: reads the whole file each poll; bound by rotating per
+                // generation (never unbounded growth across restarts). A tail-only
+                // reader is the upgrade if a single generation's log gets huge.
+                return await fsReadFile(path, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        writeFile: async (path, data) => {
+            const fh = await fsOpen(path, 'w');
+            try {
+                await fh.writeFile(data);
+            }
+            finally {
+                await fh.close();
+            }
+        },
+        mkdir: async (path) => {
+            await fsMkdir(path, { recursive: true });
+        },
+        listOwnedProcesses: async (dir) => {
+            const pids = await listProcPids();
+            const owned = [];
+            const ownUid = process.getuid?.();
+            for (const pid of pids) {
+                const identity = await readProcIdentity(pid);
+                if (!identity || !isOwnedArgv(identity.argv, dir))
+                    continue;
+                // BB-681 review R4 (I2 remainder): the `--config <dir>/…` argv
+                // marker alone is a string any process could set — spoofable by
+                // design, never sufficient to adopt or kill something. Require it
+                // ALSO be a `cloudflared` executable run under our own uid before
+                // trusting it as a candidate; otherwise a lookalike process (wrong
+                // user, or not cloudflared at all) could be adopted as ours or,
+                // worse, killed as a mismatched orphan.
+                if (ownUid !== undefined && identity.uid !== ownUid)
+                    continue;
+                if (!identity.exe.toLowerCase().includes('cloudflared'))
+                    continue;
+                owned.push(identity);
+            }
+            return owned;
+        },
+        listGenerations: async (dir) => {
+            try {
+                const entries = await fsReaddir(dir, { withFileTypes: true });
+                return entries
+                    .filter((e) => e.isDirectory())
+                    .map((e) => /^gen-(\d+)$/.exec(e.name)?.[1])
+                    .filter((n) => n !== undefined)
+                    .map(Number);
+            }
+            catch {
+                return [];
+            }
+        },
+        getProcessIdentity: (pid) => readProcIdentity(pid),
+        kill: (pid) => {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                // already gone
+            }
+        },
+        waitExit: async (pid, timeoutMs, signal) => {
+            const deadline = Date.now() + timeoutMs;
+            for (;;) {
+                if (signal?.aborted)
+                    return false;
+                const identity = await readProcIdentity(pid);
+                if (!identity)
+                    return true;
+                if (Date.now() >= deadline)
+                    return false;
+                await new Promise((resolve) => setTimeout(resolve, 100));
+            }
+        },
+        bootId: readBootId,
+        env: process.env,
+        urlWaitMs: 15_000,
+        pollMs: 250,
+        killWaitMs: 5_000,
+    };
+}
+/**
+ * Default export factory consumed by `@bakers-build/addon-ports`'s
+ * `loadPortsTransport`. No `zone` — Quick has no fixed `<ticket>-<key>.
+ * <zone>` naming, unlike Named Cloudflare/frp.
+ */
+export default async function createTransport(settings, context) {
+    validateSettings(settings);
+    const deps = createNodeDeps();
+    const home = context.home;
+    return {
+        id: 'cloudflare-quick',
+        identity: 'cloudflare-quick',
+        validateData,
+        reconcile: (records, { signal, checkpoint }) => reconcileQuick(records, deps, home, { signal, checkpoint }),
+    };
+}

package/dist/src/quick.d.ts

@@ -0,0 +1,127 @@
+import type { TunnelDesiredRecord } from '@bakers-build/addon-ports/transport';
+/** The nonsecret identity fields a live/recorded process is matched on. A
+ *  bare PID is NEVER sufficient — PIDs get reused — so every comparison
+ *  checks all of these together. */
+export interface ManagedProcessIdentity {
+    readonly pid: number;
+    readonly exe: string;
+    readonly argv: readonly string[];
+    readonly uid: number;
+    readonly startTime: number;
+    /** Machine boot identity (boot time or boot id) — a PID+startTime pair
+     *  from BEFORE a machine reboot must never be mistaken for a match after
+     *  one, even if the raw numbers happen to coincide. */
+    readonly bootId: string;
+}
+export interface QuickOrigin {
+    readonly service: string;
+    readonly hostHeader?: string | undefined;
+    readonly insecureTls?: boolean | undefined;
+}
+/** The allowlisted provider state this transport persists in
+ *  `TunnelDesiredRecord.data` — validated by `validateData` in `index.ts`. */
+export interface QuickRouteData {
+    readonly pid: number;
+    readonly exe: string;
+    readonly argv: readonly string[];
+    readonly uid: number;
+    readonly startTime: number;
+    readonly bootId: string;
+    readonly routeDir: string;
+    readonly generation: number;
+    readonly origin: QuickOrigin;
+}
+export declare function originEquals(a: QuickOrigin, b: QuickOrigin): boolean;
+export declare function identityEquals(a: ManagedProcessIdentity, b: ManagedProcessIdentity): boolean;
+/** Deterministic, collision-proof per-route directory under `BB_HOME`:
+ *  worktree+ticket+key hashed together, so two different routes never share
+ *  a directory even when a key string repeats across worktrees/tickets. */
+export declare function routeDirFor(home: string, worktree: string, ticket: string, key: string): string;
+export declare function configPathFor(dir: string, generation: number): string;
+export declare function logPathFor(dir: string, generation: number): string;
+/** Pulls the generation number back out of a recorded `--config` path —
+ *  used to rediscover an adopted process's log without trusting any other
+ *  recorded state. */
+export declare function generationFromConfigPath(configPath: string): number | null;
+/** `--no-autoupdate`, explicit `--no-tls-verify=true|false` (never omitted
+ *  when it matters — absence must never silently disable verification),
+ *  and `--http-host-header` only when the rule carries one. `--logfile` is
+ *  REQUIRED, not cosmetic: `waitForUrl` reads the allocated URL only from
+ *  this exact generation's log file (BB-681 review C2 — cloudflared never
+ *  wrote one here before, so every `up` timed out). Built as an ARGV ARRAY —
+ *  never a shell string — so nothing in `origin.service`/`hostHeader` can be
+ *  interpreted as a shell metacharacter. */
+export declare function buildArgs(configPath: string, logPath: string, origin: QuickOrigin): string[];
+/** Reads back the origin `buildArgs` encoded into a live process's argv —
+ *  used to tell whether an adopted orphan (recognized only by its
+ *  `--config <dir>/…` marker) is actually serving the DESIRED origin before
+ *  trusting it (BB-681 review I2 remainder). `null` when the argv carries
+ *  no `--url` at all (not one of ours, or a shape this parser predates). */
+export declare function originFromArgv(argv: readonly string[]): QuickOrigin | null;
+/** Marker byte-for-byte present in every managed quick process's argv (the
+ *  `--config <routeDir>/gen-N/config.yaml` pair) — used both to recognize
+ *  OUR OWN processes during recovery and to tell the generic legacy-reap
+ *  scan (`addons/ports/src/deps-node.ts`) to leave them alone. */
+export declare function isOwnedArgv(argv: readonly string[], dir: string): boolean;
+export declare function parseLiveUrl(log: string): string | null;
+/** Strips cloudflared tunnel-selection/config/credential overrides the
+ *  PARENT environment might carry (`TUNNEL_*`, and cloudflared's own
+ *  config-path override) from the CHILD's env — `HOME` itself is NEVER
+ *  touched, so the child never redirects to a different (or the user's
+ *  real) cloudflared config/credentials on disk. */
+export declare function sanitizeEnv(parentEnv: Readonly<Record<string, string | undefined>>): Record<string, string>;
+export declare class AmbiguousOwnershipError extends Error {
+    constructor(dir: string, count: number);
+}
+export interface QuickDeps {
+    /** Spawn the real child — an argv ARRAY, never a shell string. */
+    spawn(bin: string, args: readonly string[], opts: {
+        readonly cwd: string;
+        readonly env: Readonly<Record<string, string>>;
+    }): {
+        readonly pid: number;
+    };
+    /** Resolved path to the `cloudflared` binary, or `null` if missing. */
+    findBinary(): Promise<string | null>;
+    now(): number;
+    /** Resolves early if `signal` aborts mid-sleep — never leaves an abort
+     *  waiting out the full duration. */
+    sleep(ms: number, signal?: AbortSignal): Promise<void>;
+    /** `null` when the file doesn't exist yet (not spawned, or log not yet
+     *  flushed) — never an error for this case. */
+    readFile(path: string): Promise<string | null>;
+    writeFile(path: string, data: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    /** Scans the WHOLE process table for anything whose argv carries this
+     *  route's `--config` marker (see `isOwnedArgv`) — the ground truth used
+     *  for crash recovery, independent of anything recorded in `data`. */
+    listOwnedProcesses(dir: string): Promise<readonly ManagedProcessIdentity[]>;
+    /** Generation numbers with a `gen-N` directory already on disk under
+     *  `dir` — read ONLY to pick the next unused generation (BB-681 review
+     *  N7); a route's directory outlives `down`, so `recorded` alone is not
+     *  enough to avoid reusing a previous life's generation/log. */
+    listGenerations(dir: string): Promise<readonly number[]>;
+    /** Direct re-check of a single remembered pid — `null` if gone or if the
+     *  pid now belongs to an unrelated process (PID reuse is the caller's
+     *  concern via `identityEquals`, not this method's). */
+    getProcessIdentity(pid: number): Promise<ManagedProcessIdentity | null>;
+    kill(pid: number): void;
+    /** Resolves once the pid is confirmed gone, or `signal` aborts/deadline
+     *  elapses — termination is only reported back once ACTUALLY confirmed,
+     *  never merely "signal sent". */
+    waitExit(pid: number, timeoutMs: number, signal?: AbortSignal): Promise<boolean>;
+    bootId(): Promise<string>;
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly urlWaitMs: number;
+    readonly pollMs: number;
+    readonly killWaitMs: number;
+}
+/** `PortsTransport.reconcile` for Quick: no DNS/ingress phase — each
+ *  record's remote state IS its own managed process. */
+export declare function reconcileQuick(records: readonly TunnelDesiredRecord[], deps: QuickDeps, home: string, context: {
+    readonly signal?: AbortSignal | undefined;
+    checkpoint(records: readonly TunnelDesiredRecord[]): Promise<void>;
+}): Promise<{
+    readonly records: readonly TunnelDesiredRecord[];
+    readonly ok: boolean;
+}>;

package/dist/src/quick.js

@@ -0,0 +1,474 @@
+// BB-681 Task 4 — Quick Tunnel as a `PortsTransport`: one managed
+// `cloudflared tunnel --url …` process PER ROUTE, no zone, no fixed name.
+// Unlike Named Cloudflare/frp (a fixed `<ticket>-<key>.<zone>` hostname),
+// Quick allocates its own ephemeral `*.trycloudflare.com` URL per process —
+// recreating a route MAY hand back a different URL, which is expected, not
+// a bug (see README).
+//
+// Every real I/O seam (spawn, process inspection, fs, kill, clock, sleep) is
+// injected via `QuickDeps`, exactly as `cloudflare.ts`'s `fetch` is injected
+// — this file is pure logic, unit-tested without touching `/proc` or
+// spawning anything real.
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { upsertRecord } from '@bakers-build/addon-ports/transport';
+export function originEquals(a, b) {
+    return (a.service === b.service &&
+        (a.hostHeader ?? undefined) === (b.hostHeader ?? undefined) &&
+        Boolean(a.insecureTls) === Boolean(b.insecureTls));
+}
+export function identityEquals(a, b) {
+    return (a.pid === b.pid &&
+        a.exe === b.exe &&
+        a.uid === b.uid &&
+        a.startTime === b.startTime &&
+        a.bootId === b.bootId &&
+        a.argv.length === b.argv.length &&
+        a.argv.every((v, i) => v === b.argv[i]));
+}
+/** Deterministic, collision-proof per-route directory under `BB_HOME`:
+ *  worktree+ticket+key hashed together, so two different routes never share
+ *  a directory even when a key string repeats across worktrees/tickets. */
+export function routeDirFor(home, worktree, ticket, key) {
+    const hash = createHash('sha256')
+        .update(`${worktree}\0${ticket}\0${key}`)
+        .digest('hex')
+        .slice(0, 20);
+    return join(home, 'ports', 'quick', hash);
+}
+export function configPathFor(dir, generation) {
+    return join(dir, `gen-${generation}`, 'config.yaml');
+}
+export function logPathFor(dir, generation) {
+    return join(dir, `gen-${generation}`, 'cloudflared.log');
+}
+/** Pulls the generation number back out of a recorded `--config` path —
+ *  used to rediscover an adopted process's log without trusting any other
+ *  recorded state. */
+export function generationFromConfigPath(configPath) {
+    const match = /gen-(\d+)[/\\]config\.yaml$/.exec(configPath);
+    if (!match)
+        return null;
+    const n = Number(match[1]);
+    return Number.isInteger(n) ? n : null;
+}
+/** `--no-autoupdate`, explicit `--no-tls-verify=true|false` (never omitted
+ *  when it matters — absence must never silently disable verification),
+ *  and `--http-host-header` only when the rule carries one. `--logfile` is
+ *  REQUIRED, not cosmetic: `waitForUrl` reads the allocated URL only from
+ *  this exact generation's log file (BB-681 review C2 — cloudflared never
+ *  wrote one here before, so every `up` timed out). Built as an ARGV ARRAY —
+ *  never a shell string — so nothing in `origin.service`/`hostHeader` can be
+ *  interpreted as a shell metacharacter. */
+export function buildArgs(configPath, logPath, origin) {
+    return [
+        '--config',
+        configPath,
+        '--no-autoupdate',
+        '--logfile',
+        logPath,
+        'tunnel',
+        '--url',
+        origin.service,
+        `--no-tls-verify=${origin.insecureTls ? 'true' : 'false'}`,
+        ...(origin.hostHeader ? ['--http-host-header', origin.hostHeader] : []),
+    ];
+}
+/** Reads back the origin `buildArgs` encoded into a live process's argv —
+ *  used to tell whether an adopted orphan (recognized only by its
+ *  `--config <dir>/…` marker) is actually serving the DESIRED origin before
+ *  trusting it (BB-681 review I2 remainder). `null` when the argv carries
+ *  no `--url` at all (not one of ours, or a shape this parser predates). */
+export function originFromArgv(argv) {
+    const urlIdx = argv.indexOf('--url');
+    if (urlIdx === -1 || urlIdx + 1 >= argv.length)
+        return null;
+    const service = argv[urlIdx + 1];
+    const insecureTls = argv.includes('--no-tls-verify=true');
+    const headerIdx = argv.indexOf('--http-host-header');
+    const hostHeader = headerIdx !== -1 && headerIdx + 1 < argv.length
+        ? argv[headerIdx + 1]
+        : undefined;
+    return { service, hostHeader, insecureTls };
+}
+/** Marker byte-for-byte present in every managed quick process's argv (the
+ *  `--config <routeDir>/gen-N/config.yaml` pair) — used both to recognize
+ *  OUR OWN processes during recovery and to tell the generic legacy-reap
+ *  scan (`addons/ports/src/deps-node.ts`) to leave them alone. */
+export function isOwnedArgv(argv, dir) {
+    const idx = argv.indexOf('--config');
+    if (idx === -1 || idx + 1 >= argv.length)
+        return false;
+    const configPath = argv[idx + 1];
+    return typeof configPath === 'string' && configPath.startsWith(`${dir}/`);
+}
+/** Only a validated `https://<label>.trycloudflare.com` origin is ever
+ *  trusted — log-spoofing resistance: any other URL-shaped text in the log
+ *  (an attacker-controlled upstream response line, a stray info message) is
+ *  rejected, never returned as the live URL. `api.trycloudflare.com` is
+ *  cloudflared's OWN allocation-API host, which appears in the log's error
+ *  lines (not an allocated tunnel) — explicitly excluded, never matched as a
+ *  live route (BB-681 review I4). */
+const TRYCLOUDFLARE_RE = /\bhttps:\/\/(?!api\.)[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.trycloudflare\.com\b/i;
+export function parseLiveUrl(log) {
+    const match = TRYCLOUDFLARE_RE.exec(log);
+    return match ? match[0] : null;
+}
+/** Strips cloudflared tunnel-selection/config/credential overrides the
+ *  PARENT environment might carry (`TUNNEL_*`, and cloudflared's own
+ *  config-path override) from the CHILD's env — `HOME` itself is NEVER
+ *  touched, so the child never redirects to a different (or the user's
+ *  real) cloudflared config/credentials on disk. */
+export function sanitizeEnv(parentEnv) {
+    const out = {};
+    for (const [key, value] of Object.entries(parentEnv)) {
+        if (value === undefined)
+            continue;
+        if (/^TUNNEL_/i.test(key))
+            continue;
+        if (key === 'TUNNEL_ORIGIN_CERT' || key === 'CF_API_TOKEN')
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+export class AmbiguousOwnershipError extends Error {
+    constructor(dir, count) {
+        super(`ambiguous ownership for quick tunnel route '${dir}': ${count} candidate owned processes found — refusing to guess which is live (never killing or spawning alongside an ambiguous match)`);
+        this.name = 'AmbiguousOwnershipError';
+    }
+}
+function dataOf(record) {
+    return record.data;
+}
+/** Returns `true` only once the process is CONFIRMED gone (already gone, or
+ *  killed and `waitExit` confirmed it) — `false` when a kill was sent but
+ *  exit never confirmed within the deadline. BB-681 review I2 (remainder):
+ *  callers must not spawn a fresh generation while an old one might still be
+ *  alive, racing to route the same key. */
+async function terminateOwned(deps, identity, signal) {
+    // Revalidate immediately before signalling — never trust a remembered pid
+    // alone; a PID-reuse scenario (same number, different identity) must read
+    // as "already gone", never as permission to kill whatever runs there now.
+    const fresh = await deps.getProcessIdentity(identity.pid);
+    if (!fresh || !identityEquals(fresh, identity))
+        return true;
+    deps.kill(identity.pid);
+    return deps.waitExit(identity.pid, deps.killWaitMs, signal);
+}
+/** Finds this route's single owned process, if any — the authoritative
+ *  ground truth crash recovery relies on (never just a recorded pid). */
+async function findOwned(deps, dir) {
+    const owned = await deps.listOwnedProcesses(dir);
+    if (owned.length > 1)
+        throw new AmbiguousOwnershipError(dir, owned.length);
+    return owned[0] ?? null;
+}
+async function waitForUrl(deps, logPath, signal) {
+    const deadline = deps.now() + deps.urlWaitMs;
+    for (;;) {
+        if (signal?.aborted)
+            return null;
+        const log = await deps.readFile(logPath);
+        if (log) {
+            const url = parseLiveUrl(log);
+            if (url)
+                return url;
+        }
+        if (deps.now() >= deadline)
+            return null;
+        await deps.sleep(deps.pollMs, signal);
+    }
+}
+async function spawnGeneration(deps, bin, dir, generation, origin) {
+    const genDir = join(dir, `gen-${generation}`);
+    await deps.mkdir(genDir);
+    const configPath = configPathFor(dir, generation);
+    // An empty `{}` config isolates the child from any user-level cloudflared
+    // config on disk — the only thing `--config` is here for.
+    await deps.writeFile(configPath, '{}\n');
+    const args = buildArgs(configPath, logPathFor(dir, generation), origin);
+    const env = sanitizeEnv(deps.env);
+    const child = deps.spawn(bin, args, { cwd: genDir, env });
+    const identity = await deps.getProcessIdentity(child.pid);
+    const bootId = await deps.bootId();
+    if (!identity) {
+        // The process already exited before we could even inspect it.
+        return {
+            pid: child.pid,
+            exe: bin,
+            argv: args,
+            uid: -1,
+            startTime: -1,
+            bootId,
+            routeDir: dir,
+            generation,
+            origin,
+        };
+    }
+    return { ...identity, routeDir: dir, generation, origin };
+}
+async function reconcilePresent(record, deps, home, context) {
+    const dir = routeDirFor(home, record.worktree, record.ticket, record.key);
+    const origin = {
+        service: record.service,
+        hostHeader: record.hostHeader,
+        insecureTls: record.insecureTls,
+    };
+    const recorded = dataOf(record);
+    // Direct re-check of the REMEMBERED pid, never a bare PID match: a UID
+    // mismatch or PID reuse (same number, different exe/startTime/bootId)
+    // means the recorded pid is NOT ours any more — treated as "our process
+    // is gone", never as permission to touch whatever now runs there.
+    let liveRecorded = null;
+    if (recorded) {
+        const fresh = await deps.getProcessIdentity(recorded.pid);
+        if (fresh && identityEquals(fresh, recorded)) {
+            liveRecorded = fresh;
+            if (originEquals(recorded.origin, origin)) {
+                // Fast path: a live, matching, owned process — reuse it, never
+                // spawn a duplicate alongside it.
+                return { ...recorded, pid: fresh.pid };
+            }
+        }
+    }
+    if (liveRecorded) {
+        // Confirmed ours, but the origin changed — terminate before the new
+        // generation starts, so two processes never route the same key. An
+        // UNCONFIRMED termination must stop here, not fall through to spawn
+        // alongside a possibly still-live old process (BB-681 review I2).
+        const confirmed = await terminateOwned(deps, liveRecorded, context.signal);
+        if (!confirmed) {
+            return { error: 'termination of the previous process not yet confirmed' };
+        }
+    }
+    else {
+        // Either no recorded data at all (first-ever reconcile for this route,
+        // OR a crash before the very first checkpoint), or recorded data existed
+        // but its pid is gone/reused. BB-681 review I2: scan for an orphan
+        // bearing this route's marker in BOTH cases, not only the no-recorded
+        // one — a crash after checkpointing generation N+1 but before THAT
+        // process's own next reconcile leaves it running, unmatched by
+        // `recorded` (whose pid may since have been reused), and the old code
+        // spawned a second, duplicate-routing generation N+2 alongside it. An
+        // AMBIGUOUS match (more than one candidate) is an error state, never
+        // permission to kill or spawn alongside it — `findOwned` throws for
+        // that, and the caller surfaces it as a failed record.
+        const owned = await findOwned(deps, dir);
+        if (owned) {
+            const generation = generationFromConfigPath(owned.argv[owned.argv.indexOf('--config') + 1] ?? '');
+            // BB-681 review I2 (remainder): an orphan is recognized only by its
+            // `--config <dir>/…` marker, not by the ORIGIN it was actually
+            // launched with — adopting it unconditionally with the DESIRED origin
+            // would silently keep routing a stale service/host-header/TLS setting.
+            // Read the origin back out of its OWN argv and compare.
+            const ownedOrigin = originFromArgv(owned.argv);
+            const originMatches = ownedOrigin !== null && originEquals(ownedOrigin, origin);
+            if (originMatches) {
+                return {
+                    ...owned,
+                    routeDir: dir,
+                    generation: generation ?? 1,
+                    origin,
+                };
+            }
+            // A mismatched orphan must be terminated — CONFIRMED — before a fresh
+            // generation spawns, so two processes never route the same key.
+            const confirmed = await terminateOwned(deps, owned, context.signal);
+            if (!confirmed) {
+                return {
+                    error: 'termination of the previous process not yet confirmed',
+                };
+            }
+        }
+    }
+    const bin = await deps.findBinary();
+    if (!bin)
+        return { error: 'cloudflared binary not found' };
+    // BB-681 review N7: `recorded` is undefined both on a route's first-ever
+    // spawn AND after `down`/a timeout clears it — but the route DIRECTORY
+    // (hashed from worktree+ticket+key) is never deleted, so generation 1's
+    // log from a PREVIOUS life can still sit on disk. Starting from the
+    // highest generation actually present there (not just `recorded`) always
+    // lands on a brand-new, never-before-written directory, so `waitForUrl`
+    // can never read a dead generation's stale URL.
+    const existing = await deps.listGenerations(dir);
+    const highestOnDisk = existing.length > 0 ? Math.max(...existing) : 0;
+    const generation = Math.max(recorded?.generation ?? 0, highestOnDisk) + 1;
+    const spawned = await spawnGeneration(deps, bin, dir, generation, origin);
+    return spawned;
+}
+function recordWithData(record, data, patch) {
+    return {
+        ...record,
+        data: data,
+        ...patch,
+    };
+}
+async function reconcileOnePresent(record, deps, home, context, commit) {
+    let outcome;
+    try {
+        outcome = await reconcilePresent(record, deps, home, context);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const next = { ...record, applied: 'error', error: message };
+        return { record: next, ok: false };
+    }
+    if ('error' in outcome) {
+        const next = { ...record, applied: 'error', error: outcome.error };
+        return { record: next, ok: false };
+    }
+    const data = outcome;
+    // Checkpoint ownership BEFORE waiting for the URL — a crash between spawn
+    // and this point must never lose track of a process we just started.
+    const pending = recordWithData(record, data, {
+        applied: 'pending',
+        error: undefined,
+    });
+    try {
+        await commit(pending);
+    }
+    catch (err) {
+        // Checkpoint failure: the process (if freshly spawned) keeps running
+        // unkilled — the next reconcile's routeDir scan will find and adopt it.
+        // Report this attempt as failed without touching the process.
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            record: { ...record, applied: 'error', error: message },
+            ok: false,
+        };
+    }
+    // Only trust the PREVIOUSLY recorded URL when this is the exact same
+    // generation/pid as before (the fast-path reuse case) — a fresh spawn
+    // (even one whose desired origin happens to equal itself, which is
+    // tautological) always gets its URL re-read from ITS OWN generation's log.
+    const recordedBefore = dataOf(record);
+    const sameGeneration = recordedBefore !== undefined &&
+        recordedBefore.pid === data.pid &&
+        recordedBefore.generation === data.generation &&
+        recordedBefore.routeDir === data.routeDir;
+    const url = sameGeneration ? record.url : undefined;
+    const resolvedUrl = url ??
+        (await waitForUrl(deps, logPathFor(data.routeDir, data.generation), context.signal));
+    if (context.signal?.aborted && !resolvedUrl) {
+        // Aborted mid-wait: stop cleanly, don't terminate the legitimately
+        // started process, just report "not yet live" for this pass.
+        return { record: pending, ok: false };
+    }
+    if (!resolvedUrl) {
+        // Bounded timeout: terminate ONLY the process just established by THIS
+        // spawn — never an unrelated process.
+        const fresh = await deps.getProcessIdentity(data.pid);
+        if (fresh && identityEquals(fresh, data)) {
+            deps.kill(data.pid);
+            await deps.waitExit(data.pid, deps.killWaitMs, context.signal);
+        }
+        return {
+            record: {
+                ...record,
+                data: undefined,
+                applied: 'error',
+                error: 'timed out waiting for the Quick Tunnel URL',
+            },
+            ok: false,
+        };
+    }
+    return {
+        record: recordWithData(record, data, {
+            applied: 'applied',
+            error: undefined,
+            url: resolvedUrl,
+        }),
+        ok: true,
+    };
+}
+async function reconcileOneAbsent(record, deps, home, context) {
+    const dir = routeDirFor(home, record.worktree, record.ticket, record.key);
+    const recorded = dataOf(record);
+    let target = null;
+    if (recorded) {
+        // Direct re-check of the remembered pid — a UID mismatch/PID reuse
+        // reads as "already gone", never as permission to kill the impostor.
+        const fresh = await deps.getProcessIdentity(recorded.pid);
+        if (fresh && identityEquals(fresh, recorded))
+            target = fresh;
+    }
+    if (!target) {
+        // BB-681 review R4-M1: a crash between spawning a generation and
+        // checkpointing it left `recorded` stale (gone/reused pid) OR entirely
+        // absent — either way the route directory can still hold a live, owned
+        // orphan. Scanning only the no-`recorded` case let that orphan outlive
+        // a tombstone drop, keeping its tunnel publicly reachable with nothing
+        // left tracking it. Scan whenever the direct re-check didn't confirm a
+        // live owned process, not only when nothing was ever recorded.
+        try {
+            target = await findOwned(deps, dir);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                record: { ...record, applied: 'error', error: message },
+                ok: false,
+            };
+        }
+    }
+    if (target) {
+        await terminateOwned(deps, target, context.signal);
+        const stillThere = await deps.getProcessIdentity(target.pid);
+        if (stillThere && identityEquals(stillThere, target)) {
+            // Termination not yet confirmed — keep the tombstone, don't drop it.
+            return {
+                record: {
+                    ...record,
+                    applied: 'error',
+                    error: 'termination not yet confirmed',
+                },
+                ok: false,
+            };
+        }
+    }
+    // Confirmed gone (or never existed) — safe to drop the tombstone entirely.
+    return {
+        record: {
+            ...record,
+            desired: 'absent',
+            applied: 'applied',
+            data: undefined,
+        },
+        ok: true,
+    };
+}
+/** `PortsTransport.reconcile` for Quick: no DNS/ingress phase — each
+ *  record's remote state IS its own managed process. */
+export async function reconcileQuick(records, deps, home, context) {
+    let next = records;
+    let ok = true;
+    const commit = async (updated) => {
+        next = upsertRecord(next, updated);
+        await context.checkpoint(next);
+    };
+    for (const record of records) {
+        if (record.desired === 'present') {
+            const result = await reconcileOnePresent(record, deps, home, context, commit);
+            next = upsertRecord(next, result.record);
+            if (!result.ok)
+                ok = false;
+        }
+    }
+    const absentIds = [];
+    for (const record of next) {
+        if (record.desired !== 'absent')
+            continue;
+        const result = await reconcileOneAbsent(record, deps, home, context);
+        if (result.ok) {
+            absentIds.push(`${record.worktree}:${record.key}`);
+        }
+        else {
+            next = upsertRecord(next, result.record);
+            ok = false;
+        }
+    }
+    next = next.filter((r) => !(r.desired === 'absent' && absentIds.includes(`${r.worktree}:${r.key}`)));
+    return { records: next, ok };
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@bakers-build/addon-ports-cloudflare-quick",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.38",
+  "description": "bakers.build ports transport: one cloudflared Quick Tunnel process per route, with no fixed name/URL/uptime guarantee. Implements @bakers-build/addon-ports's PortsTransport contract.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/bakers-build/bakers-build.git",
+    "directory": "bakers-cli/addons/ports-cloudflare-quick"
+  },
+  "peerDependencies": {
+    "@bakers-build/addon-ports": "^0.1.0-next.38",
+    "@bakers-build/core": "^0.1.0-next.38"
+  }
+}