@bakers-build/addon-ports-frp 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-frp
 
-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 self-hosted frp (frpc) client over an operator-owned config, reconciled via its local admin API. 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/frp.d.ts

@@ -0,0 +1,92 @@
+import type { TunnelDesiredRecord } from '@bakers-build/addon-ports/transport';
+/** The `@bakers-build/addon-ports` entry's `with.transport.with` for this transport. */
+export interface FrpSettings {
+    readonly zone: string;
+    /** Absolute path to the operator-owned frpc client config (JSON). This
+     *  addon only READS and validates it — it never writes to it. */
+    readonly clientConfigPath: string;
+    readonly adminPort: number;
+    readonly adminUser: string;
+    readonly adminPassword: string;
+}
+export declare class FrpConfigError extends Error {
+    constructor(message: string);
+}
+export declare function validateSettings(settings: unknown): FrpSettings;
+/** The slice of the operator's frpc JSON config this addon actually reads.
+ *  ponytail: this is a PLAUSIBLE frpc 0.68.0 config shape built from the
+ *  public docs' field names (`serverAddr`/`serverPort`/`auth`/`user`/
+ *  `webServer`/`transport.tls`/`includes`) — not a verified real capture.
+ *  Upgrade path: swap in the real frpc config schema/types if frp ships
+ *  one, or once an operator confirms the exact shape in use. */
+export interface FrpClientConfig {
+    readonly serverAddr?: unknown;
+    readonly serverPort?: unknown;
+    readonly user?: unknown;
+    readonly auth?: {
+        readonly method?: unknown;
+    } | undefined;
+    readonly webServer?: {
+        readonly addr?: unknown;
+    } | undefined;
+    readonly transport?: {
+        readonly tls?: {
+            readonly enable?: unknown;
+            readonly trustedCaFile?: unknown;
+        } | undefined;
+    } | undefined;
+    readonly includes?: readonly unknown[] | undefined;
+    readonly proxies?: unknown;
+    readonly visitors?: unknown;
+    readonly store?: unknown;
+}
+/** The nonsecret canonical client identity: server + user + zone + the
+ *  config path itself (NOT its contents — token rotation inside the same
+ *  file must not change this, per Task 2's identity-change-safety rule). */
+export interface FrpClientIdentity {
+    readonly server: string;
+    readonly user: string;
+}
+/**
+ * Validate the operator's frpc config strictly (spec): admin API loopback
+ * only, a dedicated user/client identity, server address/port, auth
+ * present, EXPLICIT server-TLS verification (frp's default encryption alone
+ * is not identity verification), and EXACTLY ONE include — the absolute
+ * routes file path this addon owns. Any other shape — inline proxies,
+ * visitors, a store, extra/missing includes — is a hard, pre-mutation error.
+ */
+export declare function validateClientConfig(config: unknown, routesPath: string): FrpClientIdentity;
+/** frp client-plugin proxy shape this addon writes into routes.json — the
+ *  complete desired proxy list, no secrets. */
+export interface FrpProxy {
+    readonly name: string;
+    readonly type: 'http';
+    readonly customDomains: readonly [string];
+    readonly localIP?: string;
+    readonly localPort?: number;
+    readonly hostHeaderRewrite?: string;
+    readonly requestHeaders?: {
+        readonly set: Readonly<Record<string, string>>;
+    };
+    readonly plugin?: {
+        readonly type: 'http2https';
+        readonly localAddr: string;
+        readonly hostHeaderRewrite?: string;
+    };
+}
+export declare class FrpUnverifiedHttpsError extends FrpConfigError {
+    constructor(hostname: string | undefined);
+}
+/** The record's `direct` container origin as host + port, or `undefined`
+ *  when it has none. `direct` comes from persisted state, so anything but a
+ *  plain `http:` URL with a host is rejected rather than dialled. */
+export declare function directOrigin(record: TunnelDesiredRecord): {
+    readonly host: string;
+    readonly port: number;
+} | undefined;
+/**
+ * Pure translation: one `TunnelDesiredRecord` -> one frp proxy. Throws
+ * `FrpUnverifiedHttpsError` for an HTTPS origin whose verification was
+ * requested (insecureTls false/omitted) — never silently downgraded.
+ */
+export declare function toFrpProxy(record: TunnelDesiredRecord): FrpProxy;

package/dist/src/frp.js

@@ -0,0 +1,162 @@
+// BB-681 Task 3 — frp (frpc) as a `PortsTransport`. The frpc PROCESS is
+// operator-managed (same stance as Cloudflare's `cloudflared`): this package
+// never starts/stops it, only (a) validates the operator's own frpc config
+// is shaped the way this addon needs, (b) writes the ONE file it owns
+// (`<home>/frp/routes.json`, the config's sole `includes` entry) and (c)
+// drives the local admin API to reload + confirm.
+export class FrpConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FrpConfigError';
+    }
+}
+export function validateSettings(settings) {
+    if (typeof settings !== 'object' || settings === null) {
+        throw new FrpConfigError("the @bakers-build/addon-ports entry's with.transport.with for 'frp' must be an object with zone/clientConfigPath/adminPort/adminUser/adminPassword");
+    }
+    const obj = settings;
+    if (typeof obj.zone !== 'string' || obj.zone === '') {
+        throw new FrpConfigError("the @bakers-build/addon-ports entry's with.transport.with for 'frp' is missing: zone");
+    }
+    if (typeof obj.clientConfigPath !== 'string' ||
+        !obj.clientConfigPath.startsWith('/')) {
+        throw new FrpConfigError("the @bakers-build/addon-ports entry's with.transport.with for 'frp' requires an absolute 'clientConfigPath'");
+    }
+    if (typeof obj.adminPort !== 'number' || !Number.isInteger(obj.adminPort)) {
+        throw new FrpConfigError("the @bakers-build/addon-ports entry's with.transport.with for 'frp' requires an integer 'adminPort'");
+    }
+    if (typeof obj.adminUser !== 'string' || obj.adminUser === '') {
+        throw new FrpConfigError("the @bakers-build/addon-ports entry's with.transport.with for 'frp' is missing: adminUser");
+    }
+    if (typeof obj.adminPassword !== 'string' || obj.adminPassword === '') {
+        throw new FrpConfigError("the @bakers-build/addon-ports entry's with.transport.with for 'frp' is missing: adminPassword");
+    }
+    return {
+        zone: obj.zone,
+        clientConfigPath: obj.clientConfigPath,
+        adminPort: obj.adminPort,
+        adminUser: obj.adminUser,
+        adminPassword: obj.adminPassword,
+    };
+}
+/**
+ * Validate the operator's frpc config strictly (spec): admin API loopback
+ * only, a dedicated user/client identity, server address/port, auth
+ * present, EXPLICIT server-TLS verification (frp's default encryption alone
+ * is not identity verification), and EXACTLY ONE include — the absolute
+ * routes file path this addon owns. Any other shape — inline proxies,
+ * visitors, a store, extra/missing includes — is a hard, pre-mutation error.
+ */
+export function validateClientConfig(config, routesPath) {
+    if (typeof config !== 'object' || config === null) {
+        throw new FrpConfigError('frpc client config must be a JSON object');
+    }
+    const cfg = config;
+    if (cfg.proxies !== undefined) {
+        throw new FrpConfigError('frpc client config must not declare inline proxies — this addon owns routes.json exclusively');
+    }
+    if (cfg.visitors !== undefined) {
+        throw new FrpConfigError('frpc client config must not declare inline visitors');
+    }
+    if (cfg.store !== undefined) {
+        throw new FrpConfigError('frpc client config must not declare a store');
+    }
+    if (typeof cfg.serverAddr !== 'string' || cfg.serverAddr === '') {
+        throw new FrpConfigError('frpc client config is missing serverAddr');
+    }
+    if (typeof cfg.serverPort !== 'number') {
+        throw new FrpConfigError('frpc client config is missing serverPort');
+    }
+    if (typeof cfg.user !== 'string' || cfg.user === '') {
+        throw new FrpConfigError('frpc client config must declare a dedicated user/client identity');
+    }
+    if (typeof cfg.auth?.method !== 'string' || cfg.auth.method === '') {
+        throw new FrpConfigError('frpc client config must declare authentication');
+    }
+    if (cfg.webServer?.addr !== '127.0.0.1') {
+        throw new FrpConfigError('frpc admin service (webServer.addr) must bind 127.0.0.1 (loopback only)');
+    }
+    const tls = cfg.transport?.tls;
+    if (tls?.enable !== true ||
+        typeof tls.trustedCaFile !== 'string' ||
+        tls.trustedCaFile === '') {
+        throw new FrpConfigError('frpc client config must explicitly require TLS verification of the server (transport.tls.enable=true with a trustedCaFile) — encryption alone is not identity verification');
+    }
+    const includes = cfg.includes ?? [];
+    if (includes.length !== 1 || includes[0] !== routesPath) {
+        throw new FrpConfigError(`frpc client config must have EXACTLY ONE include, the routes file this addon owns (${routesPath})`);
+    }
+    return { server: `${cfg.serverAddr}:${cfg.serverPort}`, user: cfg.user };
+}
+export class FrpUnverifiedHttpsError extends FrpConfigError {
+    constructor(hostname) {
+        super(`${hostname ?? '(unknown route)'}: requests verified HTTPS origin proxying, but frp 0.68.0's http2https plugin unconditionally skips origin certificate verification — set insecureTls: true to accept that, or serve plain HTTP`);
+        this.name = 'FrpUnverifiedHttpsError';
+    }
+}
+/** The record's `direct` container origin as host + port, or `undefined`
+ *  when it has none. `direct` comes from persisted state, so anything but a
+ *  plain `http:` URL with a host is rejected rather than dialled. */
+export function directOrigin(record) {
+    if (record.direct === undefined)
+        return undefined;
+    let url;
+    try {
+        url = new URL(record.direct);
+    }
+    catch {
+        url = undefined;
+    }
+    if (url?.protocol !== 'http:' || url.hostname === '') {
+        throw new FrpConfigError(`${record.hostname ?? '(unknown route)'}: direct origin must be a plain http://<host>:<port> URL`);
+    }
+    return { host: url.hostname, port: Number(url.port || '80') };
+}
+/**
+ * Pure translation: one `TunnelDesiredRecord` -> one frp proxy. Throws
+ * `FrpUnverifiedHttpsError` for an HTTPS origin whose verification was
+ * requested (insecureTls false/omitted) — never silently downgraded.
+ */
+export function toFrpProxy(record) {
+    const name = `${record.ticket}-${record.key}`;
+    const hostname = record.hostname;
+    // A direct container origin skips the router entirely: no Host rewrite, so
+    // the app sees the public Host; frps terminates TLS, hence the forced proto.
+    const direct = directOrigin(record);
+    if (direct) {
+        return {
+            name,
+            type: 'http',
+            customDomains: [hostname],
+            localIP: direct.host,
+            localPort: direct.port,
+            requestHeaders: { set: { 'X-Forwarded-Proto': 'https' } },
+        };
+    }
+    const url = new URL(record.service);
+    if (url.protocol === 'https:') {
+        if (record.insecureTls !== true) {
+            throw new FrpUnverifiedHttpsError(hostname);
+        }
+        const port = url.port || '443';
+        return {
+            name,
+            type: 'http',
+            customDomains: [hostname],
+            plugin: {
+                type: 'http2https',
+                localAddr: `${url.hostname}:${port}`,
+                ...(record.hostHeader ? { hostHeaderRewrite: record.hostHeader } : {}),
+            },
+        };
+    }
+    const port = Number(url.port || '80');
+    return {
+        name,
+        type: 'http',
+        customDomains: [hostname],
+        localIP: url.hostname,
+        localPort: port,
+        ...(record.hostHeader ? { hostHeaderRewrite: record.hostHeader } : {}),
+    };
+}

package/dist/src/index.d.ts

@@ -0,0 +1,8 @@
+import type { PortsTransport } from '@bakers-build/addon-ports/transport';
+export type { FrpSettings } from './frp.js';
+export { FrpConfigError, FrpUnverifiedHttpsError, toFrpProxy } from './frp.js';
+export type { FrpDeps, FrpReconcileConfig } from './reconcile.js';
+export { reconcileFrp } from './reconcile.js';
+export default function createTransport(settings: unknown, context: {
+    readonly home: string;
+}): Promise<PortsTransport>;

package/dist/src/index.js

@@ -0,0 +1,83 @@
+// BB-681 Task 3 — frp as a `PortsTransport`, wired to real Node I/O. The
+// factory reads and strictly validates the operator's frpc config BEFORE
+// returning a transport (spec: reject before any mutation), then hands
+// `reconcileFrp` real fs/fetch/clock/delay seams.
+import { chmod, mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { createConnection } from 'node:net';
+import { join } from 'node:path';
+import { validateClientConfig, validateSettings, } from './frp.js';
+import { reconcileFrp, } from './reconcile.js';
+export { FrpConfigError, FrpUnverifiedHttpsError, toFrpProxy } from './frp.js';
+export { reconcileFrp } from './reconcile.js';
+const nodeFrpDeps = {
+    readFile: (path) => readFile(path, 'utf8'),
+    writeFile: async (path, data, mode) => {
+        await writeFile(path, data, { encoding: 'utf8', mode });
+        await chmod(path, mode);
+    },
+    rename: (from, to) => rename(from, to),
+    mkdir: async (path) => {
+        await mkdir(path, { recursive: true });
+    },
+    fetch: async (url, init) => {
+        const res = await fetch(url, init);
+        return { ok: res.ok, status: res.status, json: () => res.json() };
+    },
+    now: () => Date.now(),
+    delay: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    canConnect: (host, port, timeoutMs) => new Promise((resolve) => {
+        const socket = createConnection({ host, port, timeout: timeoutMs });
+        const done = (reachable) => {
+            socket.destroy();
+            resolve(reachable);
+        };
+        socket.once('connect', () => done(true));
+        socket.once('timeout', () => done(false));
+        socket.once('error', () => done(false));
+    }),
+};
+/** Allowlisted provider state for this transport: only the generation
+ *  fingerprint `reconcileFrp` uses for crash-recovery/foreign-file checks. */
+function validateData(data) {
+    if (typeof data !== 'object' || data === null) {
+        throw new Error('frp transport data must be an object');
+    }
+    const obj = data;
+    const keys = Object.keys(obj);
+    if (keys.some((k) => k !== 'generation')) {
+        throw new Error(`frp transport data has unknown field(s): ${keys.filter((k) => k !== 'generation').join(', ')}`);
+    }
+    if (obj.generation !== undefined && typeof obj.generation !== 'string') {
+        throw new Error('frp transport data.generation must be a string');
+    }
+}
+export default async function createTransport(settings, context) {
+    const cfg = validateSettings(settings);
+    const routesPath = join(context.home, 'frp', 'routes.json');
+    let rawConfig;
+    try {
+        rawConfig = JSON.parse(await nodeFrpDeps.readFile(cfg.clientConfigPath));
+    }
+    catch {
+        // BB-681 review M5: a fixed message, never the raw fs/JSON.parse
+        // error — that error can embed filesystem details (permissions, other
+        // paths probed) this client has no business repeating into CLI/inbox
+        // output. The configured path alone is enough for the operator to fix.
+        throw new Error(`frp transport cannot read or parse clientConfigPath '${cfg.clientConfigPath}' as JSON`);
+    }
+    const clientIdentity = validateClientConfig(rawConfig, routesPath);
+    const reconcileCfg = {
+        routesPath,
+        identity: `${cfg.clientConfigPath}/${clientIdentity.server}/${clientIdentity.user}/${cfg.zone}`,
+        adminBase: `http://127.0.0.1:${cfg.adminPort}`,
+        adminUser: cfg.adminUser,
+        adminPassword: cfg.adminPassword,
+    };
+    return {
+        id: 'frp',
+        identity: reconcileCfg.identity,
+        zone: cfg.zone,
+        validateData,
+        reconcile: (records, { checkpoint }) => reconcileFrp(records, reconcileCfg, nodeFrpDeps, { checkpoint }),
+    };
+}

package/dist/src/reconcile.d.ts

@@ -0,0 +1,46 @@
+import type { TunnelDesiredRecord } from '@bakers-build/addon-ports/transport';
+import { type FrpProxy } from './frp.js';
+/** The injectable seams (TDD deps pattern, matching `addon-ports-cloudflare`'s
+ *  `CloudflareDeps` / `addon-ports`'s `TunnelStateDeps`): fs, fetch, clock,
+ *  delay — nothing here calls `node:fs`/`fetch`/`setTimeout` directly. */
+export interface FrpDeps {
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, data: string, mode: number): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    mkdir(path: string): Promise<void>;
+    fetch(url: string, init: {
+        readonly method: string;
+        readonly headers: Readonly<Record<string, string>>;
+    }): Promise<{
+        readonly ok: boolean;
+        readonly status: number;
+        json(): Promise<unknown>;
+    }>;
+    now(): number;
+    delay(ms: number): Promise<void>;
+    /** Bounded TCP connect — can this host reach a container IP at all? */
+    canConnect(host: string, port: number, timeoutMs: number): Promise<boolean>;
+}
+export interface FrpReconcileConfig {
+    readonly routesPath: string;
+    readonly identity: string;
+    readonly adminBase: string;
+    readonly adminUser: string;
+    readonly adminPassword: string;
+    /** Bounded status-poll deadline/interval — never an unbounded wait. */
+    readonly pollTimeoutMs?: number;
+    readonly pollIntervalMs?: number;
+}
+/** Deterministic fingerprint of (identity, desired proxy set) — the
+ *  ownership marker written into routes.json alongside the content it
+ *  describes, so a later reconcile can tell "this generation" apart from a
+ *  foreign file without needing a lock held across process restarts.
+ *  ponytail: content hash, not a counter — simplest thing that is stable
+ *  for an unchanged desired set and changes whenever it doesn't. */
+export declare function computeGeneration(identity: string, proxies: readonly FrpProxy[]): string;
+export declare function reconcileFrp(records: readonly TunnelDesiredRecord[], cfg: FrpReconcileConfig, deps: FrpDeps, context: {
+    checkpoint(records: readonly TunnelDesiredRecord[]): Promise<void>;
+}): Promise<{
+    readonly records: readonly TunnelDesiredRecord[];
+    readonly ok: boolean;
+}>;

package/dist/src/reconcile.js

@@ -0,0 +1,311 @@
+// BB-681 Task 3 — `PortsTransport.reconcile` for frp: write the complete
+// desired proxy list to the ONE file this addon owns (`routes.json`), then
+// drive the local admin API (reload, then poll status) until every intended
+// proxy is confirmed running/absent. Desired intent stays `pending` until
+// that full confirmation (spec) — a reload returning HTTP 200 is never
+// treated as success by itself.
+import { createHash, randomUUID } from 'node:crypto';
+import { upsertRecord } from '@bakers-build/addon-ports/transport';
+import { directOrigin, toFrpProxy } from './frp.js';
+const DIRECT_PROBE_TIMEOUT_MS = 1500;
+function flattenStatus(body) {
+    const byName = new Map();
+    for (const rows of Object.values(body)) {
+        for (const row of rows ?? [])
+            byName.set(row.name, row.status);
+    }
+    return byName;
+}
+/** Deterministic fingerprint of (identity, desired proxy set) — the
+ *  ownership marker written into routes.json alongside the content it
+ *  describes, so a later reconcile can tell "this generation" apart from a
+ *  foreign file without needing a lock held across process restarts.
+ *  ponytail: content hash, not a counter — simplest thing that is stable
+ *  for an unchanged desired set and changes whenever it doesn't. */
+export function computeGeneration(identity, proxies) {
+    const sorted = [...proxies].sort((a, b) => a.name.localeCompare(b.name));
+    return createHash('sha256')
+        .update(`${identity}\n${JSON.stringify(sorted)}`)
+        .digest('hex')
+        .slice(0, 16);
+}
+function basicAuthHeader(user, password) {
+    return `Basic ${Buffer.from(`${user}:${password}`).toString('base64')}`;
+}
+async function readRoutesFile(path, deps) {
+    let raw;
+    try {
+        raw = await deps.readFile(path);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'ENOENT')
+            return { kind: 'absent' };
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: 'malformed' };
+    }
+    const proxies = parsed?.proxies;
+    if (!Array.isArray(proxies))
+        return { kind: 'malformed' };
+    // Exactly what this addon writes after its last route is gone: nothing to
+    // protect, so a new identity (e.g. after a zone change) may take it over.
+    if (proxies.length === 0 && Object.keys(parsed).length === 1) {
+        return { kind: 'absent' };
+    }
+    return { kind: 'ok', proxies: proxies };
+}
+async function writeRoutesFile(path, dir, content, deps) {
+    await deps.mkdir(dir);
+    const tmp = `${path}.${randomUUID()}.tmp`;
+    await deps.writeFile(tmp, `${JSON.stringify(content, null, 2)}\n`, 0o600);
+    await deps.rename(tmp, path);
+}
+function lastAcknowledgedGeneration(records) {
+    for (const r of records) {
+        const g = r.data?.generation;
+        if (typeof g === 'string')
+            return g;
+    }
+    return undefined;
+}
+export async function reconcileFrp(records, cfg, deps, context) {
+    let next = records;
+    let ok = true;
+    const active = next.filter((r) => r.desired === 'present');
+    // A tombstone that never had a route written (no `data.generation` ever
+    // recorded) has nothing to confirm removed — drop it immediately, same as
+    // `addon-ports-cloudflare`'s "no-op absent" handling.
+    const noOpAbsentKeys = new Set(next
+        .filter((r) => r.desired === 'absent' && typeof r.data?.generation !== 'string')
+        .map((r) => `${r.worktree}:${r.key}`));
+    next = next.filter((r) => !(r.desired === 'absent' && noOpAbsentKeys.has(`${r.worktree}:${r.key}`)));
+    const absentWithRoute = next.filter((r) => r.desired === 'absent');
+    if (active.length === 0 && absentWithRoute.length === 0) {
+        // Nothing to reconcile (every tombstone was a no-op) — no file write,
+        // no reload, no poll.
+        return { records: next, ok: true };
+    }
+    // 1) Translate every active record; a bad candidate (e.g. an unverified
+    // HTTPS origin) is excluded and marked 'error' — siblings still ride along
+    // (never truncate the whole file for one bad record).
+    const proxies = [];
+    const proxyByKey = new Map();
+    for (const record of active) {
+        try {
+            // No fallback to the router path: a host that cannot reach container
+            // IPs (Docker Desktop) gets an error instead of a dead route.
+            const direct = directOrigin(record);
+            if (direct &&
+                !(await deps.canConnect(direct.host, direct.port, DIRECT_PROBE_TIMEOUT_MS))) {
+                throw new Error(`${record.hostname}: direct container routing needs a host that reaches Docker container IPs (${direct.host}:${direct.port} is unreachable) — on macOS use OrbStack`);
+            }
+            const proxy = toFrpProxy(record);
+            proxies.push(proxy);
+            proxyByKey.set(`${record.worktree}:${record.key}`, proxy);
+        }
+        catch (err) {
+            ok = false;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'error',
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    if (active.length > 0 && proxies.length === 0) {
+        // Every candidate failed translation: nothing valid to submit. Preserve
+        // whatever routes.json currently holds — do not write an empty file.
+        return { records: next, ok };
+    }
+    const desiredGeneration = computeGeneration(cfg.identity, proxies);
+    const lastGeneration = lastAcknowledgedGeneration(records);
+    const dir = cfg.routesPath.slice(0, cfg.routesPath.lastIndexOf('/'));
+    const existing = await readRoutesFile(cfg.routesPath, deps);
+    // The file carries no identity/generation of its own (C3) — its content
+    // hash, folded with THIS client's identity, stands in for the stored
+    // fingerprint. A foreign file (wrong identity, or any content this client
+    // never wrote) hashes to neither the desired nor the last-acknowledged
+    // generation and is refused exactly as before. Unparseable/`proxies`-less
+    // content is ALWAYS foreign (N4) — never folded into that hash comparison,
+    // where it could coincidentally match a legitimately empty generation.
+    const existingGeneration = existing.kind === 'ok'
+        ? computeGeneration(cfg.identity, existing.proxies)
+        : undefined;
+    const isForeign = existing.kind === 'malformed' ||
+        (existing.kind === 'ok' &&
+            existingGeneration !== desiredGeneration &&
+            existingGeneration !== lastGeneration);
+    if (isForeign) {
+        // Foreign file (or one this client didn't write, or doesn't recognise
+        // from the last acknowledged/current generation) — refuse to clobber it.
+        ok = false;
+        const okKeys = new Set(proxyByKey.keys());
+        for (const record of active) {
+            const key = `${record.worktree}:${record.key}`;
+            if (!okKeys.has(key))
+                continue;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'error',
+                error: `${cfg.routesPath} does not match this client's identity/generation — refusing to overwrite a file it may not own`,
+            });
+        }
+        return { records: next, ok };
+    }
+    // 2) Write the complete desired set atomically (temp file + rename, 0600
+    // — same atomic-write idiom as `tunnel-state.ts`'s `writeMachineTunnelState`).
+    try {
+        await writeRoutesFile(cfg.routesPath, dir, { proxies }, deps);
+    }
+    catch (err) {
+        ok = false;
+        const message = err instanceof Error ? err.message : String(err);
+        for (const record of active) {
+            if (!proxyByKey.has(`${record.worktree}:${record.key}`))
+                continue;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'pending',
+                error: message,
+            });
+        }
+        return { records: next, ok };
+    }
+    // The file write succeeded: every submitted record carries this
+    // generation from now on, and stays `pending` until status-confirmed.
+    for (const record of active) {
+        if (!proxyByKey.has(`${record.worktree}:${record.key}`))
+            continue;
+        next = upsertRecord(next, {
+            ...record,
+            applied: 'pending',
+            error: undefined,
+            data: { generation: desiredGeneration },
+        });
+    }
+    // BB-681 review M5: an unhandled checkpoint failure used to throw
+    // straight through `bringUp` into an unhandled rejection at the CLI/inbox
+    // entry point, instead of reporting a normal failed-record result — the
+    // routes.json write above already succeeded, so the intent is durable on
+    // disk; only the durable ACKNOWLEDGEMENT of it failed here, same failure
+    // class as Quick's own checkpoint-failure handling.
+    try {
+        await context.checkpoint(next);
+    }
+    catch (err) {
+        ok = false;
+        const message = err instanceof Error ? err.message : String(err);
+        for (const record of active) {
+            if (!proxyByKey.has(`${record.worktree}:${record.key}`))
+                continue;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'error',
+                error: message,
+            });
+        }
+        return { records: next, ok };
+    }
+    // 3) Reload, then poll `/api/status` with a bounded deadline. A reload
+    // HTTP 200 is NOT success by itself — only a subsequent status poll that
+    // confirms every intended proxy running/absent marks intent applied.
+    const authHeader = basicAuthHeader(cfg.adminUser, cfg.adminPassword);
+    try {
+        const res = await deps.fetch(`${cfg.adminBase}/api/reload?strictConfig=true`, {
+            method: 'GET',
+            headers: { authorization: authHeader },
+        });
+        if (!res.ok)
+            throw new Error(`reload failed: HTTP ${res.status}`);
+    }
+    catch (err) {
+        ok = false;
+        const message = err instanceof Error ? err.message : String(err);
+        for (const record of active) {
+            if (!proxyByKey.has(`${record.worktree}:${record.key}`))
+                continue;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'pending',
+                error: message,
+            });
+        }
+        return { records: next, ok };
+    }
+    const pollTimeoutMs = cfg.pollTimeoutMs ?? 10_000;
+    const pollIntervalMs = cfg.pollIntervalMs ?? 500;
+    const deadline = deps.now() + pollTimeoutMs;
+    const wantRunningKeys = new Set(proxyByKey.keys());
+    const wantGoneNames = new Set(absentWithRoute.map((r) => `${r.ticket}-${r.key}`));
+    let statusByName = new Map();
+    for (;;) {
+        try {
+            const res = await deps.fetch(`${cfg.adminBase}/api/status`, {
+                method: 'GET',
+                headers: { authorization: authHeader },
+            });
+            if (res.ok)
+                statusByName = flattenStatus((await res.json()));
+        }
+        catch {
+            // A transient status-probe failure just means "not confirmed yet" —
+            // the bounded loop below decides when to give up, this never throws.
+        }
+        const allRunning = [...wantRunningKeys].every((key) => {
+            const proxy = proxyByKey.get(key);
+            return proxy !== undefined && statusByName.get(proxy.name) === 'running';
+        });
+        const allGone = [...wantGoneNames].every((name) => !statusByName.has(name));
+        if (allRunning && allGone)
+            break;
+        if (deps.now() >= deadline)
+            break;
+        await deps.delay(pollIntervalMs);
+    }
+    for (const record of active) {
+        const key = `${record.worktree}:${record.key}`;
+        const proxy = proxyByKey.get(key);
+        if (!proxy)
+            continue;
+        if (statusByName.get(proxy.name) === 'running') {
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'applied',
+                error: undefined,
+                url: `https://${record.hostname}`,
+                data: { generation: desiredGeneration },
+            });
+        }
+        else {
+            ok = false;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'pending',
+                error: 'proxy not confirmed running within deadline',
+                data: { generation: desiredGeneration },
+            });
+        }
+    }
+    for (const record of absentWithRoute) {
+        const name = `${record.ticket}-${record.key}`;
+        if (!statusByName.has(name)) {
+            // Confirmed gone — clear the tombstone entirely.
+            next = next.filter((r) => !(r.worktree === record.worktree && r.key === record.key));
+        }
+        else {
+            ok = false;
+            next = upsertRecord(next, {
+                ...record,
+                applied: 'pending',
+                error: 'proxy still reported running — removal not yet confirmed',
+            });
+        }
+    }
+    return { records: next, ok };
+}

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@bakers-build/addon-ports-frp",
-  "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: a self-hosted frp (frpc) client over an operator-owned config, reconciled via its local admin API. 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-frp"
+  },
+  "peerDependencies": {
+    "@bakers-build/addon-ports": "^0.1.0-next.38",
+    "@bakers-build/core": "^0.1.0-next.38"
+  }
+}