@mesh-tech/mesh-cli 0.20.2 → 0.20.3

package/dist/src/utils/temporal-auth.d.ts

@@ -1,43 +1,2 @@
-/**
- * Temporal auth resolution for the mesh CLI.
- *
- * Two responsibilities, kept together because they're always used as a pair:
- *   1. `resolveTemporalAuth` — discover the M2M client_credentials + Zitadel
- *      issuer/project for a tenant/env from SSM (with a kubectl pod-env fallback).
- *      This is what `mesh dev` injects into worker/service env.
- *   2. `acquireTemporalBearer` — exchange those credentials for a Zitadel Bearer
- *      JWT via the OAuth2 client_credentials grant, so CLI commands that talk to
- *      an auth-enforcing Temporal frontend (describe/history/terminate) can attach
- *      `authorization: Bearer <token>` gRPC metadata. Without it the server's
- *      MeshAuthorizer denies calls with "Request unauthorized".
- *
- * The token fetch is intentionally reimplemented here (not imported from
- * `@mesh-tech/app-kit`, which mirrors it) because app-kit *depends on* mesh-cli —
- * importing it back would create a dependency cycle.
- */
-/**
- * Discover Temporal M2M credentials + Zitadel issuer/project for a tenant/env.
- *
- * Returns an env-var-shaped record (TEMPORAL_AUTH_CLIENT_ID/SECRET,
- * ZITADEL_ISSUER, ZITADEL_PROJECT_ID, …). Missing pieces are simply absent —
- * callers decide whether what resolved is enough to mint a token.
- *
- * `platformName` keys the Zitadel issuer lookup and is the platform NAME
- * (e.g. "trabian"/"mesh"), NOT the app tenant — getting it wrong means the
- * issuer never resolves, so no Bearer, so Temporal denies with "Request
- * unauthorized".
- */
 export declare function resolveTemporalAuth(tenant: string, env: string, platformName?: string): Promise<Record<string, string>>;
-/**
- * Exchange resolved M2M credentials for a Zitadel Bearer access token via the
- * OAuth2 client_credentials grant. Reads from the passed record first, then the
- * ambient env (which `mesh dev` may already have populated).
- *
- * Returns `undefined` when credentials are incomplete — the caller then connects
- * unauthenticated (correct for local/non-enforcing Temporal servers).
- *
- * Mirrors `@mesh-tech/app-kit`'s `acquireToken` (kept in sync deliberately; see
- * the module doc for why it isn't imported).
- */
 export declare function acquireTemporalBearer(vars?: Record<string, string | undefined>): Promise<string | undefined>;
-//# sourceMappingURL=temporal-auth.d.ts.map

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

@@ -1,40 +1,9 @@
-/**
- * Temporal auth resolution for the mesh CLI.
- *
- * Two responsibilities, kept together because they're always used as a pair:
- *   1. `resolveTemporalAuth` — discover the M2M client_credentials + Zitadel
- *      issuer/project for a tenant/env from SSM (with a kubectl pod-env fallback).
- *      This is what `mesh dev` injects into worker/service env.
- *   2. `acquireTemporalBearer` — exchange those credentials for a Zitadel Bearer
- *      JWT via the OAuth2 client_credentials grant, so CLI commands that talk to
- *      an auth-enforcing Temporal frontend (describe/history/terminate) can attach
- *      `authorization: Bearer <token>` gRPC metadata. Without it the server's
- *      MeshAuthorizer denies calls with "Request unauthorized".
- *
- * The token fetch is intentionally reimplemented here (not imported from
- * `@mesh-tech/app-kit`, which mirrors it) because app-kit *depends on* mesh-cli —
- * importing it back would create a dependency cycle.
- */
 import { execFileSync } from "node:child_process";
 import { logSuccess, logWarn } from "./log.js";
-/**
- * Discover Temporal M2M credentials + Zitadel issuer/project for a tenant/env.
- *
- * Returns an env-var-shaped record (TEMPORAL_AUTH_CLIENT_ID/SECRET,
- * ZITADEL_ISSUER, ZITADEL_PROJECT_ID, …). Missing pieces are simply absent —
- * callers decide whether what resolved is enough to mint a token.
- *
- * `platformName` keys the Zitadel issuer lookup and is the platform NAME
- * (e.g. "trabian"/"mesh"), NOT the app tenant — getting it wrong means the
- * issuer never resolves, so no Bearer, so Temporal denies with "Request
- * unauthorized".
- */
 export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
     const { SSMClient, GetParameterCommand } = await import("@aws-sdk/client-ssm");
     const ssm = new SSMClient({ region: process.env.AWS_REGION || "us-east-2" });
     const results = {};
-    // Each SSM lookup is independent so a missing optional parameter
-    // (e.g. token-exchange-app) doesn't prevent other credentials from resolving.
     async function trySSM(name) {
         try {
             const resp = await ssm.send(new GetParameterCommand({ Name: name, WithDecryption: true }));
@@ -45,7 +14,6 @@ export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
         }
     }
     try {
-        // ── Scheme 1: Zitadel-managed per-tenant credentials ──
         const workerPath = `/mesh-platform/${tenant}/${env}/temporal/worker-service-account-key`;
         const exchangePath = `/mesh-platform/${tenant}/${env}/temporal/token-exchange-app`;
         const workerJson = await trySSM(workerPath);
@@ -54,15 +22,12 @@ export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
             results.TEMPORAL_AUTH_CLIENT_ID = worker.clientId;
             results.TEMPORAL_AUTH_CLIENT_SECRET = worker.clientSecret;
         }
-        // Token exchange app credentials (optional — not all tenants have this)
         const exchangeJson = await trySSM(exchangePath);
         if (exchangeJson) {
             const exchange = JSON.parse(exchangeJson);
             results.ZITADEL_TOKEN_EXCHANGE_CLIENT_ID = exchange.clientId;
             results.ZITADEL_TOKEN_EXCHANGE_CLIENT_SECRET = exchange.clientSecret;
         }
-        // Zitadel issuer URL and project ID from the PLATFORM's config, keyed by the
-        // platform NAME (not the app tenant, not a hardcoded "mesh").
         const platformJson = await trySSM(`/mesh-platform/${platformName}/${env}/platform/zitadel`);
         if (platformJson) {
             const platform = JSON.parse(platformJson);
@@ -71,7 +36,6 @@ export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
             if (platform.projectId)
                 results.ZITADEL_PROJECT_ID = platform.projectId;
         }
-        // ── Scheme 2: Legacy shared credentials (fallback) ──
         if (!results.TEMPORAL_AUTH_CLIENT_ID) {
             const legacyClientId = await trySSM("/platform/temporal/auth/CLIENT_ID");
             const legacyClientSecret = await trySSM("/platform/temporal/auth/CLIENT_SECRET");
@@ -80,7 +44,6 @@ export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
                 results.TEMPORAL_AUTH_CLIENT_SECRET = legacyClientSecret;
             }
         }
-        // ── Discover Zitadel config from Temporal server pods (final fallback) ──
         if (!results.ZITADEL_ISSUER) {
             try {
                 const podEnv = execFileSync("kubectl", [
@@ -127,17 +90,6 @@ export async function resolveTemporalAuth(tenant, env, platformName = tenant) {
     }
     return results;
 }
-/**
- * Exchange resolved M2M credentials for a Zitadel Bearer access token via the
- * OAuth2 client_credentials grant. Reads from the passed record first, then the
- * ambient env (which `mesh dev` may already have populated).
- *
- * Returns `undefined` when credentials are incomplete — the caller then connects
- * unauthenticated (correct for local/non-enforcing Temporal servers).
- *
- * Mirrors `@mesh-tech/app-kit`'s `acquireToken` (kept in sync deliberately; see
- * the module doc for why it isn't imported).
- */
 export async function acquireTemporalBearer(vars = {}) {
     const issuerUrl = vars.ZITADEL_ISSUER ?? process.env.ZITADEL_ISSUER;
     const projectId = vars.ZITADEL_PROJECT_ID ?? process.env.ZITADEL_PROJECT_ID;
@@ -149,9 +101,6 @@ export async function acquireTemporalBearer(vars = {}) {
     const scopes = ["openid"];
     if (projectId) {
         scopes.push(`urn:zitadel:iam:org:project:id:${projectId}:aud`);
-        // Request project roles in the token (MeshAuthorizer Path A). Same env gate
-        // as app-kit: skipping the roles scope falls back to client_id parsing
-        // (Path B), which currently also yields the reader bit.
         if (process.env.TEMPORAL_M2M_SKIP_ROLES_SCOPE !== "true") {
             scopes.push("urn:zitadel:iam:org:projects:roles");
         }
@@ -173,4 +122,3 @@ export async function acquireTemporalBearer(vars = {}) {
     const data = (await response.json());
     return data.access_token;
 }
-//# sourceMappingURL=temporal-auth.js.map

package/dist/src/utils/temporal-codec.d.ts

@@ -1,101 +1,12 @@
-/**
- * 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.
- */
-/**
- * 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 declare function resolveTemporalEncodingKeyFromK8s(namespace: string): string | undefined;
-/**
- * Minimal shape of a Temporal Payload we care about.
- * Matches `temporal.api.common.v1.Payload` from @temporalio/proto but avoids
- * importing the type at module load time (so the CLI still loads without the
- * Temporal SDK installed).
- */
 export interface RawPayload {
     metadata?: Record<string, Uint8Array | null | undefined> | null;
     data?: Uint8Array | null;
 }
-/**
- * A decrypter closure bound to a specific encoding key. Returns a decoded
- * human-readable string for a single encrypted Payload, or `null` when the
- * payload wasn't encrypted and the caller should fall back to raw decoding.
- *
- * Error paths (`[undecryptable]`, `[decode error: ...]`) are returned as
- * strings rather than thrown — debugging a history is a best-effort read-only
- * operation and one bad payload shouldn't abort the whole dump.
- */
 export type PayloadDecrypter = (payload: RawPayload | null | undefined) => Promise<string | null>;
-/**
- * Build a decrypter closure for the given encoding key.
- */
 export declare function createPayloadDecrypter(encodingKey: string): Promise<PayloadDecrypter>;
-/**
- * A closure that decrypts a single encrypted Temporal Payload to its INNER
- * (plaintext) Payload — the `{ metadata, data }` the worker's codec wrapped —
- * rather than the human-readable string {@link PayloadDecrypter} produces.
- *
- * Returns `null` when the payload isn't encrypted (the caller leaves it as-is).
- * Unlike the display decrypter, decryption errors THROW here: a fixture with a
- * silently-mangled payload would replay wrong, so the caller must surface it.
- */
 export type RawPayloadDecrypter = (payload: RawPayload | null | undefined) => Promise<RawPayload | null>;
-/**
- * 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 declare function createRawPayloadDecrypter(encodingKey: string): Promise<RawPayloadDecrypter>;
-/**
- * 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 declare function resolveEncodingKey(namespace: string): string | undefined;
-/**
- * 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 declare function buildDecrypterForNamespace(namespace: string): Promise<PayloadDecrypter | undefined>;
-/**
- * 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 declare function buildRawDecrypterForNamespace(namespace: string): Promise<RawPayloadDecrypter | undefined>;
-//# sourceMappingURL=temporal-codec.d.ts.map

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

@@ -1,7 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/utils/temporal-codec.ts", "../../../src/utils/log.ts"],
-  "sourcesContent": ["/**\n * Temporal payload decryption helpers for mesh CLI.\n *\n * Mirrors the AES-256-GCM codec in `@mesh-tech/app-kit/temporal-codec`. The CLI\n * can't depend on app-kit directly because app-kit depends on mesh-cli \u2014 so\n * the codec logic is intentionally duplicated here, kept small, and bounded\n * to read-only decryption (the CLI never encrypts).\n *\n * Wire format (matches app-kit EncryptionCodec):\n *   metadata[\"encoding\"] = \"binary/encrypted\"\n *   metadata[\"encryption-key-id\"] = first 16 hex chars of SHA-256(encodingKey)\n *   data = IV (12 bytes) || ciphertext || GCM auth tag (16 bytes)\n *\n * Decryption of `data` yields a serialized Temporal Payload protobuf, whose\n * inner `encoding` metadata tells you how to interpret the inner bytes\n * (`json/plain`, `binary/plain`, etc.). We hand-decode the Payload message\n * (a trivial 2-field protobuf) instead of depending on `@temporalio/proto`,\n * so the CLI stays dependency-clean and doesn't need a Temporal SDK peer.\n */\n\nimport { execFileSync } from \"child_process\";\nimport { webcrypto as crypto } from \"node:crypto\";\nimport { logSuccess, logWarn } from \"./log.js\";\n\n// \u2500\u2500 Encoding key resolution \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Read the Temporal encoding key from a Kubernetes secret in the given\n * namespace. Returns `undefined` when kubectl is unavailable, the secret\n * doesn't exist, or the caller isn't authenticated to the cluster.\n *\n * The K8s secret is preferred over Pulumi stack output because personal dev\n * stacks ship a placeholder encoding key that cannot decrypt deployed\n * payloads; the K8s secret is always authoritative for a given namespace.\n *\n * @param namespace - Kubernetes namespace matching the Temporal namespace\n *                    (mesh apps use the same name for both).\n */\nexport function resolveTemporalEncodingKeyFromK8s(\n  namespace: string,\n): string | undefined {\n  const secretName = `${namespace}-temporal-encoding-key`;\n  try {\n    const b64 = execFileSync(\n      \"kubectl\",\n      [\n        \"get\",\n        \"secret\",\n        secretName,\n        \"-n\",\n        namespace,\n        \"-o\",\n        \"jsonpath={.data.TEMPORAL_ENCODING_KEY}\",\n      ],\n      { encoding: \"utf-8\", timeout: 10_000, stdio: [\"pipe\", \"pipe\", \"pipe\"] },\n    ).trim();\n\n    if (!b64) return undefined;\n    return Buffer.from(b64, \"base64\").toString(\"utf-8\");\n  } catch {\n    // kubectl missing, secret absent, or no cluster access \u2014 caller decides.\n    return undefined;\n  }\n}\n\n// \u2500\u2500 AES-256-GCM decryption \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst ENCRYPTED_ENCODING = \"binary/encrypted\";\nconst IV_LENGTH = 12;\n\nasync function deriveKey(encodingKey: string): Promise<crypto.CryptoKey> {\n  const keyData = await crypto.subtle.digest(\n    \"SHA-256\",\n    new TextEncoder().encode(encodingKey),\n  );\n  return crypto.subtle.importKey(\n    \"raw\",\n    keyData,\n    { name: \"AES-GCM\" },\n    false,\n    [\"decrypt\"],\n  );\n}\n\nasync function aesGcmDecrypt(\n  data: Uint8Array,\n  key: crypto.CryptoKey,\n): Promise<Uint8Array> {\n  const iv = data.slice(0, IV_LENGTH);\n  const ciphertextWithTag = data.slice(IV_LENGTH);\n  const decrypted = await crypto.subtle.decrypt(\n    { name: \"AES-GCM\", iv },\n    key,\n    ciphertextWithTag,\n  );\n  return new Uint8Array(decrypted);\n}\n\n// \u2500\u2500 Payload decoder \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Minimal shape of a Temporal Payload we care about.\n * Matches `temporal.api.common.v1.Payload` from @temporalio/proto but avoids\n * importing the type at module load time (so the CLI still loads without the\n * Temporal SDK installed).\n */\nexport interface RawPayload {\n  metadata?: Record<string, Uint8Array | null | undefined> | null;\n  data?: Uint8Array | null;\n}\n\n/**\n * A decrypter closure bound to a specific encoding key. Returns a decoded\n * human-readable string for a single encrypted Payload, or `null` when the\n * payload wasn't encrypted and the caller should fall back to raw decoding.\n *\n * Error paths (`[undecryptable]`, `[decode error: ...]`) are returned as\n * strings rather than thrown \u2014 debugging a history is a best-effort read-only\n * operation and one bad payload shouldn't abort the whole dump.\n */\nexport type PayloadDecrypter = (\n  payload: RawPayload | null | undefined,\n) => Promise<string | null>;\n\n/**\n * Build a decrypter closure for the given encoding key.\n */\nexport async function createPayloadDecrypter(\n  encodingKey: string,\n): Promise<PayloadDecrypter> {\n  const key = await deriveKey(encodingKey);\n\n  return async (payload) => {\n    if (!payload?.metadata) return null;\n\n    const encodingBytes = payload.metadata[\"encoding\"];\n    if (!encodingBytes) return null;\n    const encoding = new TextDecoder().decode(encodingBytes);\n    if (encoding !== ENCRYPTED_ENCODING) return null;\n\n    if (!payload.data) return \"[encrypted payload missing data]\";\n\n    let inner: RawPayload;\n    try {\n      const decrypted = await aesGcmDecrypt(payload.data, key);\n      inner = decodePayloadProtobuf(decrypted);\n    } catch (err) {\n      const msg = err instanceof Error ? err.message : String(err);\n      return `[undecryptable: ${msg}]`;\n    }\n\n    return decodeInnerPayload(inner);\n  };\n}\n\n/**\n * A closure that decrypts a single encrypted Temporal Payload to its INNER\n * (plaintext) Payload \u2014 the `{ metadata, data }` the worker's codec wrapped \u2014\n * rather than the human-readable string {@link PayloadDecrypter} produces.\n *\n * Returns `null` when the payload isn't encrypted (the caller leaves it as-is).\n * Unlike the display decrypter, decryption errors THROW here: a fixture with a\n * silently-mangled payload would replay wrong, so the caller must surface it.\n */\nexport type RawPayloadDecrypter = (\n  payload: RawPayload | null | undefined,\n) => Promise<RawPayload | null>;\n\n/**\n * Build a raw (Payload-in, Payload-out) decrypter for the given encoding key.\n *\n * This is the fixture-capture counterpart of {@link createPayloadDecrypter}:\n * where that one renders a payload for human display (lossy \u2014 binary payloads\n * become placeholders), this one returns the exact decrypted inner Payload so\n * the bytes can be re-serialized into a replayable proto3-JSON history.\n */\nexport async function createRawPayloadDecrypter(\n  encodingKey: string,\n): Promise<RawPayloadDecrypter> {\n  const key = await deriveKey(encodingKey);\n\n  return async (payload) => {\n    if (!payload?.metadata) return null;\n\n    const encodingBytes = payload.metadata[\"encoding\"];\n    if (!encodingBytes) return null;\n    const encoding = new TextDecoder().decode(encodingBytes);\n    if (encoding !== ENCRYPTED_ENCODING) return null;\n\n    if (!payload.data) {\n      throw new Error(\"encrypted payload has no data to decrypt\");\n    }\n\n    const decrypted = await aesGcmDecrypt(payload.data, key);\n    return decodePayloadProtobuf(decrypted);\n  };\n}\n\n// \u2500\u2500 Hand-rolled Payload protobuf decoder \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n//\n// temporal.api.common.v1.Payload has exactly two fields:\n//   message Payload {\n//     map<string, bytes> metadata = 1;  // field 1, length-delimited\n//     bytes data = 2;                   // field 2, length-delimited\n//   }\n// A protobuf `map<K, V>` is syntactic sugar for:\n//   repeated MapEntry { K key = 1; V value = 2; }\n// so each metadata entry is itself a length-delimited submessage with two\n// inner length-delimited fields.\n//\n// Decoding this by hand avoids pulling in `@temporalio/proto` as a peer dep.\n\nfunction readVarint(buf: Uint8Array, pos: number): { value: number; next: number } {\n  let value = 0;\n  let shift = 0;\n  let next = pos;\n  while (next < buf.length) {\n    const byte = buf[next]!;\n    next += 1;\n    value |= (byte & 0x7f) << shift;\n    if ((byte & 0x80) === 0) return { value, next };\n    shift += 7;\n    if (shift >= 32) throw new Error(\"varint too large\");\n  }\n  throw new Error(\"truncated varint\");\n}\n\nfunction readLengthDelimited(\n  buf: Uint8Array,\n  pos: number,\n): { bytes: Uint8Array; next: number } {\n  const { value: length, next: afterLen } = readVarint(buf, pos);\n  const end = afterLen + length;\n  if (end > buf.length) throw new Error(\"truncated length-delimited field\");\n  return { bytes: buf.slice(afterLen, end), next: end };\n}\n\n/**\n * Decode a serialized `temporal.api.common.v1.Payload`.\n *\n * Unknown fields and wire types are skipped rather than throwing; we only\n * need the two documented fields and Temporal's wire format is stable.\n */\nfunction decodePayloadProtobuf(buf: Uint8Array): RawPayload {\n  const metadata: Record<string, Uint8Array> = {};\n  let data: Uint8Array | undefined;\n  let pos = 0;\n\n  while (pos < buf.length) {\n    const { value: tag, next: afterTag } = readVarint(buf, pos);\n    const fieldNumber = tag >>> 3;\n    const wireType = tag & 0x7;\n    pos = afterTag;\n\n    if (wireType === 2) {\n      const { bytes, next } = readLengthDelimited(buf, pos);\n      pos = next;\n      if (fieldNumber === 1) {\n        const entry = decodeMetadataEntry(bytes);\n        if (entry) metadata[entry.key] = entry.value;\n      } else if (fieldNumber === 2) {\n        data = bytes;\n      }\n      // Other fields: ignore.\n    } else if (wireType === 0) {\n      // varint \u2014 skip\n      pos = readVarint(buf, pos).next;\n    } else if (wireType === 1) {\n      pos += 8; // fixed64\n    } else if (wireType === 5) {\n      pos += 4; // fixed32\n    } else {\n      throw new Error(`unsupported wire type ${wireType} at pos ${pos}`);\n    }\n  }\n\n  return { metadata, data: data ?? new Uint8Array(0) };\n}\n\nfunction decodeMetadataEntry(\n  buf: Uint8Array,\n): { key: string; value: Uint8Array } | null {\n  let key: string | undefined;\n  let value: Uint8Array | undefined;\n  let pos = 0;\n\n  while (pos < buf.length) {\n    const { value: tag, next: afterTag } = readVarint(buf, pos);\n    const fieldNumber = tag >>> 3;\n    const wireType = tag & 0x7;\n    pos = afterTag;\n    if (wireType !== 2) {\n      // Skip unsupported fields defensively.\n      if (wireType === 0) pos = readVarint(buf, pos).next;\n      else if (wireType === 1) pos += 8;\n      else if (wireType === 5) pos += 4;\n      else throw new Error(`unsupported metadata wire type ${wireType}`);\n      continue;\n    }\n    const { bytes, next } = readLengthDelimited(buf, pos);\n    pos = next;\n    if (fieldNumber === 1) key = new TextDecoder().decode(bytes);\n    else if (fieldNumber === 2) value = bytes;\n  }\n\n  if (key === undefined || value === undefined) return null;\n  return { key, value };\n}\n\n/**\n * Render a decrypted inner Payload as a human-readable string.\n *\n * Handles the common encodings Mesh workers emit:\n *   - `json/plain` \u2192 pretty-printed JSON\n *   - `binary/null` \u2192 literal `null`\n *   - `binary/plain` \u2192 `[binary N bytes]`\n *   - anything else \u2192 `[encoding=X, N bytes]`\n */\nfunction decodeInnerPayload(payload: RawPayload): string {\n  const meta = payload.metadata ?? {};\n  const encodingBytes = meta[\"encoding\"];\n  const encoding = encodingBytes\n    ? new TextDecoder().decode(encodingBytes)\n    : \"unknown\";\n  const data = payload.data ?? new Uint8Array(0);\n\n  if (encoding === \"binary/null\") return \"null\";\n  if (encoding === \"json/plain\") {\n    const text = new TextDecoder().decode(data);\n    try {\n      return JSON.stringify(JSON.parse(text), null, 2);\n    } catch {\n      // Not valid JSON despite the encoding claim \u2014 surface the raw text so\n      // the debugger sees whatever garbage the worker actually wrote.\n      return text;\n    }\n  }\n  if (encoding === \"binary/plain\") return `[binary, ${data.length} bytes]`;\n  return `[encoding=${encoding}, ${data.length} bytes]`;\n}\n\n// \u2500\u2500 High-level helper \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n/**\n * Resolve the Temporal encoding key for a namespace, logging where it came\n * from (or why it couldn't be found). Prefer the K8s secret (authoritative for\n * the namespace); fall back to an explicit TEMPORAL_ENCODING_KEY env var. The\n * env fallback lets you decrypt a workflow's history OFFLINE \u2014 e.g. to\n * reconstruct a conversation, or capture a replay fixture, whose worker can no\n * longer replay it \u2014 using the key from a running `mesh dev` worker env when\n * kubectl/cluster access isn't set up.\n *\n * Returns `undefined` when neither source yields a key.\n */\nexport function resolveEncodingKey(namespace: string): string | undefined {\n  const fromK8s = resolveTemporalEncodingKeyFromK8s(namespace);\n  const key = fromK8s ?? process.env.TEMPORAL_ENCODING_KEY;\n  if (!key) {\n    logWarn(\n      `Could not read TEMPORAL_ENCODING_KEY from secret ` +\n        `${namespace}/${namespace}-temporal-encoding-key, and TEMPORAL_ENCODING_KEY ` +\n        \"is not set. Configure kubectl (namespace read \" +\n        \"access), or export TEMPORAL_ENCODING_KEY (e.g. from a `mesh dev` worker env).\",\n    );\n    return undefined;\n  }\n  logSuccess(\n    fromK8s\n      ? `Resolved encoding key from ${namespace}-temporal-encoding-key`\n      : \"Resolved encoding key from TEMPORAL_ENCODING_KEY env\",\n  );\n  return key;\n}\n\n/**\n * Resolve the encoding key and build a decrypter for the given namespace.\n * Logs a warning and returns `undefined` when the key can't be read; callers\n * should fall back to printing events without payloads.\n */\nexport async function buildDecrypterForNamespace(\n  namespace: string,\n): Promise<PayloadDecrypter | undefined> {\n  const key = resolveEncodingKey(namespace);\n  if (!key) return undefined;\n  return createPayloadDecrypter(key);\n}\n\n/**\n * Resolve the encoding key and build a RAW (Payload-in/Payload-out) decrypter\n * for the given namespace \u2014 used by `capture-history` to decrypt payloads back\n * into replayable proto bytes. Returns `undefined` when the key can't be read;\n * callers decide whether that's fatal.\n */\nexport async function buildRawDecrypterForNamespace(\n  namespace: string,\n): Promise<RawPayloadDecrypter | undefined> {\n  const key = resolveEncodingKey(namespace);\n  if (!key) return undefined;\n  return createRawPayloadDecrypter(key);\n}\n", "/**\n * Logging utilities with colored output.\n *\n * Non-TTY streams (CI, agent runs, piped output) get an [HH:MM:SS] prefix on\n * every line so long quiet stretches are attributable after the fact\n * (MESH-2479); interactive terminals stay clean. Override with\n * MESH_LOG_TIMESTAMPS=1 (force on) / =0 (force off).\n */\n\nimport chalk from \"chalk\";\n\n/**\n * Pure prefix decision, exported for tests: timestamps when the env flag says\n * so, else whenever stderr is not a TTY.\n */\nexport function logPrefix(opts: {\n  isTTY: boolean;\n  envFlag: string | undefined;\n  now: Date;\n}): string {\n  const enabled = opts.envFlag === \"1\" || (opts.envFlag !== \"0\" && !opts.isTTY);\n  return enabled ? `[${opts.now.toISOString().slice(11, 19)}] ` : \"\";\n}\n\nfunction prefix(): string {\n  return chalk.dim(\n    logPrefix({\n      isTTY: !!process.stderr.isTTY,\n      envFlag: process.env.MESH_LOG_TIMESTAMPS,\n      now: new Date(),\n    }),\n  );\n}\n\nexport function logInfo(message: string): void {\n  console.error(prefix() + chalk.blue(\"\u2139\"), message);\n}\n\nexport function logSuccess(message: string): void {\n  console.error(prefix() + chalk.green(\"\u2713\"), message);\n}\n\nexport function logWarn(message: string): void {\n  console.error(prefix() + chalk.yellow(\"\u26A0\"), message);\n}\n\nexport function logError(message: string): void {\n  console.error(prefix() + chalk.red(\"\u2717\"), message);\n}\n\n/** Render elapsed milliseconds compactly: \"45s\", \"2m 30s\", \"1h 5m\". */\nexport function formatElapsed(ms: number): string {\n  const totalSec = Math.max(0, Math.round(ms / 1000));\n  const h = Math.floor(totalSec / 3600);\n  const m = Math.floor((totalSec % 3600) / 60);\n  const s = totalSec % 60;\n  if (h > 0) return `${h}h ${m}m`;\n  if (m > 0) return `${m}m ${s}s`;\n  return `${s}s`;\n}\n\n/**\n * Periodic \"still working\" line during a long silent operation (registry\n * fetches, image builds) so a non-TTY first run never sits at 0 bytes of\n * output for minutes (MESH-2479). `touch()` marks recent real output, which\n * suppresses the next beat \u2014 the heartbeat only fills silence.\n */\nexport function startHeartbeat(\n  label: string,\n  intervalMs = 15_000,\n): { stop: () => void; touch: () => void } {\n  const startedAt = Date.now();\n  let lastOutputAt = startedAt;\n  const timer = setInterval(() => {\n    if (Date.now() - lastOutputAt < intervalMs) return;\n    logInfo(`\u2026 still working: ${label} (${formatElapsed(Date.now() - startedAt)} elapsed)`);\n  }, intervalMs);\n  timer.unref?.();\n  return {\n    stop: () => clearInterval(timer),\n    touch: () => {\n      lastOutputAt = Date.now();\n    },\n  };\n}\n"],
   "mappings": "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",
   "names": []
 }

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

@@ -1,97 +1,39 @@
-/**
- * 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;
@@ -99,32 +41,11 @@ export declare function verifyRunnerOwnership(args: {
     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.js

@@ -1,25 +1,3 @@
-/**
- * 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 crypto from 'node:crypto';
 import * as fs from 'node:fs';
 import * as net from 'node:net';
@@ -42,11 +20,6 @@ export function writeRunnerManifest(file, manifest) {
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.writeFileSync(file, JSON.stringify(manifest, null, 2), { mode: 0o600 });
 }
-/**
- * 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 function clearRunnerManifest(file, token) {
     if (token !== undefined && readRunnerManifest(file)?.token !== token)
         return;
@@ -54,10 +27,8 @@ export function clearRunnerManifest(file, token) {
         fs.unlinkSync(file);
     }
     catch {
-        /* already gone */
     }
 }
-/** Process-group id of a pid via `ps` (macOS/BSD); null when undiscoverable. */
 export function getProcessGroupId(pid) {
     try {
         const out = execFileSync('ps', ['-o', 'pgid=', '-p', String(pid)], {
@@ -71,12 +42,6 @@ export function getProcessGroupId(pid) {
         return 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 function parseRunnerPidsFromPs(psOutput, tenant, exclude) {
     const pids = [];
     for (const line of psOutput.split('\n')) {
@@ -86,8 +51,6 @@ export function parseRunnerPidsFromPs(psOutput, tenant, exclude) {
         if (!m)
             continue;
         const argv = m[2].split(/\s+/);
-        // The tenant is the argument right after __run/__supervise — an exact
-        // match, so tenant "enc" never matches a runner for tenant "encore".
         const i = argv.findIndex((a) => a === '__run' || a === '__supervise');
         if (i === -1 || argv[i + 1] !== tenant)
             continue;
@@ -97,7 +60,6 @@ export function parseRunnerPidsFromPs(psOutput, tenant, exclude) {
     }
     return pids;
 }
-/** Live argv discovery of runner pids for a tenant (empty when `ps` fails). */
 export function discoverRunnerPids(tenant, exclude) {
     try {
         const out = execFileSync('ps', ['ax', '-o', 'pid=,command='], {
@@ -110,11 +72,6 @@ export function discoverRunnerPids(tenant, exclude) {
         return [];
     }
 }
-/**
- * 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 function startControlServer(payload) {
     return new Promise((resolve, reject) => {
         const server = net.createServer((socket) => {
@@ -132,7 +89,6 @@ export function startControlServer(payload) {
         });
     });
 }
-/** Dial the control endpoint and parse its one-line JSON answer; null on any failure. */
 export function queryControl(port, timeoutMs = 700) {
     return new Promise((resolve) => {
         const s = new net.Socket();
@@ -171,11 +127,6 @@ function defaultPidAlive(pid) {
         return false;
     }
 }
-/**
- * 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 async function verifyRunnerOwnership(args) {
     const { manifest } = args;
     if (!manifest)
@@ -198,17 +149,6 @@ export async function verifyRunnerOwnership(args) {
     }
     return { ok: true, reason: '', resp };
 }
-/**
- * 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 async function pollOwnership(check, deadlineMs) {
     let last = { ok: false, reason: 'not-checked' };
     const end = Date.now() + deadlineMs;
@@ -220,14 +160,12 @@ export async function pollOwnership(check, deadlineMs) {
     } while (Date.now() < end);
     return last;
 }
-/** Best-effort `lsof` description of what holds a port ("cmd (pid N)"); null if unknown. */
 export function describePortOwner(port) {
     try {
         const out = execFileSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fcp'], {
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'ignore'],
         });
-        // -F output: "p<pid>\nc<command>\n…" per process.
         const pid = out.match(/^p(\d+)$/m)?.[1];
         const cmd = out.match(/^c(.+)$/m)?.[1];
         if (!pid && !cmd)
@@ -238,10 +176,6 @@ export function describePortOwner(port) {
         return 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 async function findSquattedPorts(ports, accepts) {
     const squatted = [];
     for (const port of ports) {
@@ -250,10 +184,6 @@ export async function findSquattedPorts(ports, accepts) {
     }
     return squatted;
 }
-/**
- * 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 function buildSquatterError(tenant, squatted, detail) {
     const lines = squatted.map((s) => `    127.0.0.1:${s.port}  held by ${s.owner ?? 'an unidentified process'}`);
     const first = squatted[0]?.port ?? '<port>';
@@ -265,10 +195,6 @@ export function buildSquatterError(tenant, squatted, detail) {
         `    mesh vpn -t ${tenant} tunnel down --stop    # tear down mesh-owned runners + daemon`,
         `    lsof -nP -iTCP:${first} -sTCP:LISTEN        # identify what still holds the port`,
         `  then stop that process and re-run.`,
-        // Port blocks are a 63-bucket hash (MESH-2375), so a DIFFERENT tenant's
-        // runner can collide onto this block — in which case the `down` above is a
-        // no-op and only lsof identifies the real owner.
         `  (If lsof names another mesh runner, it belongs to a different tenant — tear that one down instead.)`,
     ].join('\n');
 }
-//# sourceMappingURL=tunnel-ownership.js.map

package/dist/src/utils/vpn-join.d.ts

@@ -2,31 +2,15 @@ type CtxConfig = {
     issuer?: string;
     vpnJoinBroker?: string;
 } | null;
-/**
- * Resolve the broker URL, preferring the platform-published value from
- * discovery (ContextConfig.vpnJoinBroker) and falling back to DNS-convention
- * derivation for platforms not yet redeployed with the payload field.
- */
 export declare function resolveVpnJoinBroker(context: string, getCfg?: (c: string) => CtxConfig): string | null;
-/**
- * FALLBACK ONLY. Derive by convention — issuer host `identity.<env>.<domain>`
- * → `vpn-join.<env>.<domain>` — mirroring deriveLoginServer (dev.ts:1479).
- * Prefer resolveVpnJoinBroker, which reads the platform-published URL first.
- */
 export declare function deriveVpnJoinBroker(context: string, getCfg?: (c: string) => CtxConfig): string | null;
 export interface MintDeps {
     getValidToken: (context: string) => Promise<string | null>;
     fetchFn?: typeof fetch;
 }
-/**
- * Fetch a single-use pre-auth key from the broker. Returns null on ANY failure
- * (no token, non-2xx, network error) so the caller falls back to the browser
- * relay join — the broker path is strictly additive.
- */
 export declare function mintPreAuthKey(context: string, brokerUrl: string, deps: MintDeps): Promise<{
     authKey: string;
     loginServer: string;
 } | null>;
 export declare function realMintDeps(): MintDeps;
 export {};
-//# sourceMappingURL=vpn-join.d.ts.map