@kontextmind/kxm 0.6.0 → 0.7.10

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

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { randomBytes } from "node:crypto";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const HUB_ENV_SCHEMA = "kxm.hub-env.v1" as const;
+
+export interface HubEnvRecord {
+  schema: typeof HUB_ENV_SCHEMA;
+  /** ISO-8601 creation time of the persisted record. */
+  createdAt: string;
+  authToken?: string | undefined;
+  projectTokens?: Record<string, string> | undefined;
+}
+
+export class HubEnvError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "HubEnvError";
+  }
+}
+
+function resolveUserStateRoot(env: NodeJS.ProcessEnv): string {
+  const explicit = env.KXM_STATE_HOME?.trim();
+  if (explicit) {
+    if (!isAbsolute(explicit)) throw new HubEnvError("local_state_root_not_absolute");
+    return resolve(explicit);
+  }
+  if (process.platform === "win32") {
+    const localAppData = env.LOCALAPPDATA?.trim();
+    const base = localAppData && isAbsolute(localAppData) ? localAppData : join(homedir(), "AppData", "Local");
+    return resolve(base, "KXM");
+  }
+  if (process.platform === "darwin") return resolve(homedir(), "Library", "Application Support", "KXM");
+  const xdgState = env.XDG_STATE_HOME?.trim();
+  const base = xdgState && isAbsolute(xdgState) ? xdgState : join(homedir(), ".local", "state");
+  return resolve(base, "kxm");
+}
+
+export function hubEnvFile(env: NodeJS.ProcessEnv = process.env): string {
+  return join(resolveUserStateRoot(env), "hub-env.json");
+}
+
+export function generateHubAuthToken(): string {
+  return `kxm_admin_${randomBytes(24).toString("base64url")}`;
+}
+
+export function readHubEnvRecord(env: NodeJS.ProcessEnv = process.env): HubEnvRecord | undefined {
+  const file = hubEnvFile(env);
+  if (!existsSync(file)) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new HubEnvError(`hub env file is malformed at ${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new HubEnvError(`hub env file is malformed at ${file}: expected a JSON object`);
+  }
+  const record = parsed as Partial<HubEnvRecord>;
+  if (record.schema !== HUB_ENV_SCHEMA) {
+    throw new HubEnvError(`hub env file at ${file} has unsupported schema ${String(record.schema)}`);
+  }
+  if (record.authToken !== undefined && (typeof record.authToken !== "string" || record.authToken.trim().length === 0)) {
+    throw new HubEnvError(`hub env file at ${file} has an invalid authToken`);
+  }
+  if (record.projectTokens !== undefined) {
+    const tokens = record.projectTokens;
+    if (!tokens || typeof tokens !== "object" || Array.isArray(tokens)) {
+      throw new HubEnvError(`hub env file at ${file} has invalid projectTokens`);
+    }
+    for (const [project, token] of Object.entries(tokens)) {
+      if (!project.trim() || typeof token !== "string" || !token.trim()) {
+        throw new HubEnvError(`hub env file at ${file} has an empty project name or token`);
+      }
+    }
+  }
+  return {
+    schema: HUB_ENV_SCHEMA,
+    createdAt: typeof record.createdAt === "string" ? record.createdAt : "",
+    ...(record.authToken !== undefined ? { authToken: record.authToken } : {}),
+    ...(record.projectTokens !== undefined ? { projectTokens: record.projectTokens } : {}),
+  };
+}
+
+export function writeHubEnvRecord(record: HubEnvRecord, env: NodeJS.ProcessEnv = process.env): string {
+  const file = hubEnvFile(env);
+  const directory = dirname(file);
+  mkdirSync(directory, { recursive: true });
+  const temporary = join(directory, `.hub-env-${process.pid}.tmp`);
+  writeFileSync(temporary, `${JSON.stringify(record, undefined, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+  try {
+    renameSync(temporary, file);
+  } catch (error) {
+    rmSync(temporary, { force: true });
+    throw error;
+  }
+  return file;
+}
+
+export interface ResolveHubCredentialsOptions {
+  env?: NodeJS.ProcessEnv | undefined;
+  /** Injectable token generator for tests. */
+  generateToken?: () => string | undefined;
+  /** When false, never create or update the persisted file. */
+  persist?: boolean | undefined;
+  now?: () => string | undefined;
+}
+
+export interface ResolvedHubCredentials {
+  authToken: string | undefined;
+  projectTokens: Record<string, string> | undefined;
+  /** Where each value came from; `generated` values were persisted when allowed. */
+  authTokenSource: "env" | "file" | "generated" | "none";
+  projectTokensSource: "env" | "file" | "generated" | "none";
+  envFile: string | undefined;
+  written: boolean;
+}
+
+function parseProjectTokens(raw: string | undefined): Record<string, string> | undefined | "invalid" {
+  const trimmed = raw?.trim();
+  if (!trimmed) return undefined;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    return "invalid";
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return "invalid";
+  const entries = Object.entries(parsed as Record<string, unknown>);
+  if (entries.some(([project, token]) => !project.trim() || typeof token !== "string" || !token.trim())) return "invalid";
+  return Object.fromEntries(entries) as Record<string, string>;
+}
+
+/** Resolve hub credentials with persistence across restarts.
+ *
+ * Precedence: explicit environment variable, then the persisted user-state
+ * file, then (for the admin token only) a freshly generated token that is
+ * persisted so later restarts and workers reuse the same credential. */
+export function resolveHubCredentials(options: ResolveHubCredentialsOptions = {}): ResolvedHubCredentials {
+  const env = options.env ?? process.env;
+  const persist = options.persist !== false;
+  const existing = readHubEnvRecord(env);
+  const envFile = hubEnvFile(env);
+
+  const envAuthToken = env.KXM_AUTH_TOKEN?.trim();
+  const envProjectTokens = parseProjectTokens(env.KXM_PROJECT_TOKENS);
+  if (envProjectTokens === "invalid") {
+    throw new HubEnvError("KXM_PROJECT_TOKENS must be a JSON object of project names to tokens");
+  }
+
+  let authTokenSource: ResolvedHubCredentials["authTokenSource"] = "none";
+  let authToken = envAuthToken || existing?.authToken;
+  if (envAuthToken) authTokenSource = "env";
+  else if (authToken) authTokenSource = "file";
+
+  if (!authToken) {
+    const generated = options.generateToken?.() ?? generateHubAuthToken();
+    if (generated) {
+      authToken = generated;
+      authTokenSource = "generated";
+    }
+  }
+
+  let projectTokensSource: ResolvedHubCredentials["projectTokensSource"] = "none";
+  let projectTokens = envProjectTokens ?? existing?.projectTokens;
+  if (envProjectTokens) projectTokensSource = "env";
+  else if (projectTokens) projectTokensSource = "file";
+
+  const needsPersist = persist
+    && (authTokenSource === "generated"
+      || (authTokenSource === "env" && existing?.authToken !== authToken)
+      || (projectTokensSource === "env" && JSON.stringify(existing?.projectTokens ?? undefined) !== JSON.stringify(projectTokens ?? undefined)));
+
+  if (needsPersist) {
+    const record: HubEnvRecord = {
+      schema: HUB_ENV_SCHEMA,
+      createdAt: existing?.createdAt || (options.now?.() ?? new Date().toISOString()),
+      ...(authToken ? { authToken } : {}),
+      ...(projectTokens ? { projectTokens } : {}),
+    };
+    writeHubEnvRecord(record, env);
+  }
+
+  return {
+    authToken,
+    projectTokens,
+    authTokenSource,
+    projectTokensSource,
+    envFile: needsPersist || existing ? envFile : undefined,
+    written: needsPersist === true,
+  };
+}

package/plugins/kxm/src/hub.ts

@@ -29,6 +29,7 @@ import {
   type WorkflowMessageContext,
 } from "./protocol.ts";
 import { workflowScopeExtras } from "./diagnostics.ts";
+import { timingSafeStringCompare } from "./commands.ts";
 import { arbitrate, explainContextItem, journalEntryToContextItem, memoryRecordToContextItem, rolePolicy } from "./arbiter.ts";
 import { loadAuthoredMemory } from "./memory.ts";
 import { contextItemAuditMetadata, CONTEXT_AUTHORITIES, CONTEXT_CONFIDENCES, type ContextAuthority, type ContextConfidence, type ContextItem } from "./context.ts";
@@ -123,10 +124,7 @@ function publicAgent(agent: StoredAgent): AgentRecord {
 }
 
 function safeTokenEqual(actual: string | undefined, expected: string): boolean {
-  if (!actual) return false;
-  const actualHash = createHash("sha256").update(actual).digest();
-  const expectedHash = createHash("sha256").update(expected).digest();
-  return timingSafeEqual(actualHash, expectedHash);
+  return timingSafeStringCompare(actual, expected);
 }
 
 function bearerToken(request: IncomingMessage): string | undefined {

package/plugins/kxm/src/improve.ts

@@ -381,3 +381,75 @@ export function formatImprovementReport(report: ImprovementReport): string {
 
   return lines.join("\n");
 }
+
+export interface PromotionDecision {
+  eligible: boolean;
+  policy: "manual_pr" | "critic_quorum" | "auto_threshold";
+  authorized: boolean;
+  reason: string;
+}
+
+/**
+ * Evaluates candidate promotion policy (Decision Q11).
+ * Supports:
+ * - manual_pr: strict operator signoff via Git PR / CLI (fail-closed anti-privilege-escalation)
+ * - critic_quorum: requires dual critic approval before auto-promotion
+ * - auto_threshold: requires candidate to exceed recurrence and verifyPassRate thresholds
+ */
+export function evaluatePromotionPolicy(
+  candidate: ImprovementCandidate,
+  policy: "manual_pr" | "critic_quorum" | "auto_threshold" = "manual_pr",
+  options?: {
+    criticApprovals?: string[] | undefined;
+    autoThreshold?: {
+      minRuns: number;
+      minPassRate: number;
+      minCostSavings?: number | undefined;
+    } | undefined;
+  },
+): PromotionDecision {
+  if (policy === "manual_pr") {
+    return {
+      eligible: true,
+      policy,
+      authorized: false,
+      reason: "Manual PR review and signoff required by policy (fail-closed anti-privilege-escalation)",
+    };
+  }
+
+  if (policy === "critic_quorum") {
+    const approvals = options?.criticApprovals ?? [];
+    const hasQuorum = approvals.length >= 2;
+    return {
+      eligible: true,
+      policy,
+      authorized: hasQuorum,
+      reason: hasQuorum
+        ? `Authorized by critic quorum (${approvals.join(", ")})`
+        : `Requires dual critic quorum; current approvals: ${approvals.length}/2`,
+    };
+  }
+
+  if (policy === "auto_threshold") {
+    const threshold = options?.autoThreshold ?? { minRuns: 10, minPassRate: 0.95 };
+    const recurrence = candidate.baselineMetrics.recurrence;
+    const passRate = candidate.baselineMetrics.verifyPassRate;
+    const meetsThreshold = recurrence >= threshold.minRuns && passRate >= threshold.minPassRate;
+
+    return {
+      eligible: true,
+      policy,
+      authorized: meetsThreshold,
+      reason: meetsThreshold
+        ? `Authorized by auto-threshold (runs=${recurrence}>=${threshold.minRuns}, passRate=${passRate}>=${threshold.minPassRate})`
+        : `Auto-threshold not met: runs=${recurrence}/${threshold.minRuns}, passRate=${passRate}/${threshold.minPassRate}`,
+    };
+  }
+
+  return {
+    eligible: false,
+    policy,
+    authorized: false,
+    reason: `Unknown promotion policy: ${String(policy)}`,
+  };
+}