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

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
 
-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: a named Cloudflare Tunnel, reconciled via the Cloudflare API (DNS + ingress). 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/cloudflare.d.ts

@@ -0,0 +1,57 @@
+export interface CloudflareConfig {
+    readonly accountId: string;
+    readonly tunnelId: string;
+    readonly zoneId: string;
+    /** The bare zone hostname (e.g. `preview.example`) — carried here so
+     *  `index.ts` can surface it as `PortsTransport.zone` for hostname
+     *  construction; `cloudflare.ts`'s own API calls use `zoneId`, not this. */
+    readonly zone: string;
+    readonly apiToken: string;
+}
+export interface CfOriginRequest {
+    readonly httpHostHeader?: string;
+    readonly noTLSVerify?: boolean;
+}
+export interface CfIngressRule {
+    readonly hostname?: string;
+    readonly service: string;
+    readonly originRequest?: CfOriginRequest;
+}
+export interface CfFetchResponse {
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+}
+/** The HTTP seam, injected — a test fakes it, nothing here calls real `fetch`. */
+export interface CloudflareDeps {
+    fetch(url: string, init: {
+        readonly method: string;
+        readonly headers: Readonly<Record<string, string>>;
+        readonly body?: string;
+        readonly signal?: AbortSignal;
+    }): Promise<CfFetchResponse>;
+    readonly timeoutMs: number;
+}
+export declare class CloudflareApiError extends Error {
+    constructor(message: string);
+}
+/** The tunnel's currently uploaded ingress — read before replacing it, so an
+ *  unexpected unmanaged rule set can block the replace rather than vanish. */
+export declare function getIngressConfig(cfg: CloudflareConfig, deps: CloudflareDeps): Promise<{
+    readonly ingress: readonly CfIngressRule[];
+}>;
+/** Replace the WHOLE ingress list — Cloudflare's configuration API has no
+ *  partial update, so every call uploads the complete desired set. */
+export declare function putIngressConfig(cfg: CloudflareConfig, ingress: readonly CfIngressRule[], deps: CloudflareDeps): Promise<void>;
+export interface CfDnsRecord {
+    readonly id: string;
+    readonly content: string;
+}
+/** The exact-name CNAME, if any — used both to detect a foreign-owned
+ *  conflict and to adopt a record this tunnel already created. */
+export declare function findDnsRecord(cfg: CloudflareConfig, hostname: string, deps: CloudflareDeps): Promise<CfDnsRecord | null>;
+/** This tunnel's own target for a proxied CNAME — the only content a record
+ *  this reconciliation may delete is allowed to carry (ownership check). */
+export declare function tunnelCnameTarget(cfg: CloudflareConfig): string;
+export declare function createDnsRecord(cfg: CloudflareConfig, hostname: string, deps: CloudflareDeps): Promise<CfDnsRecord>;
+export declare function deleteDnsRecord(cfg: CloudflareConfig, recordId: string, deps: CloudflareDeps): Promise<void>;

package/dist/src/cloudflare.js

@@ -0,0 +1,92 @@
+// BB-676 Task 3, moved to its own package by BB-681 Task 2 — the
+// Cloudflare REST calls a reconciliation needs: upload the tunnel's ingress
+// configuration and own the proxied CNAME per hostname. See
+// https://developers.cloudflare.com/api/resources/zero_trust/subresources/tunnels/subresources/cloudflared/subresources/configurations/
+// and https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/create-remote-tunnel-api/
+// for the API shapes this wraps; locking/ownership/retry semantics are this
+// ticket's own decisions, not the API's.
+export class CloudflareApiError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'CloudflareApiError';
+    }
+}
+/** Replace the token with a fixed marker wherever it would otherwise leak
+ *  into a thrown message, a log line or a CLI argument. */
+function redact(token, message) {
+    return token ? message.split(token).join('[REDACTED]') : message;
+}
+async function call(cfg, deps, path, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.timeoutMs);
+    try {
+        let res;
+        try {
+            res = await deps.fetch(`https://api.cloudflare.com/client/v4${path}`, {
+                method: init.method,
+                headers: {
+                    authorization: `Bearer ${cfg.apiToken}`,
+                    'content-type': 'application/json',
+                },
+                ...(init.body !== undefined ? { body: JSON.stringify(init.body) } : {}),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new CloudflareApiError(redact(cfg.apiToken, `${init.method} ${path} failed: ${msg}`));
+        }
+        const body = (await res.json().catch(() => ({})));
+        if (!res.ok || body.success === false) {
+            const detail = (body.errors ?? []).map((e) => e.message).join('; ') ||
+                `HTTP ${res.status}`;
+            throw new CloudflareApiError(redact(cfg.apiToken, `${init.method} ${path} failed: ${detail}`));
+        }
+        return body.result;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** The tunnel's currently uploaded ingress — read before replacing it, so an
+ *  unexpected unmanaged rule set can block the replace rather than vanish. */
+export async function getIngressConfig(cfg, deps) {
+    const result = await call(cfg, deps, `/accounts/${cfg.accountId}/cfd_tunnel/${cfg.tunnelId}/configurations`, { method: 'GET' });
+    const config = result
+        ?.config;
+    return { ingress: config?.ingress ?? [] };
+}
+/** Replace the WHOLE ingress list — Cloudflare's configuration API has no
+ *  partial update, so every call uploads the complete desired set. */
+export async function putIngressConfig(cfg, ingress, deps) {
+    await call(cfg, deps, `/accounts/${cfg.accountId}/cfd_tunnel/${cfg.tunnelId}/configurations`, { method: 'PUT', body: { config: { ingress } } });
+}
+/** The exact-name CNAME, if any — used both to detect a foreign-owned
+ *  conflict and to adopt a record this tunnel already created. */
+export async function findDnsRecord(cfg, hostname, deps) {
+    const result = await call(cfg, deps, `/zones/${cfg.zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(hostname)}`, { method: 'GET' });
+    const records = result ?? [];
+    return records[0] ?? null;
+}
+/** This tunnel's own target for a proxied CNAME — the only content a record
+ *  this reconciliation may delete is allowed to carry (ownership check). */
+export function tunnelCnameTarget(cfg) {
+    return `${cfg.tunnelId}.cfargotunnel.com`;
+}
+export async function createDnsRecord(cfg, hostname, deps) {
+    const result = await call(cfg, deps, `/zones/${cfg.zoneId}/dns_records`, {
+        method: 'POST',
+        body: {
+            type: 'CNAME',
+            name: hostname,
+            content: tunnelCnameTarget(cfg),
+            proxied: true,
+        },
+    });
+    return result;
+}
+export async function deleteDnsRecord(cfg, recordId, deps) {
+    await call(cfg, deps, `/zones/${cfg.zoneId}/dns_records/${recordId}`, {
+        method: 'DELETE',
+    });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,19 @@
+import type { PortsTransport } from '@bakers-build/addon-ports/transport';
+export type { CloudflareConfig, CloudflareDeps } from './cloudflare.js';
+export { reconcileCloudflare } from './reconcile.js';
+/** The `@bakers-build/addon-ports` entry's `with.transport.with` for this transport. */
+export interface CloudflareSettings {
+    readonly accountId: string;
+    readonly tunnelId: string;
+    readonly zoneId: string;
+    readonly zone: string;
+    readonly apiToken: string;
+}
+/**
+ * Default export factory consumed by `@bakers-build/addon-ports`'s
+ * `loadPortsTransport`. `identity` deliberately excludes `apiToken` — a
+ * rotated token with the same account/tunnel/zone is NOT an identity change.
+ */
+export default function createTransport(settings: unknown, _context: {
+    readonly home: string;
+}): Promise<PortsTransport>;

package/dist/src/index.js

@@ -0,0 +1,69 @@
+// BB-681 Task 2 — Named Cloudflare as a `PortsTransport`. The connector
+// (`cloudflared` daemon) is operator-managed: this package never starts or
+// stops it, only reconciles DNS + ingress via the Cloudflare REST API.
+import { reconcileCloudflare } from './reconcile.js';
+export { reconcileCloudflare } from './reconcile.js';
+const REQUIRED_FIELDS = [
+    'accountId',
+    'tunnelId',
+    'zoneId',
+    'zone',
+    'apiToken',
+];
+function validateSettings(settings) {
+    if (typeof settings !== 'object' || settings === null) {
+        throw new Error("the @bakers-build/addon-ports entry's with.transport.with for 'cloudflare' must be an object with accountId/tunnelId/zoneId/zone/apiToken");
+    }
+    const obj = settings;
+    const missing = REQUIRED_FIELDS.filter((f) => typeof obj[f] !== 'string' || obj[f] === '');
+    if (missing.length > 0) {
+        throw new Error(`the @bakers-build/addon-ports entry's with.transport.with for 'cloudflare' is missing: ${missing.join(', ')}`);
+    }
+    return {
+        accountId: obj.accountId,
+        tunnelId: obj.tunnelId,
+        zoneId: obj.zoneId,
+        zone: obj.zone,
+        apiToken: obj.apiToken,
+    };
+}
+/** Real `fetch` — the only seam into the actual network, injected into
+ *  `reconcileCloudflare`/`cloudflare.ts`'s calls, never used directly by the
+ *  generic ports layer. */
+const nodeCloudflareDeps = {
+    fetch: async (url, init) => {
+        const res = await fetch(url, init);
+        return { ok: res.ok, status: res.status, json: () => res.json() };
+    },
+    timeoutMs: 10_000,
+};
+/** Allowlisted provider state for this transport: only a DNS record id. */
+function validateData(data) {
+    if (typeof data !== 'object' || data === null) {
+        throw new Error('cloudflare transport data must be an object');
+    }
+    const obj = data;
+    const keys = Object.keys(obj);
+    if (keys.some((k) => k !== 'dnsRecordId')) {
+        throw new Error(`cloudflare transport data has unknown field(s): ${keys.filter((k) => k !== 'dnsRecordId').join(', ')}`);
+    }
+    if (obj.dnsRecordId !== undefined && typeof obj.dnsRecordId !== 'string') {
+        throw new Error('cloudflare transport data.dnsRecordId must be a string');
+    }
+}
+/**
+ * Default export factory consumed by `@bakers-build/addon-ports`'s
+ * `loadPortsTransport`. `identity` deliberately excludes `apiToken` — a
+ * rotated token with the same account/tunnel/zone is NOT an identity change.
+ */
+export default async function createTransport(settings, _context) {
+    const cfg = validateSettings(settings);
+    const deps = nodeCloudflareDeps;
+    return {
+        id: 'cloudflare',
+        identity: `${cfg.accountId}/${cfg.tunnelId}/${cfg.zoneId}`,
+        zone: cfg.zone,
+        validateData,
+        reconcile: (records, { checkpoint }) => reconcileCloudflare(records, cfg, deps, { checkpoint }),
+    };
+}

package/dist/src/reconcile.d.ts

@@ -0,0 +1,10 @@
+import type { TunnelDesiredRecord } from '@bakers-build/addon-ports/transport';
+import { type CloudflareConfig, type CloudflareDeps } from './cloudflare.js';
+export interface ReconcileContext {
+    readonly signal?: AbortSignal;
+    checkpoint(records: readonly TunnelDesiredRecord[]): Promise<void>;
+}
+export declare function reconcileCloudflare(records: readonly TunnelDesiredRecord[], cfg: CloudflareConfig, deps: CloudflareDeps, context: ReconcileContext): Promise<{
+    readonly records: readonly TunnelDesiredRecord[];
+    readonly ok: boolean;
+}>;

package/dist/src/reconcile.js

@@ -0,0 +1,200 @@
+// BB-676 Task 3, generalized by BB-681 Task 2 into this package's own
+// `PortsTransport.reconcile` — DNS create/adopt + the complete ingress
+// upload, in the order a crash can recover from: an active record without
+// an owned CNAME gets one BEFORE the ingress that names its hostname is
+// uploaded (so a hostname never resolves before its route exists); a
+// reduced ingress is uploaded BEFORE an absent record's CNAME is deleted
+// (so the public URL stops routing before the DNS name that reached it
+// disappears). Returns the records with updated `applied`/`data.dnsRecordId`
+// /`error` — the generic layer (`tunnel-ops.ts`) persists them.
+import { upsertRecord } from '@bakers-build/addon-ports/transport';
+import { createDnsRecord, deleteDnsRecord, findDnsRecord, getIngressConfig, putIngressConfig, tunnelCnameTarget, } from './cloudflare.js';
+function dnsRecordId(record) {
+    const v = record.data?.dnsRecordId;
+    return typeof v === 'string' ? v : undefined;
+}
+function withDnsRecordId(record, id) {
+    return {
+        ...record,
+        data: id === undefined ? undefined : { dnsRecordId: id },
+    };
+}
+export async function reconcileCloudflare(records, cfg, deps, context) {
+    let next = records;
+    let ok = true;
+    const active = next.filter((r) => r.desired === 'present');
+    // Records whose DNS create/adopt itself failed (e.g. a foreign-owned exact
+    // name): they still ride along in the ingress upload below so one bad
+    // record can't drop its siblings, but they must not be reported `applied`
+    // just because the PUT happened to succeed — there's no DNS pointing at
+    // them. Track their ids to preserve that `error` through the PUT phase.
+    const dnsErrorIds = new Set();
+    for (const record of active) {
+        if (dnsRecordId(record))
+            continue;
+        try {
+            const existing = await findDnsRecord(cfg, record.hostname, deps);
+            if (existing && existing.content !== tunnelCnameTarget(cfg)) {
+                throw new Error(`${record.hostname} already has a DNS record this tunnel does not own`);
+            }
+            let id = existing?.id;
+            if (id === undefined) {
+                try {
+                    id = (await createDnsRecord(cfg, record.hostname, deps)).id;
+                }
+                catch (err) {
+                    // Uncertain create (e.g. the request succeeded remotely but the
+                    // response was ambiguous, or this is a retry after a timeout):
+                    // reconcile against the live state by exact hostname+content match
+                    // rather than assuming failure (which would otherwise risk a
+                    // duplicate record on the next attempt).
+                    const recheck = await findDnsRecord(cfg, record.hostname, deps).catch(() => null);
+                    if (recheck && recheck.content === tunnelCnameTarget(cfg)) {
+                        id = recheck.id;
+                    }
+                    else {
+                        throw err;
+                    }
+                }
+            }
+            next = upsertRecord(next, withDnsRecordId({ ...record, applied: 'pending', error: undefined }, id));
+            // Checkpoint DNS ownership immediately after acquiring/confirming it —
+            // don't wait until the whole reconcile finishes to record that this
+            // process now owns a DNS record (so a crash before the ingress PUT
+            // still leaves ownership discoverable on the next reconcile).
+            await context.checkpoint(next);
+        }
+        catch (err) {
+            ok = false;
+            dnsErrorIds.add(`${record.worktree}:${record.key}`);
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'error',
+                // CloudflareApiError messages are already redacted (`cloudflare.ts`);
+                // a non-Cloudflare error (e.g. a thrown plain Error) carries only its
+                // own message, never a raw fetch payload or token.
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    // The ingress is built from every `present` record, including ones whose
+    // DNS/apply state is `error` — otherwise one failed record would silently
+    // drop every other worktree's already-working route from the next upload.
+    const stillActive = next.filter((r) => r.desired === 'present');
+    // Remote config check first (I1): refuse to replace rules this tunnel does
+    // not own, rather than silently overwriting an out-of-band dashboard edit.
+    try {
+        const remote = await getIngressConfig(cfg, deps);
+        // Every hostname this tunnel identity has ever recorded is "managed",
+        // present or absent (N1): an `absent` record's hostname can still be in
+        // the remote ingress for one more reconcile (the PUT below removes it),
+        // and treating only `present` names as known wedges every later up/down
+        // the moment a single `down` runs, because the just-removed hostname then
+        // reads as a foreign unmanaged rule.
+        const expectedHostnames = new Set(next.map((r) => r.hostname).filter((h) => h !== undefined));
+        const unmanaged = remote.ingress.filter((rule) => typeof rule.hostname === 'string' &&
+            !expectedHostnames.has(rule.hostname));
+        if (unmanaged.length > 0) {
+            throw new Error(`refusing to replace unmanaged ingress rule(s): ${unmanaged.map((r) => r.hostname).join(', ')}`);
+        }
+    }
+    catch (err) {
+        ok = false;
+        const message = err instanceof Error ? err.message : String(err);
+        for (const r of stillActive) {
+            next = upsertRecord(next, { ...r, applied: 'pending', error: message });
+        }
+        return { records: next, ok };
+    }
+    // BB-681 Task 2 — translate the neutral record (`hostHeader`/
+    // `insecureTls`) into Cloudflare's own `originRequest` shape HERE, the only
+    // place that knows Cloudflare's field names. Omission of `insecureTls`
+    // NEVER disables TLS verification (absent/false means verified) — only an
+    // explicit `true` sets `noTLSVerify: true`.
+    const ingress = [
+        ...stillActive
+            .slice()
+            .sort((a, b) => (a.hostname ?? '').localeCompare(b.hostname ?? ''))
+            .map((r) => ({
+            ...(r.hostname !== undefined ? { hostname: r.hostname } : {}),
+            service: r.service,
+            ...(r.hostHeader || r.insecureTls
+                ? {
+                    originRequest: {
+                        ...(r.hostHeader ? { httpHostHeader: r.hostHeader } : {}),
+                        ...(r.insecureTls ? { noTLSVerify: true } : {}),
+                    },
+                }
+                : {}),
+        })),
+        { service: 'http_status:404' },
+    ];
+    try {
+        await putIngressConfig(cfg, ingress, deps);
+        for (const r of stillActive) {
+            if (dnsErrorIds.has(`${r.worktree}:${r.key}`))
+                continue;
+            // Applied only when BOTH the ingress route and the owned DNS record are
+            // confirmed — the DNS phase above already confirmed ownership for
+            // every id that isn't in `dnsErrorIds`.
+            next = upsertRecord(next, {
+                ...r,
+                applied: 'applied',
+                error: undefined,
+                url: r.hostname ? `https://${r.hostname}` : r.url,
+            });
+        }
+    }
+    catch (err) {
+        ok = false;
+        const message = err instanceof Error ? err.message : String(err);
+        for (const r of stillActive) {
+            // 'pending', not 'error': an upload failure is retryable and must not
+            // permanently drop this record from the next reconcile's ingress.
+            next = upsertRecord(next, { ...r, applied: 'pending', error: message });
+        }
+        // The ingress upload failed: nothing routes yet, so deleting an absent
+        // record's DNS now would be deleting the name for a route that is still
+        // live. Stop before the DNS-deletion phase.
+        return { records: next, ok };
+    }
+    // A desired-absent record with no DNS record ever created has nothing to
+    // delete remotely (M3) — drop its tombstone immediately rather than only
+    // ones that went through the create/adopt path.
+    const absent = next.filter((r) => r.desired === 'absent' && dnsRecordId(r));
+    const noOpAbsentIds = new Set(next
+        .filter((r) => r.desired === 'absent' && !dnsRecordId(r))
+        .map((r) => `${r.worktree}:${r.key}`));
+    next = next.filter((r) => !(r.desired === 'absent' && noOpAbsentIds.has(`${r.worktree}:${r.key}`)));
+    const kept = [];
+    for (const record of absent) {
+        const id = dnsRecordId(record);
+        try {
+            const existing = await findDnsRecord(cfg, record.hostname, deps);
+            if (existing &&
+                existing.id === id &&
+                existing.content === tunnelCnameTarget(cfg)) {
+                await deleteDnsRecord(cfg, id, deps);
+            }
+            // Tombstone cleared — drop it from the returned set entirely.
+            await context.checkpoint(next.filter((r) => `${r.worktree}:${r.key}` !== `${record.worktree}:${record.key}`));
+        }
+        catch (err) {
+            // Failed-cleanup tombstone: teardown partially failed, so this record
+            // stays (with its DNS id preserved) recording what's left to clean up,
+            // rather than the state losing track of it. Sibling records are
+            // unaffected — this loop never touches any key but its own.
+            ok = false;
+            kept.push({
+                ...record,
+                applied: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const absentIds = new Set(absent.map((r) => `${r.worktree}:${r.key}`));
+    next = next
+        .filter((r) => !(r.desired === 'absent' && absentIds.has(`${r.worktree}:${r.key}`)))
+        .concat(kept);
+    return { records: next, ok };
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@bakers-build/addon-ports-cloudflare",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.42",
+  "description": "bakers.build ports transport: a named Cloudflare Tunnel, reconciled via the Cloudflare API (DNS + ingress). 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"
+  },
+  "peerDependencies": {
+    "@bakers-build/addon-ports": "^0.1.0-next.42",
+    "@bakers-build/core": "^0.1.0-next.42"
+  }
+}