@kontextmind/kxm 0.7.164 → 0.7.166

package/plugins/kxm/src/hub-binding.ts

@@ -1,3 +1,4 @@
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, resolve } from "node:path";
@@ -20,8 +21,31 @@ export interface HubBindingRecord {
   schema: typeof HUB_BINDING_SCHEMA;
   url: string;
   boundAt: string;
+  /** A forwarded or otherwise remote hub. Loopback in the URL does not make this local. */
+  cloud?: true;
+  /** Environment variable that holds the hub token. The token itself is never stored. */
+  tokenEnv?: string;
+  /** Program plus arguments that print the hub token. Not a shell pipeline, and not the token. */
+  tokenCommand?: string;
 }
 
+export type CloudTokenErrorCode = "cloud_token_missing" | "cloud_token_command_failed" | "cloud_token_command_invalid";
+
+/** The cloud binding named a token source and that source did not produce a token. */
+export class CloudTokenError extends Error {
+  readonly code: CloudTokenErrorCode;
+
+  constructor(code: CloudTokenErrorCode, message: string) {
+    super(message);
+    this.name = "CloudTokenError";
+    this.code = code;
+  }
+}
+
+const TOKEN_ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+const TOKEN_COMMAND_TIMEOUT_MS = 15_000;
+const TOKEN_COMMAND_MAX_BUFFER = 4096;
+
 export class HubBindingError extends Error {
   constructor(message: string) {
     super(message);
@@ -71,6 +95,132 @@ export function validateHubUrl(raw: string): string {
   return parsed.href.replace(/\/$/, "");
 }
 
+/** A cloud binding's token command is a program and arguments, never a shell. */
+export function splitTokenCommand(raw: string): string[] {
+  if (/[|&;<>$`\n\r]/.test(raw)) {
+    throw new CloudTokenError(
+      "cloud_token_command_invalid",
+      "token command must be a program and arguments, not a shell pipeline",
+    );
+  }
+  const args: string[] = [];
+  let current = "";
+  let quote: "'" | "\"" | undefined;
+  for (const ch of raw) {
+    if (quote) {
+      if (ch === quote) quote = undefined;
+      else current += ch;
+      continue;
+    }
+    if (ch === "'" || ch === "\"") {
+      quote = ch;
+      continue;
+    }
+    if (ch === " " || ch === "\t") {
+      if (current.length > 0) {
+        args.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += ch;
+  }
+  if (quote) {
+    throw new CloudTokenError("cloud_token_command_invalid", "token command has an unclosed quote");
+  }
+  if (current.length > 0) args.push(current);
+  if (args.length === 0) {
+    throw new CloudTokenError("cloud_token_command_invalid", "token command is empty");
+  }
+  return args;
+}
+
+export function isCloudTokenEnvName(value: string): boolean {
+  return TOKEN_ENV_NAME.test(value);
+}
+
+/**
+ * Where this command should say the hub sits. A cloud binding is remote even when its
+ * URL is a loopback forward, but only for the URL the binding names. `KXM_SERVER_URL`
+ * pointing somewhere else keeps that URL's own scope.
+ */
+export function effectiveHubBindingScope(url: string, env: NodeJS.ProcessEnv = process.env): HubBindingScope {
+  try {
+    const binding = readHubBinding(env);
+    if (binding?.cloud) {
+      try {
+        if (validateHubUrl(url) === binding.url) return "remote";
+      } catch {
+        // An unparsable override is not the cloud binding.
+      }
+    }
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+  }
+  return hubBindingScope(url);
+}
+
+/** Hub URL for a session: explicit env, else the binding, else the local default. */
+export function resolveHubServerUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.KXM_SERVER_URL?.trim();
+  if (fromEnv) return fromEnv.replace(/\/$/, "");
+  try {
+    const binding = readHubBinding(env);
+    if (binding?.url) return binding.url;
+  } catch (error) {
+    if (!(error instanceof HubBindingError)) throw error;
+  }
+  return "http://127.0.0.1:7331";
+}
+
+/**
+ * Resolve the token a cloud binding names. Never reads hub-env and never uses
+ * `KXM_AUTH_TOKEN` unless `tokenEnv` is that name. `tokenEnv` wins when it is non-empty;
+ * otherwise the command runs. The command is not cached.
+ */
+export function resolveCloudHubToken(binding: HubBindingRecord, env: NodeJS.ProcessEnv = process.env): string {
+  if (!binding.cloud) {
+    throw new CloudTokenError("cloud_token_missing", "cloud hub token is missing; the local hub-env token was not used");
+  }
+  if (binding.tokenEnv) {
+    const value = env[binding.tokenEnv]?.trim();
+    if (value) return value;
+  }
+  if (binding.tokenCommand) return runTokenCommand(binding.tokenCommand, env);
+  const source = binding.tokenEnv ? `${binding.tokenEnv} is unset or empty` : "no token source is configured";
+  throw new CloudTokenError(
+    "cloud_token_missing",
+    `cloud hub token is missing: ${source}; the local hub-env token was not used`,
+  );
+}
+
+function runTokenCommand(command: string, env: NodeJS.ProcessEnv): string {
+  const argv = splitTokenCommand(command);
+  const [program, ...args] = argv;
+  const result = spawnSync(program!, args, {
+    encoding: "utf8",
+    shell: false,
+    timeout: TOKEN_COMMAND_TIMEOUT_MS,
+    maxBuffer: TOKEN_COMMAND_MAX_BUFFER,
+    env,
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    throw new CloudTokenError(
+      "cloud_token_command_failed",
+      "token command failed; the local hub-env token was not used",
+    );
+  }
+  const stdout = result.stdout ?? "";
+  if (stdout.trim().length === 0 || stdout.trim() !== stdout.trim().split(/\r?\n/)[0]) {
+    throw new CloudTokenError(
+      "cloud_token_command_failed",
+      "token command did not print a single token; the local hub-env token was not used",
+    );
+  }
+  return stdout.trim();
+}
+
 /** Loopback literals only; `0.0.0.0`, a LAN address or a hostname are all remote. */
 export function hubBindingScope(url: string): HubBindingScope {
   let host: string;
@@ -111,8 +261,11 @@ export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBinding
   }
   const row = parsed as Record<string, unknown>;
   const keys = Object.keys(row);
+  const allowed = new Set(["schema", "url", "boundAt", "cloud", "tokenEnv", "tokenCommand"]);
+  const cloudish = keys.some((key) => key === "cloud" || key === "tokenEnv" || key === "tokenCommand");
   if (
-    keys.length !== 3
+    keys.some((key) => !allowed.has(key))
+    || (!cloudish && keys.length !== 3)
     || row.schema !== HUB_BINDING_SCHEMA
     || typeof row.url !== "string"
     || typeof row.boundAt !== "string"
@@ -126,7 +279,34 @@ export function readHubBinding(env: NodeJS.ProcessEnv = process.env): HubBinding
   } catch {
     throw new HubBindingError(`malformed hub binding at ${file}`);
   }
-  return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
+  if (!cloudish) return { schema: HUB_BINDING_SCHEMA, url, boundAt: row.boundAt };
+  if (row.cloud !== true) throw new HubBindingError(`malformed hub binding at ${file}`);
+  let tokenEnv: string | undefined;
+  let tokenCommand: string | undefined;
+  if (row.tokenEnv !== undefined) {
+    if (typeof row.tokenEnv !== "string" || !isCloudTokenEnvName(row.tokenEnv)) {
+      throw new HubBindingError(`malformed hub binding at ${file}`);
+    }
+    tokenEnv = row.tokenEnv;
+  }
+  if (row.tokenCommand !== undefined) {
+    if (typeof row.tokenCommand !== "string") throw new HubBindingError(`malformed hub binding at ${file}`);
+    try {
+      splitTokenCommand(row.tokenCommand);
+    } catch {
+      throw new HubBindingError(`malformed hub binding at ${file}`);
+    }
+    tokenCommand = row.tokenCommand;
+  }
+  if (!tokenEnv && !tokenCommand) throw new HubBindingError(`malformed hub binding at ${file}`);
+  return {
+    schema: HUB_BINDING_SCHEMA,
+    url,
+    boundAt: row.boundAt,
+    cloud: true,
+    ...(tokenEnv ? { tokenEnv } : {}),
+    ...(tokenCommand ? { tokenCommand } : {}),
+  };
 }
 
 export function writeHubBinding(record: HubBindingRecord, env: NodeJS.ProcessEnv = process.env): string {

package/plugins/kxm/src/hub-env.ts

@@ -2,6 +2,22 @@ import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync
 import { homedir } from "node:os";
 import { randomBytes } from "node:crypto";
 import { dirname, isAbsolute, join, resolve } from "node:path";
+import { loadHubSettings } from "./config.ts";
+import {
+  describeHubConnection,
+  projectTokenMissingMessage,
+  resolveKeyReference,
+  type OpReader,
+  type ProjectIdentity,
+} from "./hub-identity.ts";
+import {
+  CloudTokenError,
+  HubBindingError,
+  hubBindingFile,
+  readHubBinding,
+  resolveCloudHubToken,
+  type HubBindingRecord,
+} from "./hub-binding.ts";
 
 export const HUB_ENV_SCHEMA = "kxm.hub-env.v1" as const;
 
@@ -210,8 +226,81 @@ export function resolveHubCredentials(options: ResolveHubCredentialsOptions = {}
  * only another project's token cannot authorise this one, and a guard that counts it as a
  * credential stores a binding that will fail exactly like the one it prevented.
  */
-export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, project?: string): boolean {
+/** A cloud binding, when this machine has one. A malformed binding fails closed. */
+function activeCloudBinding(env: NodeJS.ProcessEnv): HubBindingRecord | undefined {
+  try {
+    const binding = readHubBinding(env);
+    return binding?.cloud ? binding : undefined;
+  } catch (error) {
+    if (error instanceof HubBindingError) {
+      throw new HubEnvError(
+        `${error.message}; refusing to guess a credential — repair or remove ${hubBindingFile(env)}`,
+      );
+    }
+    throw error;
+  }
+}
+
+/**
+ * Credential for control-plane posts that are not agent sessions (context, degrade).
+ * Non-cloud keeps the historical rule: only the explicit `KXM_AUTH_TOKEN`, never hub-env.
+ * A cloud binding uses its named source and nothing else.
+ */
+export function resolveControlPlaneAuthToken(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  if (cloud) return cloud;
+  return env.KXM_AUTH_TOKEN?.trim() || undefined;
+}
+
+/**
+ * Environment a pi or Claude session started through kxm should inherit.
+ * The project id comes from the shared resolver. A cloud binding adds
+ * `KXM_AUTH_TOKEN` in this object only — it is never written to the binding.
+ */
+function cloudModeToken(
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  explicitProject?: string,
+  opRead?: OpReader,
+): string | undefined {
+  const connection = describeHubConnection(cwd, env, explicitProject === undefined ? {} : { explicitProject });
+  if (connection.mode !== "cloud") return undefined;
+  const fromConfig = resolveKeyReference(connection.endpoint?.key, env, opRead);
+  if (fromConfig) return fromConfig.value;
+  if (connection.binding?.cloud) return resolveCloudHubToken(connection.binding, env);
+  throw new CloudTokenError(
+    "cloud_token_missing",
+    "cloud hub token is missing; the local hub-env token was not used",
+  );
+}
+
+export function agentSessionEnv(
+  cwd: string,
+  env: NodeJS.ProcessEnv = process.env,
+  explicitProject?: string,
+  opRead?: OpReader,
+): NodeJS.ProcessEnv {
+  const connection = describeHubConnection(cwd, env, explicitProject === undefined ? {} : { explicitProject });
+  const session: NodeJS.ProcessEnv = { KXM_PROJECT: connection.project };
+  if (connection.url) session.KXM_SERVER_URL = connection.url.replace(/\/$/, "");
+  if (connection.mode === "cloud") {
+    const token = cloudModeToken(cwd, env, explicitProject, opRead);
+    if (token) session.KXM_AUTH_TOKEN = token;
+  }
+  return session;
+}
+
+export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, project?: string, cwd: string = process.cwd()): boolean {
   if (env.KXM_AUTH_TOKEN?.trim()) return true;
+  const settings = loadHubSettings(cwd, env);
+  const mode = settings.mode ?? (activeCloudBinding(env) ? "cloud" : "local");
+  const key = (mode === "cloud" ? settings.cloud : settings.local)?.key;
+  if (key?.op) return true;
+  if (key?.env && env[key.env]?.trim()) return true;
   let record: HubEnvRecord | undefined;
   try {
     record = readHubEnvRecord(env);
@@ -228,9 +317,18 @@ export function hasClientHubCredential(env: NodeJS.ProcessEnv = process.env, pro
   return Object.values(tokens).some((token) => typeof token === "string" && token.trim().length > 0);
 }
 
-export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
+export function resolveClientHubAuthToken(
+  env: NodeJS.ProcessEnv,
+  project: string,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  if (cloud) return cloud;
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
+  const fromConfig = resolveKeyReference(describeHubConnection(cwd, env).endpoint?.key, env, opRead);
+  if (fromConfig) return fromConfig.value;
   const record = readHubEnvRecord(env);
   return record?.projectTokens?.[project]?.trim() || record?.authToken?.trim() || undefined;
 }
@@ -244,9 +342,20 @@ export function resolveClientHubAuthToken(env: NodeJS.ProcessEnv, project: strin
  * token for. Operator tools keep `resolveClientHubAuthToken`. Throws HubEnvError on a
  * malformed persisted record, same as `resolveClientHubAuthToken`.
  */
-export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string): string | undefined {
+export function resolveAgentHubAuthToken(
+  env: NodeJS.ProcessEnv,
+  project: string,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  // A cloud binding's token is the remote hub's credential. It is not this
+  // machine's hub-env admin token, which an agent must still never use.
+  if (cloud) return cloud;
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
+  const fromConfig = resolveKeyReference(describeHubConnection(cwd, env).endpoint?.key, env, opRead);
+  if (fromConfig) return fromConfig.value;
   const tokens = readHubEnvRecord(env)?.projectTokens;
   if (!tokens || !Object.hasOwn(tokens, project)) return undefined;
   return tokens[project]?.trim() || undefined;
@@ -259,13 +368,19 @@ export function resolveAgentHubAuthToken(env: NodeJS.ProcessEnv, project: string
 export class AgentProjectTokenMissingError extends Error {
   readonly code = "project_token_missing";
   readonly project: string;
+  readonly projectSource: ProjectIdentity["source"] | "unknown";
+  readonly hint: string;
 
-  constructor(project: string) {
-    super(
-      `kxm has no project token for project ${project} on this machine. Set KXM_AUTH_TOKEN to that project's token, or add ${project} to the hub KXM_PROJECT_TOKENS (list every existing project too, because that variable replaces the saved map). An agent never uses the hub admin token.`,
-    );
+  constructor(projectOrIdentity: string | ProjectIdentity) {
+    const identity: ProjectIdentity = typeof projectOrIdentity === "string"
+      ? { project: projectOrIdentity, source: "env", sourceLabel: "the project id sent to the hub" }
+      : projectOrIdentity;
+    const message = projectTokenMissingMessage(identity);
+    super(message);
     this.name = "AgentProjectTokenMissingError";
-    this.project = project;
+    this.project = identity.project;
+    this.projectSource = typeof projectOrIdentity === "string" ? "unknown" : identity.source;
+    this.hint = message;
   }
 }
 
@@ -276,8 +391,16 @@ export class AgentProjectTokenMissingError extends Error {
  * refuse — handing the portal a 401 dressed as "configured" is worse than handing it none.
  * Throws on a malformed persisted record, same as `resolveClientHubAuthToken`.
  */
-export function resolveClientAdminAuthToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
+export function resolveClientAdminAuthToken(
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = process.cwd(),
+  opRead?: OpReader,
+): string | undefined {
+  const cloud = cloudModeToken(cwd, env, undefined, opRead);
+  if (cloud) return cloud;
   const envToken = env.KXM_AUTH_TOKEN?.trim();
   if (envToken) return envToken;
   return readHubEnvRecord(env)?.authToken?.trim() || undefined;
 }
+
+export { CloudTokenError };