@trazum/core 1.8.0

package/src/nearest.ts

@@ -0,0 +1,61 @@
+/**
+ * Suggesting what somebody probably meant.
+ *
+ * Used for an unrecognised CLI flag and an unrecognised config key. Both are
+ * the same failure: a name that looks right, is silently not the name the tool
+ * reads, and leaves a limit unenforced while the author believes it is set.
+ */
+
+/**
+ * Edit distance, with an early exit.
+ *
+ * Bounded by construction: the table is two rows of `b.length + 1`, and pairs
+ * whose lengths differ by more than `MAX_DISTANCE` return immediately without
+ * building anything. Only ever used to rank candidates, so a large distance
+ * needs no precision — `SENTINEL` is simply "further than we care about".
+ */
+const MAX_DISTANCE = 3;
+const SENTINEL = 99;
+
+export function editDistance(a: string, b: string): number {
+  if (Math.abs(a.length - b.length) > MAX_DISTANCE) return SENTINEL;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(
+        prev[j]! + 1,
+        row[j - 1]! + 1,
+        prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      );
+    }
+    prev = row;
+  }
+  return prev[b.length]!;
+}
+
+/**
+ * The closest candidate, or null when nothing is close enough to name.
+ *
+ * **The tolerance scales with the length of what was typed**, and that is the
+ * whole reason this function exists rather than a fixed threshold. Three edits
+ * is a plausible typo on `max-tokens` and a completely different word on
+ * `llm` — which is how a fixed budget of three came to answer "did you mean
+ * --help?" for `--llm`. A wrong guess is worse than no guess: it sends the
+ * reader off to check something that was never the answer.
+ */
+export function nearestName(typed: string, candidates: readonly string[]): string | null {
+  let best: string | null = null;
+  let bestDistance = Infinity;
+
+  for (const candidate of candidates) {
+    const distance = editDistance(typed, candidate);
+    if (distance < bestDistance) {
+      best = candidate;
+      bestDistance = distance;
+    }
+  }
+
+  const tolerance = Math.min(MAX_DISTANCE, Math.max(1, Math.floor(typed.length / 3)));
+  return best !== null && bestDistance <= tolerance ? best : null;
+}

package/src/net.ts

@@ -0,0 +1,233 @@
+/**
+ * Endpoint validation for the pluggable LLM layer.
+ *
+ * Trazum lets the caller choose the URL its optional LLM pass talks to. On a
+ * deployed server that is a server-side request forgery primitive: without
+ * this check, anyone who can reach the web app can make it fetch the cloud
+ * metadata service, an internal admin panel, or any host behind the firewall,
+ * and read the response through the error message.
+ *
+ * This lives in the core rather than in the web route on purpose. It is the
+ * most security-sensitive code in the project, so it belongs where it can be
+ * unit-tested and where every caller — the API route today, anything else
+ * later — gets the same answer.
+ */
+
+/**
+ * Hostnames that must never be reachable from a server-side fetch.
+ *
+ * Written against the *hostname string* rather than a resolved address: DNS
+ * resolution would be more thorough but introduces a TOCTOU window (the name
+ * can resolve differently between the check and the request) and a network
+ * call in a validation path. This blocks the literal forms an attacker
+ * actually types; defence in depth against DNS rebinding belongs at the egress
+ * layer, and is called out in SECURITY.md rather than pretended to here.
+ */
+const PRIVATE_HOST_PATTERNS: readonly RegExp[] = [
+  /^localhost$/i,
+  /^127\./,
+  /^0\./,
+  /^10\./,
+  /^172\.(1[6-9]|2\d|3[01])\./,
+  /^192\.168\./,
+  /^169\.254\./, // cloud metadata (AWS/GCP/Azure) and link-local
+  /^100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\./, // carrier-grade NAT
+  /^\[?::1\]?$/,
+  /^\[?::\]?$/,
+  /^\[?f[cd][0-9a-f]{2}:/i, // IPv6 unique local
+  /^\[?fe80:/i, // IPv6 link-local
+  /^\[?::ffff:/i, // IPv4-mapped IPv6, e.g. ::ffff:169.254.169.254
+  /\.internal$/i,
+  /\.local$/i,
+  /\.localhost$/i,
+  /^metadata\./i,
+  /^metadata$/i,
+];
+
+/** Whether a hostname points somewhere a public service must not fetch. */
+export function isPrivateHost(hostname: string): boolean {
+  const host = hostname.trim().toLowerCase().replace(/\.$/, '');
+  if (!host) return true;
+  return PRIVATE_HOST_PATTERNS.some((pattern) => pattern.test(host));
+}
+
+export type EndpointRejection =
+  | 'invalid-url'
+  | 'insecure-scheme'
+  | 'private-host'
+  | 'credentials-in-url';
+
+export interface ValidateEndpointOptions {
+  /**
+   * Allow `http:` and private hosts. For local development only — it disables
+   * the entire protection, so it must never be derived from request input.
+   */
+  allowInsecure?: boolean;
+}
+
+/**
+ * Validates an LLM endpoint URL. Returns `null` when it is safe to fetch, or a
+ * machine-readable reason when it is not.
+ *
+ * A reason code rather than a message so the caller renders it in the reader's
+ * locale, and so a test asserts on the decision rather than on wording.
+ */
+export function validateLlmEndpoint(
+  raw: string,
+  options: ValidateEndpointOptions = {},
+): EndpointRejection | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return 'invalid-url';
+  }
+
+  const { allowInsecure = false } = options;
+
+  if (url.protocol !== 'https:' && !(allowInsecure && url.protocol === 'http:')) {
+    return 'insecure-scheme';
+  }
+
+  // Credentials in the URL would be forwarded to whatever the host turns out
+  // to be, and would land in any log line that records the endpoint.
+  if (url.username || url.password) {
+    return 'credentials-in-url';
+  }
+
+  if (!allowInsecure && isPrivateHost(url.hostname)) {
+    return 'private-host';
+  }
+
+  return null;
+}
+
+/**
+ * Validates an endpoint and returns the value to fetch, with no trailing slash.
+ *
+ * Returning it rather than approving it is the point. The first version of this
+ * validated `baseUrl` and then fetched
+ * `` `${baseUrl.replace(/\/$/, '')}/chat/completions` `` — two different
+ * expressions, so the thing checked was never the thing used, and a later edit
+ * could have moved the check without anything noticing.
+ *
+ * Re-parsing normalises it too: `https://host/v1/../../admin` passes validation
+ * as a string and resolves somewhere else on the wire.
+ *
+ * Every caller in this package that sends a key to a caller-named host goes
+ * through here — both providers and the exact token counter.
+ */
+export function checkedEndpoint(
+  baseUrl: string,
+  { allowInsecure = false, name }: ValidateEndpointOptions & { name: string },
+): string {
+  const rejection = validateLlmEndpoint(baseUrl, { allowInsecure });
+  if (rejection !== null) {
+    throw new Error(
+      `Provider "${name}" cannot use ${baseUrl}: ${rejection}. ` +
+        'Pass allowInsecure only for an endpoint you configured yourself.',
+    );
+  }
+  return new URL(baseUrl).toString().replace(/\/$/, '');
+}
+
+/**
+ * `fetch` options that every server-side call in this package must carry.
+ *
+ * `redirect: 'error'` is the one that matters, and it was missing. Everything
+ * above validates the URL the caller named — and then `fetch` followed
+ * redirects by default, so an endpoint that passed every check could answer
+ * `302 Location: http://169.254.169.254/latest/meta-data/` and the request went
+ * there anyway, carrying the `authorization` header. The entire host filter was
+ * one HTTP response away from being bypassed, for the CLI as much as for the
+ * deployed app.
+ *
+ * A refused redirect is a thrown `TypeError`, which is the right outcome: a
+ * legitimate LLM endpoint does not redirect its completions API, and one that
+ * suddenly does is exactly the case worth failing on.
+ */
+export const SAFE_FETCH_INIT = {
+  redirect: 'error',
+  // No cookies or TLS client certs on a cross-origin call the caller named.
+  credentials: 'omit',
+  referrerPolicy: 'no-referrer',
+} as const satisfies RequestInit;
+
+// --------------------------------------------------------------------------
+// What a deployment is willing to be pointed at
+// --------------------------------------------------------------------------
+
+/**
+ * Which LLM endpoints a server-side caller is allowed to reach.
+ *
+ * The web route used to take `baseUrl` out of the request body, validate the
+ * string and hand it to a provider. That is server-side request forgery by
+ * construction, and validating harder does not fix it:
+ *
+ * - Every check above reads the *name*. `https://totally-fine.example.com` that
+ *   resolves to `169.254.169.254` passes all of them, and the fix for that is
+ *   pinning the resolved address at the socket, which `fetch` does not offer.
+ * - Even with the redirect hop closed, an anonymous caller could still aim the
+ *   server at any public host and read the reply through the error body.
+ *   "Public" is not the same as "fine to fetch on somebody else's behalf".
+ *
+ * So the request body no longer *names* an endpoint. It **selects** one the
+ * operator listed, and the value that reaches the provider is the entry from
+ * the list — never the string that arrived over HTTP. The default is an empty
+ * list, so a deployment that has not thought about this cannot be pointed
+ * anywhere at all.
+ *
+ * Nobody loses the capability: an operator running Trazum for themselves puts
+ * the endpoint in `TRAZUM_LLM_BASE_URL` and it is used directly, exactly as the
+ * CLI has always worked. This is only about who is allowed to choose.
+ *
+ * `env` is a parameter rather than a read of `process.env` because this module
+ * is on the browser-safe path.
+ */
+const ALLOWLIST_VAR = 'TRAZUM_ALLOWED_LLM_ENDPOINTS';
+
+/** Normalised, so a trailing slash or a capitalised host is not a mismatch. */
+function normaliseEndpoint(raw: string): string | null {
+  try {
+    return new URL(raw.trim()).toString().replace(/\/$/, '');
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The endpoints this server will call, from `TRAZUM_ALLOWED_LLM_ENDPOINTS`
+ * (comma-separated).
+ *
+ * An entry that would fail `validateLlmEndpoint` is dropped rather than
+ * honoured. The operator is trusted to choose, not to be immune from pasting
+ * `http://169.254.169.254` into a list that then serves every anonymous caller.
+ * `allowInsecure` is deliberately not offered: an endpoint only reachable with
+ * the protection off has no business being selectable over HTTP.
+ */
+export function allowedEndpoints(env: Record<string, string | undefined>): readonly string[] {
+  const raw = env[ALLOWLIST_VAR];
+  if (!raw) return [];
+
+  const listed = new Set<string>();
+  for (const part of raw.split(',')) {
+    const url = normaliseEndpoint(part);
+    if (url === null) continue;
+    if (validateLlmEndpoint(url) !== null) continue;
+    listed.add(url);
+  }
+  return [...listed];
+}
+
+/**
+ * Resolves what a caller asked for to an entry on the list.
+ *
+ * Returns the **listed** value, not the requested one. That distinction is the
+ * entire function: the string from the request is compared and then discarded,
+ * so nothing derived from it reaches `fetch`.
+ */
+export function resolveEndpoint(requested: string, allowed: readonly string[]): string | null {
+  const wanted = normaliseEndpoint(requested);
+  if (wanted === null) return null;
+  return allowed.find((entry) => entry.toLowerCase() === wanted.toLowerCase()) ?? null;
+}

package/src/node.ts

@@ -0,0 +1,63 @@
+/**
+ * The parts of the core that read the filesystem.
+ *
+ * Kept off the main entry point on purpose, and the reason is a build failure
+ * rather than a preference: `apps/web` bundles `@trazum/core` for the browser,
+ * and a single `node:fs/promises` import anywhere in that graph fails the build
+ * outright — "the chunking context does not support external modules".
+ *
+ * That failure is the friendly version of the real risk. The web app hands
+ * `optimize()` a prompt straight from a request body; a file read reachable
+ * from that entry point is path traversal available to anyone who can reach the
+ * API. Two entry points make the split structural: the browser cannot import
+ * what is not in its graph, whatever a future refactor does.
+ *
+ * Only the CLI imports this.
+ */
+
+export { loadConfig } from './config.js';
+export type { LoadConfigOptions, LoadedConfig } from './config.js';
+
+// Re-exported for convenience, so the CLI has one import for everything
+// config-shaped. These halves are pure and also live on the main entry point.
+export {
+  CONFIG_FILENAME,
+  CONFIG_KEYS,
+  CONFIG_USAGE_KEYS,
+  ConfigError,
+  DEFAULT_EXTENSIONS,
+  MAX_CONFIG_BYTES,
+  MAX_CONFIG_SEARCH_DEPTH,
+  budgetFor,
+  parseConfig,
+  validateConfigModel,
+} from './config-schema.js';
+export type { ResolvedBudget, TrazumConfig } from './config-schema.js';
+
+// Local price corrections. Pure, so also on the main entry point; re-exported
+// here so the CLI has one import for everything it needs to resolve a run.
+export {
+  MAX_PRICING_BYTES,
+  PricingOverlayError,
+  applyPricingOverlay,
+  catalogueFromOverlay,
+  parsePricingOverlay,
+} from './pricing-overlay.js';
+export type { PricingOverlay } from './pricing-overlay.js';
+
+// Turns a live price feed into an overlay. Pure — the fetch is the CLI's — and
+// re-exported here for the same reason as the overlay itself: one import.
+export { openrouterOverlay } from './openrouter.js';
+export type { OpenRouterResult } from './openrouter.js';
+
+// The endpoint gate every outbound call in this project goes through.
+export { SAFE_FETCH_INIT, checkedEndpoint } from './net.js';
+export { BUNDLED_CATALOGUE } from './pricing.js';
+export type { PricingCatalogue } from './pricing.js';
+
+// Reads the process environment, so it cannot live on the browser-safe entry.
+export { detectHost } from './host.js';
+export type { HostEnvironment } from './host.js';
+
+export { MAX_WALK_DEPTH, MAX_WALK_FILES, walkPrompts } from './walk.js';
+export type { WalkOptions, WalkResult } from './walk.js';

package/src/openrouter.ts

@@ -0,0 +1,125 @@
+import type { PricingOverlay } from './pricing-overlay.js';
+
+/**
+ * A pricing overlay built from OpenRouter's model catalogue.
+ *
+ * **Why a live source at all.** Trazum's bundled prices are a table somebody
+ * typed, and prices change on someone else's schedule. Worse, the table only
+ * covers the providers whoever typed it had reached for — so a user on Groq or
+ * Together got no figure at all, from a tool whose entire output is figures.
+ * OpenRouter publishes price and context window for hundreds of models across
+ * dozens of providers, as data, at a URL. That is a better source than my
+ * memory, and it is current by construction.
+ *
+ * **What it deliberately does not do.** OpenRouter publishes what a model costs
+ * and how much context it takes. It does not publish whether the model has
+ * prompt caching, or the minimum prefix it caches at. Both feed the caching
+ * advisory, which is the largest saving Trazum reports — an order of magnitude
+ * above what the trimming rules recover.
+ *
+ * So a model that arrives from here carries `caching: 'unknown'` and
+ * `cacheMinTokens: null`, and the advisory declines. The two available lies are
+ * symmetrical and both are worse: claim caching works and Trazum offers a
+ * saving that cannot be bought at any price; claim it does not and Trazum hides
+ * the biggest saving there is.
+ *
+ * **Pure, and in the core, so it is testable without a network.** The fetch
+ * lives in the CLI. Everything here is a transformation of a document somebody
+ * already has, which is the same split as `LlmProvider` taking a `fetchImpl`.
+ */
+
+/** The subset of OpenRouter's payload this reads. Everything else is ignored. */
+interface OpenRouterModel {
+  id?: unknown;
+  name?: unknown;
+  context_length?: unknown;
+  pricing?: { prompt?: unknown; completion?: unknown };
+}
+
+export interface OpenRouterResult {
+  overlay: PricingOverlay;
+  /** Ids that were skipped, and the reason, so nothing disappears silently. */
+  skipped: Array<{ id: string; reason: string }>;
+}
+
+/**
+ * OpenRouter quotes USD **per token**, as a decimal string.
+ *
+ * `"0.000003"` is three dollars per million. Parsed rather than multiplied
+ * blindly: a free model quotes `"0"`, and a model with no price for one half
+ * quotes `"-1"` on occasion. Neither is a price Trazum can put in a budget.
+ */
+function perMillion(raw: unknown): number | null {
+  if (typeof raw !== 'string' && typeof raw !== 'number') return null;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value <= 0) return null;
+  return value * 1_000_000;
+}
+
+/**
+ * Turns OpenRouter's catalogue into an overlay.
+ *
+ * `knownIds` is the set the bundled catalogue already has. For those, only the
+ * three things OpenRouter actually knows are overridden — price in, price out,
+ * context window. `cacheMinTokens`, `caching`, `capability` and `tier` are left
+ * alone, because the bundled entry was written by somebody who looked them up
+ * and this feed has nothing to say about them. Overwriting a researched fact
+ * with a blank is not a refresh.
+ */
+export function openrouterOverlay(
+  payload: unknown,
+  options: { knownIds: ReadonlySet<string>; lastReviewed: string; idFor?: (id: string) => string },
+): OpenRouterResult {
+  const { knownIds, lastReviewed, idFor = (id) => id } = options;
+
+  const data = (payload as { data?: unknown })?.data;
+  if (!Array.isArray(data)) {
+    throw new Error('OpenRouter payload has no "data" array — is this the models endpoint?');
+  }
+
+  const models: PricingOverlay['models'] = {};
+  const skipped: Array<{ id: string; reason: string }> = [];
+
+  for (const entry of data as OpenRouterModel[]) {
+    const rawId = typeof entry?.id === 'string' ? entry.id : '';
+    if (!rawId) continue;
+
+    const id = idFor(rawId);
+    const input = perMillion(entry.pricing?.prompt);
+    const output = perMillion(entry.pricing?.completion);
+
+    if (input === null || output === null) {
+      // Free models and half-priced entries. Skipped rather than recorded at
+      // zero: a zero price makes every saving Trazum computes zero too, and a
+      // report full of $0.00 reads as "nothing to gain here" rather than as
+      // "this catalogue has no price for that".
+      skipped.push({ id: rawId, reason: 'no usable price' });
+      continue;
+    }
+
+    const context = Number(entry.context_length);
+    if (!Number.isInteger(context) || context <= 0) {
+      skipped.push({ id: rawId, reason: 'no context window' });
+      continue;
+    }
+
+    if (knownIds.has(id)) {
+      models[id] = { inputPerMTok: input, outputPerMTok: output, contextWindow: context };
+      continue;
+    }
+
+    models[id] = {
+      displayName: typeof entry.name === 'string' && entry.name ? entry.name : rawId,
+      inputPerMTok: input,
+      outputPerMTok: output,
+      contextWindow: context,
+      // The two the feed cannot answer. See the note at the top of this file.
+      cacheMinTokens: null,
+      caching: 'unknown',
+      capability: 'unknown',
+      tier: 'unknown',
+    };
+  }
+
+  return { overlay: { lastReviewed, models }, skipped };
+}