@duckmind/dm-darwin-x64 0.66.5 → 0.66.7

package/extensions/dm-mcp-adapter/dist/http-ca.js

@@ -0,0 +1,75 @@
+import { readFileSync } from "node:fs";
+import { X509Certificate } from "node:crypto";
+import { Agent, Request as UndiciRequest, fetch as undiciFetch } from "undici";
+import { getMissingEnvVars, resolveConfigPath, resolveServerUrl } from "./utils.js";
+export function validateCaFile(definition) {
+  if (definition.caFile === undefined)
+    return;
+  if (typeof definition.caFile !== "string" || !definition.caFile.trim()) {
+    throw new Error("MCP caFile must be a non-empty path string");
+  }
+  if (definition.command !== undefined || definition.socket !== undefined || !definition.url || new URL(resolveServerUrl(definition)).protocol !== "https:") {
+    throw new Error("MCP caFile is only supported for HTTPS HTTP servers");
+  }
+}
+export function createCaFetch(definition) {
+  validateCaFile(definition);
+  if (definition.caFile === undefined)
+    return;
+  const origin = new URL(resolveServerUrl(definition)).origin;
+  if (getMissingEnvVars(definition.caFile).length)
+    throw new Error("Missing environment variable in MCP caFile");
+  let ca;
+  try {
+    ca = readFileSync(resolveConfigPath(definition.caFile), "utf8");
+    const certificates = ca.match(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g);
+    if (!certificates?.length || ca.replace(/-----BEGIN CERTIFICATE-----[\s\S]*?-----END CERTIFICATE-----/g, "").trim()) {
+      throw new Error("expected a PEM certificate bundle");
+    }
+    for (const certificate of certificates)
+      new X509Certificate(certificate);
+  } catch (cause) {
+    throw new Error("Failed to load MCP caFile PEM certificate bundle", { cause });
+  }
+  const dispatcher = new Agent({ connect: { ca } });
+  let closed;
+  return {
+    fetch: (input, init) => {
+      const url = new URL(input instanceof Request ? input.url : input.toString());
+      if (url.origin !== origin)
+        return globalThis.fetch(input, init);
+      try {
+        if (input instanceof Request) {
+          input = new Request(input, init);
+          init = undefined;
+        }
+        const bundledInput = input instanceof Request ? new UndiciRequest(input.url, {
+          method: input.method,
+          headers: [...input.headers],
+          ...init?.body == null && input.body ? { body: async function* () {
+            yield* input.body;
+          }(), duplex: "half" } : {},
+          cache: input.cache,
+          credentials: input.credentials,
+          integrity: input.integrity,
+          keepalive: input.keepalive,
+          mode: input.mode,
+          redirect: input.redirect,
+          referrer: input.referrer,
+          referrerPolicy: input.referrerPolicy,
+          signal: input.signal
+        }) : input;
+        const options = {
+          ...init,
+          ...init?.headers !== undefined ? { headers: [...new Headers(init.headers)] } : {},
+          dispatcher,
+          redirect: "error"
+        };
+        return undiciFetch(bundledInput, options);
+      } catch (error) {
+        return Promise.reject(error);
+      }
+    },
+    close: () => closed ??= dispatcher.destroy()
+  };
+}

package/extensions/dm-mcp-adapter/dist/jev-client.js

@@ -0,0 +1,359 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { isServerDisabled } from "./types.js";
+import { combineAbortSignals } from "./runtime-owner.js";
+import { JEV_SDK_PATH, OPENROUTER_ORIGIN, resolveJevCredential, resolveJevEndpoint } from "./jev-key-store.js";
+const DEFAULTS = {
+  semanticSearch: false,
+  scriptEvaluation: false,
+  allowedServers: [],
+  model: "jev-1.13.0",
+  requestTimeoutMs: 5000,
+  maxRetries: 0,
+  maxStateBytes: 262144,
+  maxQuestionsPerRequest: 64,
+  maxEvaluationsPerScript: 8,
+  maxEvaluationBytesPerScript: 524288,
+  maxEvaluationTokensPerScript: 32768,
+  semanticCandidateLimit: 127,
+  semanticMinProbability: 0.2
+};
+const DANGEROUS_KEYS = new Set(["__proto__", "constructor", "prototype"]);
+const OPENROUTER_DEFAULT_MODEL = "typesafe/jev-1.13";
+const hosts = new WeakMap;
+const credentials = new WeakMap;
+function resolveCredential(state, endpoint) {
+  const existing = credentials.get(state);
+  if (existing && existing.endpoint === endpoint.href)
+    return existing.credential;
+  const credential = resolveJevCredential(process.env, endpoint);
+  if (credential.status === "present")
+    credentials.set(state, { endpoint: endpoint.href, credential });
+  return credential;
+}
+function credentialForState(state) {
+  const resolution = resolveJevEndpoint();
+  return resolution.status === "unavailable" ? resolution : resolveCredential(state, resolution.endpoint);
+}
+export function areJevSourcesAllowed(state, settings, sources) {
+  for (const source of sources) {
+    const server = state.config.mcpServers[source];
+    if (!settings.allowedServers.includes(source) || !server || isServerDisabled(server))
+      return false;
+  }
+  return true;
+}
+function record(value, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error(`${label} must be an object`);
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null)
+    throw new Error(`${label} must be a plain object`);
+  return value;
+}
+function boolean(value, fallback, label) {
+  if (value === undefined)
+    return fallback;
+  if (typeof value !== "boolean")
+    throw new Error(`${label} must be a boolean`);
+  return value;
+}
+function integer(value, fallback, min, max, label) {
+  if (value === undefined)
+    return fallback;
+  if (!Number.isInteger(value) || value < min || value > max)
+    throw new Error(`${label} must be an integer from ${min} to ${max}`);
+  return value;
+}
+export function validateJevSettings(value) {
+  if (value === undefined || value === false)
+    return { ...DEFAULTS, allowedServers: [...DEFAULTS.allowedServers] };
+  const input = record(value, "settings.jev");
+  const allowed = new Set(Object.keys(DEFAULTS));
+  for (const key of Object.keys(input))
+    if (!allowed.has(key))
+      throw new Error(`settings.jev.${key} is not supported`);
+  if (input.allowedServers !== undefined && (!Array.isArray(input.allowedServers) || input.allowedServers.some((name) => typeof name !== "string" || name.length === 0 || DANGEROUS_KEYS.has(name) || /[\u0000-\u001f\u007f]/.test(name)))) {
+    throw new Error("settings.jev.allowedServers must contain non-empty safe server names");
+  }
+  const model = input.model ?? DEFAULTS.model;
+  if (typeof model !== "string" || model.length === 0 || model.length > 128 || /(?:latest|preview)/i.test(model))
+    throw new Error("settings.jev.model must be a pinned model name");
+  const probability = input.semanticMinProbability ?? DEFAULTS.semanticMinProbability;
+  if (typeof probability !== "number" || !Number.isFinite(probability) || probability < 0 || probability > 1)
+    throw new Error("settings.jev.semanticMinProbability must be from 0 to 1");
+  return {
+    semanticSearch: boolean(input.semanticSearch, DEFAULTS.semanticSearch, "settings.jev.semanticSearch"),
+    scriptEvaluation: boolean(input.scriptEvaluation, DEFAULTS.scriptEvaluation, "settings.jev.scriptEvaluation"),
+    allowedServers: [...new Set(input.allowedServers ?? DEFAULTS.allowedServers)],
+    model,
+    requestTimeoutMs: integer(input.requestTimeoutMs, DEFAULTS.requestTimeoutMs, 100, 30000, "settings.jev.requestTimeoutMs"),
+    maxRetries: integer(input.maxRetries, DEFAULTS.maxRetries, 0, 2, "settings.jev.maxRetries"),
+    maxStateBytes: integer(input.maxStateBytes, DEFAULTS.maxStateBytes, 1, 1048576, "settings.jev.maxStateBytes"),
+    maxQuestionsPerRequest: integer(input.maxQuestionsPerRequest, DEFAULTS.maxQuestionsPerRequest, 1, 128, "settings.jev.maxQuestionsPerRequest"),
+    maxEvaluationsPerScript: integer(input.maxEvaluationsPerScript, DEFAULTS.maxEvaluationsPerScript, 1, 32, "settings.jev.maxEvaluationsPerScript"),
+    maxEvaluationBytesPerScript: integer(input.maxEvaluationBytesPerScript, DEFAULTS.maxEvaluationBytesPerScript, 1, 4194304, "settings.jev.maxEvaluationBytesPerScript"),
+    maxEvaluationTokensPerScript: integer(input.maxEvaluationTokensPerScript, DEFAULTS.maxEvaluationTokensPerScript, 1, 1e6, "settings.jev.maxEvaluationTokensPerScript"),
+    semanticCandidateLimit: integer(input.semanticCandidateLimit, DEFAULTS.semanticCandidateLimit, 2, 127, "settings.jev.semanticCandidateLimit"),
+    semanticMinProbability: probability
+  };
+}
+export function resolveSemanticJevSettings(state, credentialResolver) {
+  const configured = state.config.settings?.jev;
+  const settings = validateJevSettings(configured);
+  if (configured === false || configured?.semanticSearch === false)
+    return settings;
+  const semanticSearch = settings.semanticSearch || (credentialResolver ? credentialResolver() : credentialForState(state)).status === "present";
+  const hasExplicitAllowlist = configured !== undefined && Object.hasOwn(configured, "allowedServers");
+  const allowedServers = hasExplicitAllowlist ? settings.allowedServers : Object.keys(state.config.mcpServers).filter((name) => !isServerDisabled(state.config.mcpServers[name]));
+  return { ...settings, semanticSearch, allowedServers };
+}
+function validateJson(value, path, seen = new Set) {
+  if (value === null || typeof value === "string" || typeof value === "boolean")
+    return;
+  if (typeof value === "number") {
+    if (Number.isFinite(value))
+      return;
+    throw new Error(`${path} contains a non-finite number`);
+  }
+  if (typeof value !== "object")
+    throw new Error(`${path} is not JSON-compatible`);
+  if (seen.has(value))
+    throw new Error(`${path} contains a cycle`);
+  seen.add(value);
+  if (Array.isArray(value))
+    value.forEach((item, index) => validateJson(item, `${path}[${index}]`, seen));
+  else {
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+      throw new Error(`${path} contains a non-plain object`);
+    for (const [key, item] of Object.entries(value)) {
+      if (DANGEROUS_KEYS.has(key))
+        throw new Error(`${path} contains an unsafe key`);
+      validateJson(item, `${path}.${key}`, seen);
+    }
+  }
+  seen.delete(value);
+}
+function validateId(id, label) {
+  if (id.length === 0 || id.length > 128 || DANGEROUS_KEYS.has(id) || /[\u0000-\u001f\u007f]/.test(id))
+    throw new Error(`${label} contains an invalid identifier`);
+}
+function validateSource(source) {
+  if (source.length === 0 || DANGEROUS_KEYS.has(source) || /[\u0000-\u001f\u007f]/.test(source))
+    throw new Error("sources contains an invalid server name");
+}
+function exactKeys(value, allowed, label) {
+  if (Object.keys(value).some((key) => !allowed.includes(key)))
+    throw new Error(`${label} contains unsupported fields`);
+}
+export function validateJevEvaluateInput(value, limits) {
+  const input = record(value, "Jev evaluation input");
+  exactKeys(input, ["state", "questions", "sources"], "Jev evaluation input");
+  if (!("state" in input))
+    throw new Error("Jev evaluation input requires state");
+  validateJson(input.state, "state");
+  const stateBytes = Buffer.byteLength(JSON.stringify(input.state));
+  if (stateBytes > limits.maxStateBytes)
+    throw new Error("Jev state exceeds maxStateBytes");
+  const questions = record(input.questions, "questions");
+  const entries = Object.entries(questions);
+  if (entries.length < 1 || entries.length > limits.maxQuestionsPerRequest)
+    throw new Error("Jev question count is outside the configured limit");
+  for (const [id, raw] of entries) {
+    validateId(id, "questions");
+    const question = record(raw, `question ${id}`);
+    if (question.type === "choice") {
+      exactKeys(question, ["type", "instructions", "criteria"], `question ${id}`);
+      const criteria = record(question.criteria, `question ${id} criteria`);
+      const labels = Object.keys(criteria);
+      if (labels.length < 2 || labels.length > 128)
+        throw new Error(`question ${id} choice criteria must have 2 to 128 labels`);
+      for (const label of labels) {
+        validateId(label, `question ${id} criteria`);
+        validateJson(criteria[label], `question ${id} criteria.${label}`);
+      }
+    } else if (question.type === "score") {
+      exactKeys(question, ["type", "instructions", "criteria"], `question ${id}`);
+      if (!Array.isArray(question.criteria) || question.criteria.length < 2 || question.criteria.length > 16)
+        throw new Error(`question ${id} score criteria must have 2 to 16 entries`);
+      validateJson(question.criteria, `question ${id} criteria`);
+    } else if (question.type === "noul") {
+      exactKeys(question, ["type", "instructions", "criteria"], `question ${id}`);
+      if (question.criteria !== undefined) {
+        const criteria = record(question.criteria, `question ${id} criteria`);
+        exactKeys(criteria, ["true", "false"], `question ${id} criteria`);
+        validateJson(criteria, `question ${id} criteria`);
+      }
+    } else
+      throw new Error(`question ${id} has an invalid type`);
+    if (question.instructions !== undefined)
+      validateJson(question.instructions, `question ${id} instructions`);
+  }
+  let sources;
+  if (input.sources !== undefined) {
+    if (!Array.isArray(input.sources))
+      throw new Error("sources must be an array");
+    sources = input.sources.map((source, index) => {
+      if (typeof source !== "string")
+        throw new Error(`sources[${index}] must be a string`);
+      validateSource(source);
+      return source;
+    });
+    if (new Set(sources).size !== sources.length)
+      throw new Error("sources must not contain duplicates");
+  }
+  const normalized = { state: input.state, questions, ...sources ? { sources } : {} };
+  if (Buffer.byteLength(JSON.stringify(normalized)) > limits.maxEvaluationBytesPerScript)
+    throw new Error("Jev request exceeds the configured byte limit");
+  return normalized;
+}
+function safeNumber(value, label, integerOnly = false) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || integerOnly && !Number.isInteger(value))
+    throw new Error(`Invalid ${label}`);
+  return value;
+}
+function probability(value, label) {
+  const number = safeNumber(value, label);
+  if (number > 1)
+    throw new Error(`Invalid ${label}`);
+  return number;
+}
+function sameKeys(actual, expected) {
+  const keys = Object.keys(actual);
+  return keys.length === expected.length && expected.every((key) => Object.hasOwn(actual, key));
+}
+function validateResponse(value, input) {
+  const response = record(value, "response");
+  const answers = record(response.answers, "response answers");
+  const questionNames = Object.keys(input.questions);
+  if (!sameKeys(answers, questionNames))
+    throw new Error("Response answer keys do not match questions");
+  const validated = {};
+  for (const name of questionNames) {
+    const question = input.questions[name];
+    const answer = record(answers[name], `answer ${name}`);
+    if (answer.type !== question.type)
+      throw new Error(`Answer ${name} type does not match`);
+    if (question.type === "choice") {
+      exactKeys(answer, ["type", "choice", "confidence", "probabilities"], `answer ${name}`);
+      const labels = Object.keys(question.criteria);
+      if (typeof answer.choice !== "string" || !Object.hasOwn(question.criteria, answer.choice))
+        throw new Error(`Answer ${name} choice is invalid`);
+      const probabilities = record(answer.probabilities, `answer ${name} probabilities`);
+      if (!sameKeys(probabilities, labels))
+        throw new Error(`Answer ${name} probability keys are invalid`);
+      validated[name] = { type: "choice", choice: answer.choice, confidence: probability(answer.confidence, "confidence"), probabilities: Object.fromEntries(labels.map((label) => [label, probability(probabilities[label], "probability")])) };
+    } else if (question.type === "score") {
+      exactKeys(answer, ["type", "score", "confidence", "probabilities", "legend"], `answer ${name}`);
+      const labels = question.criteria.map((_, index) => String(index));
+      const probabilities = record(answer.probabilities, `answer ${name} probabilities`);
+      if (!sameKeys(probabilities, labels))
+        throw new Error(`Answer ${name} probability keys are invalid`);
+      const score = safeNumber(answer.score, "score");
+      if (score > question.criteria.length - 1)
+        throw new Error(`Answer ${name} score is invalid`);
+      validated[name] = { type: "score", score, confidence: probability(answer.confidence, "confidence"), probabilities: Object.fromEntries(labels.map((label) => [label, probability(probabilities[label], "probability")])) };
+    } else {
+      exactKeys(answer, ["type", "noul"], `answer ${name}`);
+      validated[name] = { type: "noul", noul: probability(answer.noul, "noul") };
+    }
+  }
+  if (typeof response.model !== "string" || response.model.length === 0 || response.model.length > 128)
+    throw new Error("Invalid response model");
+  const usage = record(response.usage, "response usage");
+  return { answers: validated, model: response.model, usage: { inputTokens: safeNumber(usage.input_tokens, "input tokens", true), outputTokens: safeNumber(usage.output_tokens, "output tokens", true) } };
+}
+function createPinnedEndpointFetch(endpoint) {
+  return (input, init) => {
+    const target = input.replace(JEV_SDK_PATH, () => endpoint.path);
+    const url = new URL(target);
+    if (url.origin !== endpoint.origin || url.pathname !== endpoint.path || url.search !== "" || url.hash !== "") {
+      throw new Error("Jev request endpoint rejected");
+    }
+    return fetch(target, { ...init, redirect: "error" });
+  };
+}
+function getHost(state, settings) {
+  const resolution = resolveJevEndpoint();
+  if (resolution.status === "unavailable")
+    return { ok: false, error: { code: "endpoint_unavailable", message: resolution.message } };
+  const { endpoint } = resolution;
+  const existing = hosts.get(state);
+  if (existing && existing.endpoint.href === endpoint.href)
+    return existing;
+  const credential = resolveCredential(state, endpoint);
+  if (credential.status === "missing")
+    return { ok: false, error: { code: "credential_missing", message: "Jev API key is not configured." } };
+  if (credential.status === "unavailable")
+    return { ok: false, error: { code: "credential_unavailable", message: credential.message } };
+  const host = { endpoint, client: new TypeSafeClient({ apiKey: credential.apiKey, baseURL: endpoint.origin, defaultModel: settings.model, logLevel: "off", retry: { maxRetries: settings.maxRetries }, timeout: settings.requestTimeoutMs, defaultHeaders: {}, fetch: createPinnedEndpointFetch(endpoint) }) };
+  hosts.set(state, host);
+  return host;
+}
+function failure(error, signal, timedOut) {
+  if (timedOut)
+    return { ok: false, error: { code: "timeout", message: "Jev evaluation timed out.", retryable: true } };
+  if (signal?.aborted || error instanceof Error && error.name === "APIUserAbortError")
+    return { ok: false, error: { code: "aborted", message: "Jev evaluation was aborted." } };
+  const status = typeof error === "object" && error !== null && "status" in error ? error.status : undefined;
+  if (status === 401 || status === 403)
+    return { ok: false, error: { code: "authentication_failed", message: "Jev authentication failed." } };
+  if (status === 402)
+    return { ok: false, error: { code: "payment_required", message: "Jev provider requires payment for this account." } };
+  if (status === 404 || status === 405 || status === 410)
+    return { ok: false, error: { code: "endpoint_unavailable", message: "Jev endpoint was not found; check SYSTEMONE_ENDPOINT." } };
+  if (status === 408)
+    return { ok: false, error: { code: "timeout", message: "Jev evaluation timed out.", retryable: true } };
+  if (status === 429)
+    return { ok: false, error: { code: "rate_limited", message: "Jev rate limit exceeded.", retryable: true } };
+  if (typeof status === "number" && status >= 500)
+    return { ok: false, error: { code: "service_unavailable", message: "Jev service is unavailable.", retryable: true } };
+  if (typeof status === "number" && status >= 400)
+    return { ok: false, error: { code: "invalid_request", message: `Jev rejected the evaluation request (HTTP ${status}).` } };
+  if (error instanceof Error && (error.name === "APIConnectionError" || error.name === "APITimeoutError"))
+    return { ok: false, error: { code: "service_unavailable", message: "Jev service is unavailable.", retryable: true } };
+  return { ok: false, error: { code: "invalid_response", message: "Jev returned an invalid response." } };
+}
+export async function evaluateJev(state, value, options) {
+  let settings;
+  let input;
+  try {
+    settings = options.purpose === "semantic-search" ? resolveSemanticJevSettings(state) : validateJevSettings(state.config.settings?.jev);
+    input = validateJevEvaluateInput(value, settings);
+  } catch {
+    return { ok: false, error: { code: "invalid_request", message: "Invalid Jev evaluation request or settings." } };
+  }
+  if (options.purpose === "script" && !settings.scriptEvaluation || options.purpose === "semantic-search" && !settings.semanticSearch)
+    return { ok: false, error: { code: "disabled", message: "Jev evaluation is disabled." } };
+  const sources = new Set([...input.sources ?? [], ...options.observedSources ?? []]);
+  if (!areJevSourcesAllowed(state, settings, sources))
+    return { ok: false, error: { code: "data_policy_denied", message: "Evaluation sources are not allowed by policy." } };
+  const bytes = Buffer.byteLength(JSON.stringify(input));
+  if (options.budget && !options.budget.consume(bytes))
+    return { ok: false, error: { code: "budget_exhausted", message: "Jev evaluation budget exhausted." } };
+  const resolved = getHost(state, settings);
+  if (!("client" in resolved))
+    return resolved;
+  const deadline = new AbortController;
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    deadline.abort(new Error("Jev evaluation deadline exceeded"));
+  }, settings.requestTimeoutMs);
+  const signal = combineAbortSignals(options.signal, state.owner.signal, deadline.signal);
+  try {
+    const configured = state.config.settings?.jev;
+    const model = resolved.endpoint.origin === OPENROUTER_ORIGIN && (!configured || configured.model === undefined) ? OPENROUTER_DEFAULT_MODEL : settings.model;
+    const request = { state: input.state, questions: input.questions, model };
+    const raw = await resolved.client.systemOne(request, { ...signal ? { signal } : {}, timeout: settings.requestTimeoutMs, retry: { maxRetries: settings.maxRetries } });
+    try {
+      return { ok: true, data: validateResponse(raw, input) };
+    } catch {
+      return { ok: false, error: { code: "invalid_response", message: "Jev returned an invalid response." } };
+    }
+  } catch (error) {
+    return failure(error, signal, timedOut);
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/extensions/dm-mcp-adapter/dist/jev-contracts.js

@@ -0,0 +1 @@
+export {};

package/extensions/dm-mcp-adapter/dist/jev-key-store.js

@@ -0,0 +1,189 @@
+import { createSecureKeyringStore } from "./secure-keyring.js";
+export const JEV_DEFAULT_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+const SYSTEMONE_ENDPOINT_ENV = "SYSTEMONE_ENDPOINT";
+const SYSTEMONE_API_KEY_ENV = "SYSTEMONE_API_KEY";
+const LEGACY_TYPESAFE_API_KEY_ENV = "TYPESAFE_API_KEY";
+const OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
+export const OPENROUTER_ORIGIN = "https://openrouter.ai";
+export const TYPESAFE_API_ORIGIN = "https://api.typesafe.ai";
+export const JEV_KEYRING_ACCOUNT = "typesafe@sha256(https://api.typesafe.ai)";
+export const JEV_KEYRING_SERVICE = "dm-mcp-adapter.service-key";
+const MAX_ENDPOINT_LENGTH = 512;
+export const JEV_SDK_PATH = "/v1/systemone";
+
+export class JevCredentialStoreError extends Error {
+  operation;
+  code = "JEV_CREDENTIAL_STORE_UNAVAILABLE";
+  constructor(operation, cause) {
+    super(`Jev API key secure credential store unavailable during ${operation}. Configure or unlock the OS credential store and retry.`, { cause });
+    this.operation = operation;
+    this.name = "JevCredentialStoreError";
+  }
+}
+function validateApiKey(value) {
+  if (typeof value !== "string" || value.trim().length === 0 || /[\u0000-\u001f\u007f]/.test(value)) {
+    throw new Error("Jev API key must be a non-empty string without control characters");
+  }
+  return value;
+}
+function isLoopbackHostname(hostname) {
+  return hostname === "localhost" || hostname === "[::1]" || /^127\.\d+\.\d+\.\d+$/.test(hostname);
+}
+function parseEndpoint(raw, label) {
+  if (typeof raw !== "string" || raw.trim().length === 0)
+    throw new Error(`${label} must be a non-empty URL`);
+  if (raw.length > MAX_ENDPOINT_LENGTH)
+    throw new Error(`${label} must be at most ${MAX_ENDPOINT_LENGTH} characters`);
+  if (/[\u0000-\u001f\u007f\s]/.test(raw))
+    throw new Error(`${label} must not contain whitespace or control characters`);
+  let url;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(`${label} must be an absolute URL`);
+  }
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && isLoopbackHostname(url.hostname))) {
+    throw new Error(`${label} must use https, except http on localhost, 127.0.0.0/8, or [::1]`);
+  }
+  if (url.username !== "" || url.password !== "")
+    throw new Error(`${label} must not embed credentials`);
+  if (url.search !== "")
+    throw new Error(`${label} must not include a query string`);
+  if (url.hash !== "")
+    throw new Error(`${label} must not include a fragment`);
+  if (url.pathname === "" || url.pathname === "/")
+    throw new Error(`${label} must include a path such as ${JEV_SDK_PATH}`);
+  return { href: `${url.origin}${url.pathname}`, origin: url.origin, path: url.pathname };
+}
+export function resolveJevEndpoint(env = process.env) {
+  if (Object.hasOwn(env, SYSTEMONE_ENDPOINT_ENV)) {
+    try {
+      return { status: "resolved", source: "environment", endpoint: parseEndpoint(env[SYSTEMONE_ENDPOINT_ENV], SYSTEMONE_ENDPOINT_ENV) };
+    } catch (error) {
+      return { status: "unavailable", message: error instanceof Error ? error.message : `${SYSTEMONE_ENDPOINT_ENV} is invalid.` };
+    }
+  }
+  return { status: "resolved", source: "default", endpoint: parseEndpoint(JEV_DEFAULT_ENDPOINT, "the default Jev endpoint") };
+}
+export function jevKeyringAccount(endpoint) {
+  return `systemone@sha256(${endpoint.href})`;
+}
+function store() {
+  return createSecureKeyringStore(JEV_KEYRING_SERVICE);
+}
+function requireEndpoint(endpoint) {
+  if (endpoint)
+    return endpoint;
+  const resolution = resolveJevEndpoint();
+  if (resolution.status === "unavailable")
+    throw new Error(resolution.message);
+  return resolution.endpoint;
+}
+function parseStoredKey(payload, endpoint) {
+  let value;
+  try {
+    value = JSON.parse(payload);
+  } catch {
+    throw new Error("invalid record");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("invalid record");
+  const record = value;
+  const keys = Object.keys(record);
+  if (record.version === 2) {
+    if (keys.length !== 3 || !["version", "endpoint", "apiKey"].every((key) => Object.hasOwn(record, key)))
+      throw new Error("invalid record fields");
+    if (record.endpoint !== endpoint.href)
+      throw new Error("invalid or mismatched record");
+    return validateApiKey(record.apiKey);
+  }
+  if (record.version === 1) {
+    if (keys.length !== 4 || !["version", "provider", "origin", "apiKey"].every((key) => Object.hasOwn(record, key)))
+      throw new Error("invalid record fields");
+    if (record.provider !== "typesafe" || record.origin !== TYPESAFE_API_ORIGIN)
+      throw new Error("invalid or mismatched record");
+    if (endpoint.href !== JEV_DEFAULT_ENDPOINT)
+      throw new Error("invalid or mismatched record");
+    return validateApiKey(record.apiKey);
+  }
+  throw new Error("invalid record version");
+}
+function readStoredKey(secretStore, endpoint) {
+  try {
+    let payload = secretStore.read(jevKeyringAccount(endpoint));
+    if (payload === undefined && endpoint.href === JEV_DEFAULT_ENDPOINT)
+      payload = secretStore.read(JEV_KEYRING_ACCOUNT);
+    return payload === undefined ? undefined : parseStoredKey(payload, endpoint);
+  } catch (error) {
+    throw new JevCredentialStoreError("read", error);
+  }
+}
+export function resolveJevCredential(env = process.env, endpoint, secretStore = store()) {
+  let target;
+  if (endpoint)
+    target = endpoint;
+  else {
+    const resolution = resolveJevEndpoint(env);
+    if (resolution.status === "unavailable")
+      return resolution;
+    target = resolution.endpoint;
+  }
+  if (Object.hasOwn(env, SYSTEMONE_API_KEY_ENV)) {
+    try {
+      return { status: "present", source: "environment", apiKey: validateApiKey(env[SYSTEMONE_API_KEY_ENV]) };
+    } catch {
+      return { status: "unavailable", message: `${SYSTEMONE_API_KEY_ENV} is present but invalid.` };
+    }
+  }
+  const legacySet = Object.hasOwn(env, LEGACY_TYPESAFE_API_KEY_ENV);
+  if (legacySet && target.href === JEV_DEFAULT_ENDPOINT) {
+    try {
+      return { status: "present", source: "environment", apiKey: validateApiKey(env[LEGACY_TYPESAFE_API_KEY_ENV]) };
+    } catch {
+      return { status: "unavailable", message: `${LEGACY_TYPESAFE_API_KEY_ENV} is present but invalid.` };
+    }
+  }
+  if (target.origin === OPENROUTER_ORIGIN && Object.hasOwn(env, OPENROUTER_API_KEY_ENV)) {
+    try {
+      return { status: "present", source: "environment", apiKey: validateApiKey(env[OPENROUTER_API_KEY_ENV]) };
+    } catch {
+      return { status: "unavailable", message: `${OPENROUTER_API_KEY_ENV} is present but invalid.` };
+    }
+  }
+  let stored;
+  try {
+    stored = readStoredKey(secretStore, target);
+  } catch (error) {
+    if (!(error instanceof JevCredentialStoreError))
+      throw error;
+    return { status: "unavailable", message: error.message };
+  }
+  if (stored !== undefined)
+    return { status: "present", source: "keyring", apiKey: stored };
+  if (legacySet) {
+    return {
+      status: "unavailable",
+      message: `${LEGACY_TYPESAFE_API_KEY_ENV} is a TypeSafe credential and is not sent to ${target.href}; set ${SYSTEMONE_API_KEY_ENV} for that endpoint.`
+    };
+  }
+  return { status: "missing" };
+}
+export function saveJevApiKey(apiKey, endpoint, secretStore = store()) {
+  const target = requireEndpoint(endpoint);
+  const record = { version: 2, endpoint: target.href, apiKey: validateApiKey(apiKey) };
+  try {
+    secretStore.write(jevKeyringAccount(target), JSON.stringify(record));
+  } catch (error) {
+    throw new JevCredentialStoreError("write", error);
+  }
+}
+export function removeJevApiKey(endpoint, secretStore = store()) {
+  const target = requireEndpoint(endpoint);
+  try {
+    secretStore.remove(jevKeyringAccount(target));
+    if (target.href === JEV_DEFAULT_ENDPOINT)
+      secretStore.remove(JEV_KEYRING_ACCOUNT);
+  } catch (error) {
+    throw new JevCredentialStoreError("remove", error);
+  }
+}