@mesh-tech/mesh-cli 0.1.0 → 0.12.0

package/dist/src/utils/temporal-codec.js

@@ -0,0 +1,319 @@
+/**
+ * Temporal payload decryption helpers for mesh CLI.
+ *
+ * Mirrors the AES-256-GCM codec in `@mesh-tech/app-kit/temporal-codec`. The CLI
+ * can't depend on app-kit directly because app-kit depends on mesh-cli — so
+ * the codec logic is intentionally duplicated here, kept small, and bounded
+ * to read-only decryption (the CLI never encrypts).
+ *
+ * Wire format (matches app-kit EncryptionCodec):
+ *   metadata["encoding"] = "binary/encrypted"
+ *   metadata["encryption-key-id"] = first 16 hex chars of SHA-256(encodingKey)
+ *   data = IV (12 bytes) || ciphertext || GCM auth tag (16 bytes)
+ *
+ * Decryption of `data` yields a serialized Temporal Payload protobuf, whose
+ * inner `encoding` metadata tells you how to interpret the inner bytes
+ * (`json/plain`, `binary/plain`, etc.). We hand-decode the Payload message
+ * (a trivial 2-field protobuf) instead of depending on `@temporalio/proto`,
+ * so the CLI stays dependency-clean and doesn't need a Temporal SDK peer.
+ */
+import { execFileSync } from "child_process";
+import { webcrypto as crypto } from "node:crypto";
+import { logSuccess, logWarn } from "./log.js";
+// ── Encoding key resolution ────────────────────────────────────────────────
+/**
+ * Read the Temporal encoding key from a Kubernetes secret in the given
+ * namespace. Returns `undefined` when kubectl is unavailable, the secret
+ * doesn't exist, or the caller isn't authenticated to the cluster.
+ *
+ * The K8s secret is preferred over Pulumi stack output because personal dev
+ * stacks ship a placeholder encoding key that cannot decrypt deployed
+ * payloads; the K8s secret is always authoritative for a given namespace.
+ *
+ * @param namespace - Kubernetes namespace matching the Temporal namespace
+ *                    (mesh apps use the same name for both).
+ */
+export function resolveTemporalEncodingKeyFromK8s(namespace) {
+    const secretName = `${namespace}-temporal-encoding-key`;
+    try {
+        const b64 = execFileSync("kubectl", [
+            "get",
+            "secret",
+            secretName,
+            "-n",
+            namespace,
+            "-o",
+            "jsonpath={.data.TEMPORAL_ENCODING_KEY}",
+        ], { encoding: "utf-8", timeout: 10_000, stdio: ["pipe", "pipe", "pipe"] }).trim();
+        if (!b64)
+            return undefined;
+        return Buffer.from(b64, "base64").toString("utf-8");
+    }
+    catch {
+        // kubectl missing, secret absent, or no cluster access — caller decides.
+        return undefined;
+    }
+}
+// ── AES-256-GCM decryption ─────────────────────────────────────────────────
+const ENCRYPTED_ENCODING = "binary/encrypted";
+const IV_LENGTH = 12;
+async function deriveKey(encodingKey) {
+    const keyData = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(encodingKey));
+    return crypto.subtle.importKey("raw", keyData, { name: "AES-GCM" }, false, ["decrypt"]);
+}
+async function aesGcmDecrypt(data, key) {
+    const iv = data.slice(0, IV_LENGTH);
+    const ciphertextWithTag = data.slice(IV_LENGTH);
+    const decrypted = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, ciphertextWithTag);
+    return new Uint8Array(decrypted);
+}
+/**
+ * Build a decrypter closure for the given encoding key.
+ */
+export async function createPayloadDecrypter(encodingKey) {
+    const key = await deriveKey(encodingKey);
+    return async (payload) => {
+        if (!payload?.metadata)
+            return null;
+        const encodingBytes = payload.metadata["encoding"];
+        if (!encodingBytes)
+            return null;
+        const encoding = new TextDecoder().decode(encodingBytes);
+        if (encoding !== ENCRYPTED_ENCODING)
+            return null;
+        if (!payload.data)
+            return "[encrypted payload missing data]";
+        let inner;
+        try {
+            const decrypted = await aesGcmDecrypt(payload.data, key);
+            inner = decodePayloadProtobuf(decrypted);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return `[undecryptable: ${msg}]`;
+        }
+        return decodeInnerPayload(inner);
+    };
+}
+/**
+ * Build a raw (Payload-in, Payload-out) decrypter for the given encoding key.
+ *
+ * This is the fixture-capture counterpart of {@link createPayloadDecrypter}:
+ * where that one renders a payload for human display (lossy — binary payloads
+ * become placeholders), this one returns the exact decrypted inner Payload so
+ * the bytes can be re-serialized into a replayable proto3-JSON history.
+ */
+export async function createRawPayloadDecrypter(encodingKey) {
+    const key = await deriveKey(encodingKey);
+    return async (payload) => {
+        if (!payload?.metadata)
+            return null;
+        const encodingBytes = payload.metadata["encoding"];
+        if (!encodingBytes)
+            return null;
+        const encoding = new TextDecoder().decode(encodingBytes);
+        if (encoding !== ENCRYPTED_ENCODING)
+            return null;
+        if (!payload.data) {
+            throw new Error("encrypted payload has no data to decrypt");
+        }
+        const decrypted = await aesGcmDecrypt(payload.data, key);
+        return decodePayloadProtobuf(decrypted);
+    };
+}
+// ── Hand-rolled Payload protobuf decoder ──────────────────────────────────
+//
+// temporal.api.common.v1.Payload has exactly two fields:
+//   message Payload {
+//     map<string, bytes> metadata = 1;  // field 1, length-delimited
+//     bytes data = 2;                   // field 2, length-delimited
+//   }
+// A protobuf `map<K, V>` is syntactic sugar for:
+//   repeated MapEntry { K key = 1; V value = 2; }
+// so each metadata entry is itself a length-delimited submessage with two
+// inner length-delimited fields.
+//
+// Decoding this by hand avoids pulling in `@temporalio/proto` as a peer dep.
+function readVarint(buf, pos) {
+    let value = 0;
+    let shift = 0;
+    let next = pos;
+    while (next < buf.length) {
+        const byte = buf[next];
+        next += 1;
+        value |= (byte & 0x7f) << shift;
+        if ((byte & 0x80) === 0)
+            return { value, next };
+        shift += 7;
+        if (shift >= 32)
+            throw new Error("varint too large");
+    }
+    throw new Error("truncated varint");
+}
+function readLengthDelimited(buf, pos) {
+    const { value: length, next: afterLen } = readVarint(buf, pos);
+    const end = afterLen + length;
+    if (end > buf.length)
+        throw new Error("truncated length-delimited field");
+    return { bytes: buf.slice(afterLen, end), next: end };
+}
+/**
+ * Decode a serialized `temporal.api.common.v1.Payload`.
+ *
+ * Unknown fields and wire types are skipped rather than throwing; we only
+ * need the two documented fields and Temporal's wire format is stable.
+ */
+function decodePayloadProtobuf(buf) {
+    const metadata = {};
+    let data;
+    let pos = 0;
+    while (pos < buf.length) {
+        const { value: tag, next: afterTag } = readVarint(buf, pos);
+        const fieldNumber = tag >>> 3;
+        const wireType = tag & 0x7;
+        pos = afterTag;
+        if (wireType === 2) {
+            const { bytes, next } = readLengthDelimited(buf, pos);
+            pos = next;
+            if (fieldNumber === 1) {
+                const entry = decodeMetadataEntry(bytes);
+                if (entry)
+                    metadata[entry.key] = entry.value;
+            }
+            else if (fieldNumber === 2) {
+                data = bytes;
+            }
+            // Other fields: ignore.
+        }
+        else if (wireType === 0) {
+            // varint — skip
+            pos = readVarint(buf, pos).next;
+        }
+        else if (wireType === 1) {
+            pos += 8; // fixed64
+        }
+        else if (wireType === 5) {
+            pos += 4; // fixed32
+        }
+        else {
+            throw new Error(`unsupported wire type ${wireType} at pos ${pos}`);
+        }
+    }
+    return { metadata, data: data ?? new Uint8Array(0) };
+}
+function decodeMetadataEntry(buf) {
+    let key;
+    let value;
+    let pos = 0;
+    while (pos < buf.length) {
+        const { value: tag, next: afterTag } = readVarint(buf, pos);
+        const fieldNumber = tag >>> 3;
+        const wireType = tag & 0x7;
+        pos = afterTag;
+        if (wireType !== 2) {
+            // Skip unsupported fields defensively.
+            if (wireType === 0)
+                pos = readVarint(buf, pos).next;
+            else if (wireType === 1)
+                pos += 8;
+            else if (wireType === 5)
+                pos += 4;
+            else
+                throw new Error(`unsupported metadata wire type ${wireType}`);
+            continue;
+        }
+        const { bytes, next } = readLengthDelimited(buf, pos);
+        pos = next;
+        if (fieldNumber === 1)
+            key = new TextDecoder().decode(bytes);
+        else if (fieldNumber === 2)
+            value = bytes;
+    }
+    if (key === undefined || value === undefined)
+        return null;
+    return { key, value };
+}
+/**
+ * Render a decrypted inner Payload as a human-readable string.
+ *
+ * Handles the common encodings Mesh workers emit:
+ *   - `json/plain` → pretty-printed JSON
+ *   - `binary/null` → literal `null`
+ *   - `binary/plain` → `[binary N bytes]`
+ *   - anything else → `[encoding=X, N bytes]`
+ */
+function decodeInnerPayload(payload) {
+    const meta = payload.metadata ?? {};
+    const encodingBytes = meta["encoding"];
+    const encoding = encodingBytes
+        ? new TextDecoder().decode(encodingBytes)
+        : "unknown";
+    const data = payload.data ?? new Uint8Array(0);
+    if (encoding === "binary/null")
+        return "null";
+    if (encoding === "json/plain") {
+        const text = new TextDecoder().decode(data);
+        try {
+            return JSON.stringify(JSON.parse(text), null, 2);
+        }
+        catch {
+            // Not valid JSON despite the encoding claim — surface the raw text so
+            // the debugger sees whatever garbage the worker actually wrote.
+            return text;
+        }
+    }
+    if (encoding === "binary/plain")
+        return `[binary, ${data.length} bytes]`;
+    return `[encoding=${encoding}, ${data.length} bytes]`;
+}
+// ── High-level helper ──────────────────────────────────────────────────────
+/**
+ * Resolve the Temporal encoding key for a namespace, logging where it came
+ * from (or why it couldn't be found). Prefer the K8s secret (authoritative for
+ * the namespace); fall back to an explicit TEMPORAL_ENCODING_KEY env var. The
+ * env fallback lets you decrypt a workflow's history OFFLINE — e.g. to
+ * reconstruct a conversation, or capture a replay fixture, whose worker can no
+ * longer replay it — using the key from a running `mesh dev` worker env when
+ * kubectl/cluster access isn't set up.
+ *
+ * Returns `undefined` when neither source yields a key.
+ */
+export function resolveEncodingKey(namespace) {
+    const fromK8s = resolveTemporalEncodingKeyFromK8s(namespace);
+    const key = fromK8s ?? process.env.TEMPORAL_ENCODING_KEY;
+    if (!key) {
+        logWarn(`Could not read TEMPORAL_ENCODING_KEY from secret ` +
+            `${namespace}/${namespace}-temporal-encoding-key, and TEMPORAL_ENCODING_KEY ` +
+            "is not set. Configure kubectl (namespace read " +
+            "access), or export TEMPORAL_ENCODING_KEY (e.g. from a `mesh dev` worker env).");
+        return undefined;
+    }
+    logSuccess(fromK8s
+        ? `Resolved encoding key from ${namespace}-temporal-encoding-key`
+        : "Resolved encoding key from TEMPORAL_ENCODING_KEY env");
+    return key;
+}
+/**
+ * Resolve the encoding key and build a decrypter for the given namespace.
+ * Logs a warning and returns `undefined` when the key can't be read; callers
+ * should fall back to printing events without payloads.
+ */
+export async function buildDecrypterForNamespace(namespace) {
+    const key = resolveEncodingKey(namespace);
+    if (!key)
+        return undefined;
+    return createPayloadDecrypter(key);
+}
+/**
+ * Resolve the encoding key and build a RAW (Payload-in/Payload-out) decrypter
+ * for the given namespace — used by `capture-history` to decrypt payloads back
+ * into replayable proto bytes. Returns `undefined` when the key can't be read;
+ * callers decide whether that's fatal.
+ */
+export async function buildRawDecrypterForNamespace(namespace) {
+    const key = resolveEncodingKey(namespace);
+    if (!key)
+        return undefined;
+    return createRawPayloadDecrypter(key);
+}
+//# sourceMappingURL=temporal-codec.js.map

package/dist/src/utils/temporal-codec.js.map

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

package/dist/src/utils/tunnel-ownership.d.ts

@@ -0,0 +1,130 @@
+/**
+ * Ownership contract for the tunnel runner (MESH-2407).
+ *
+ * Three silent-dead-tunnel incidents in ten days (MESH-2169, MESH-2014, the
+ * #2991 re-review) shared one enabler: readiness was inferred from "something
+ * accepts TCP on the port". That conflates LIVENESS (a listener exists) with
+ * OWNERSHIP (the listener is OUR runner, wired to OUR SOCKS upstream). This
+ * module is the ownership half of the contract:
+ *
+ *  - The runner that actually binds the forwarder ports writes a MANIFEST
+ *    (pid, process-group id, a per-run random token, a loopback control port)
+ *    and answers a one-shot control handshake with that token plus the ports
+ *    it is listening on — read from its in-process `net.Server`s, so the
+ *    answer can't be faked by a foreign listener and probing it opens no
+ *    SOCKS→VPC data connection.
+ *  - Callers verify ownership (manifest → live pid → control handshake →
+ *    token/socks-port/port-coverage match) instead of dialing ports. A port
+ *    that accepts TCP without passing the handshake is a SQUATTER and must be
+ *    a loud failure, never adopt-and-continue.
+ *  - Teardown signals process GROUPS recorded here (plus argv-discovered
+ *    runners), so no kill path can orphan a grandchild with ports still bound.
+ */
+import * as net from 'node:net';
+/** Written by the runner (the process that binds the ports) — never by callers. */
+export interface RunnerManifest {
+    tenant: string;
+    /** Pid of the runner process itself (the port owner), NOT its launcher. */
+    pid: number;
+    /** Process-group id — all teardown paths signal `-pgid`, never a bare pid. */
+    pgid: number;
+    /** Per-run random token; the control handshake must echo it. */
+    token: string;
+    /** Loopback port answering the one-shot ownership handshake. */
+    controlPort: number;
+    /** SOCKS port the runner's forwarders dial (must match the live daemon's). */
+    socksPort: number;
+    /** Forwarder ports the runner is responsible for. */
+    ports: number[];
+    startedAt: string;
+}
+/** What the runner's control endpoint answers with. */
+export interface ControlResponse {
+    token: string;
+    tenant: string;
+    pid: number;
+    socksPort: number;
+    /** Ports whose in-process `net.Server` is currently listening. */
+    listening: number[];
+    /** port → error code for forwarders that failed to bind (e.g. EADDRINUSE). */
+    bindErrors: Record<string, string>;
+}
+export declare function mintRunnerToken(): string;
+export declare function readRunnerManifest(file: string): RunnerManifest | null;
+export declare function writeRunnerManifest(file: string, manifest: RunnerManifest): void;
+/**
+ * Remove the manifest — but only if it is still OURS (`token` matches). A dying
+ * runner must not clobber the manifest of a newer runner that already replaced it.
+ * Omit `token` for teardown paths that own the whole tenant state.
+ */
+export declare function clearRunnerManifest(file: string, token?: string): void;
+/** Process-group id of a pid via `ps` (macOS/BSD); null when undiscoverable. */
+export declare function getProcessGroupId(pid: number): number | null;
+/**
+ * Pids of tunnel-runner processes for a tenant, parsed from `ps` output
+ * (`pid command` lines). Matches both `__run` and the legacy `__supervise`
+ * argv, and skips `exclude` (the calling process, when it IS the runner).
+ * Pure for unit tests; `discoverRunnerPids` feeds it live `ps` output.
+ */
+export declare function parseRunnerPidsFromPs(psOutput: string, tenant: string, exclude?: number): number[];
+/** Live argv discovery of runner pids for a tenant (empty when `ps` fails). */
+export declare function discoverRunnerPids(tenant: string, exclude?: number): number[];
+/**
+ * Start the runner's one-shot control endpoint on a loopback ephemeral port.
+ * Each connection gets one JSON line (the live payload) and is closed — no
+ * protocol state, nothing routable, and probing it touches no data plane.
+ */
+export declare function startControlServer(payload: () => ControlResponse): Promise<{
+    server: net.Server;
+    port: number;
+}>;
+/** Dial the control endpoint and parse its one-line JSON answer; null on any failure. */
+export declare function queryControl(port: number, timeoutMs?: number): Promise<ControlResponse | null>;
+export interface OwnershipCheck {
+    ok: boolean;
+    /** Machine-readable failure reason ("" when ok). */
+    reason: string;
+    /** The control answer, when the handshake got that far. */
+    resp?: ControlResponse;
+}
+/**
+ * The ownership handshake: manifest → live pid → control endpoint → token,
+ * SOCKS port, and port coverage all match. Anything less is NOT ours — the
+ * caller must treat an accepting-but-unowned port as a squatter, never reuse it.
+ */
+export declare function verifyRunnerOwnership(args: {
+    manifest: RunnerManifest | null;
+    expectedSocksPort: number;
+    expectedPorts: number[];
+    isPidAlive?: (pid: number) => boolean;
+    query?: (port: number) => Promise<ControlResponse | null>;
+}): Promise<OwnershipCheck>;
+/**
+ * Poll an ownership check until it passes or `deadlineMs` of wall-clock elapses;
+ * returns the last (failing) check otherwise. The deadline bounds TIME, not
+ * rounds — each check can itself cost up to the control-query timeout, so a
+ * round-counting loop would multiply the promised deadline several-fold.
+ * Retrying also matters for correctness, not just latency: two failure reasons
+ * are transient by design (`ports-not-listening:` while the runner's self-heal
+ * loop rebinds a forwarder, `no-control-answer` under accept-backlog pressure),
+ * and a single-shot sample of a healthy shared runner in one of those windows
+ * would tear it down for every concurrent session on the tenant (MESH-2014).
+ */
+export declare function pollOwnership(check: () => Promise<OwnershipCheck>, deadlineMs: number): Promise<OwnershipCheck>;
+/** Best-effort `lsof` description of what holds a port ("cmd (pid N)"); null if unknown. */
+export declare function describePortOwner(port: number): string | null;
+export interface SquattedPort {
+    port: number;
+    owner: string | null;
+}
+/**
+ * Of `ports`, the ones something is accepting TCP on. Called AFTER ownership
+ * failed / teardown ran, so every hit is a foreign or stale listener.
+ */
+export declare function findSquattedPorts(ports: number[], accepts: (port: number) => Promise<boolean>): Promise<SquattedPort[]>;
+/**
+ * The loud-failure text for a squatted tunnel port (`mesh dev doctor` style:
+ * what is wrong, why we refuse, exactly what to run). Never adopt-and-continue.
+ */
+export declare function buildSquatterError(tenant: string, squatted: SquattedPort[], detail?: string): string;
+//# sourceMappingURL=tunnel-ownership.d.ts.map

package/dist/src/utils/tunnel-ownership.d.ts.map

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