@h-ai/core 0.1.0-alpha9 → 1.0.0-beta.10

package/dist/node.js

@@ -1,61 +1,533 @@
-import { createCore, CoreConfigSchema, i18n, err, HaiConfigError, ok, typeUtils } from './chunk-FVCFFZP6.js';
-export { CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, IdConfigSchema, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, err, ok } from './chunk-FVCFFZP6.js';
-import { existsSync, readdirSync, watch, readFileSync } from 'fs';
-import { join } from 'path';
-import process2 from 'process';
+import { installRequestLocales, installRequestContext, createCore, i18n, err, HaiConfigError, ok, RequestAccessConfigSchema, RequestAccessPolicySchema, AccessConditionSchema, requestContext, sanitize, emitLogRecord, sanitizeLogFields, CoreConfigSchema } from './chunk-MYNB4HIZ.js';
+export { AccessConditionSchema, CoreConfigSchema, EnvSchema, HaiCommonError, HaiConfigError, LogFormatSchema, LogLevelSchema, LoggingConfigSchema, RequestAccessConfigSchema, RequestAccessPolicySchema, TrustedProxiesSchema, err, ok } from './chunk-MYNB4HIZ.js';
+import { AsyncLocalStorage } from 'async_hooks';
+import { Buffer } from 'buffer';
+import { timingSafeEqual } from 'crypto';
+import { existsSync, readFileSync, openSync, constants, fstatSync, readSync, closeSync, readdirSync, watch } from 'fs';
+import path, { join, resolve, basename, dirname } from 'path';
+import { BlockList, isIP } from 'net';
+import { networkInterfaces } from 'os';
+import process4 from 'process';
 import { parse } from 'yaml';
+import { parseEnv } from 'util';
 import { execSync } from 'child_process';
+import { createRequire } from 'module';
 import pino from 'pino';
 
-var ENV_VAR_PATTERN = /\$\{([^}:]+)(?::([^}]*))?\}/g;
-var FULL_VAR_PATTERN = /^\$\{[^}:]+(?::[^}]*)?\}$/;
-function interpolateEnv(value) {
-  if (typeof value === "string") {
-    let result = value;
-    ENV_VAR_PATTERN.lastIndex = 0;
-    while (true) {
-      const match = ENV_VAR_PATTERN.exec(value);
-      if (!match)
+var allowed = Object.freeze({ allowed: true });
+var invalidPath = Object.freeze({ allowed: false, reason: "path" });
+var maximumPolicyBytes = 1024 * 1024;
+function normalizeClientIp(value) {
+  if (!value)
+    return void 0;
+  const address = value.trim();
+  if (address.includes("%") || !isIP(address))
+    return void 0;
+  return address.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/i)?.[1] ?? address;
+}
+function addAddress(list, entry) {
+  const [address, prefix, extra] = entry.split("/");
+  const family = address ? isIP(address) : 0;
+  if (!family || address?.includes("%") || extra !== void 0)
+    throw new Error("Expected an IP address or CIDR");
+  const type = family === 4 ? "ipv4" : "ipv6";
+  if (prefix === void 0) {
+    list.addAddress(address, type);
+    return;
+  }
+  const bits = Number(prefix);
+  if (!/^\d+$/.test(prefix) || bits < 0 || bits > (family === 4 ? 32 : 128))
+    throw new Error("Invalid CIDR prefix");
+  list.addSubnet(address, bits, type);
+}
+function createClientIpResolver(trustedProxies = "auto") {
+  const entries = trustedProxies === "auto" ? process4.env.HAI_DEPLOY_PRIVATE_PROXY === "1" ? Object.values(networkInterfaces()).flatMap((interfaces) => interfaces?.filter((value) => !value.internal && value.cidr && !value.cidr.includes("%")).map((value) => value.cidr) ?? []) : [] : trustedProxies;
+  if (trustedProxies === "auto" && process4.env.HAI_DEPLOY_PRIVATE_PROXY === "1" && !entries.length)
+    throw new Error("Private proxy mode requires an isolated container network");
+  const proxies = new BlockList();
+  for (const entry of entries)
+    addAddress(proxies, entry);
+  const trusted = (address) => proxies.check(address, isIP(address) === 4 ? "ipv4" : "ipv6");
+  return (request, remoteAddress) => {
+    const peer = normalizeClientIp(remoteAddress);
+    if (!peer || !entries.length || !trusted(peer))
+      return peer;
+    const forwarded = request.headers.get("x-forwarded-for");
+    if (forwarded === null) {
+      const realIp = request.headers.get("x-real-ip");
+      return realIp === null ? peer : normalizeClientIp(realIp);
+    }
+    if (forwarded.length > 2048)
+      return void 0;
+    const chain = forwarded.split(",");
+    if (chain.length > 32)
+      return void 0;
+    let current = peer;
+    for (let index = chain.length - 1; index >= 0 && trusted(current); index--) {
+      const address = normalizeClientIp(chain[index]);
+      if (!address)
+        return void 0;
+      current = address;
+    }
+    return current;
+  };
+}
+function timeReader(timezone) {
+  const formatter = new Intl.DateTimeFormat("en-US", { timeZone: timezone, weekday: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
+  const weekdays = ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"];
+  let lastMinute = Number.NaN;
+  let local;
+  return (now) => {
+    const minute = Math.floor(now / 6e4);
+    if (minute !== lastMinute) {
+      const parts = Object.fromEntries(formatter.formatToParts(now).map((part) => [part.type, part.value]));
+      local = { day: weekdays.indexOf(parts.weekday) + 1, time: `${parts.hour}:${parts.minute}` };
+      lastMinute = minute;
+    }
+    return local;
+  };
+}
+function compileCondition(condition, readTime, ruleId) {
+  const allow = new BlockList();
+  const deny = new BlockList();
+  for (const entry of condition.allowIps)
+    addAddress(allow, entry);
+  for (const entry of condition.denyIps)
+    addAddress(deny, entry);
+  const addressDenied = Object.freeze({ allowed: false, reason: "address", ruleId });
+  const timeDenied = Object.freeze({ allowed: false, reason: "time", ruleId });
+  const checksAddress = condition.allowIps.length > 0 || condition.denyIps.length > 0;
+  return (ip) => {
+    if (checksAddress) {
+      const address = normalizeClientIp(ip);
+      if (!address)
+        return addressDenied;
+      const family = isIP(address) === 4 ? "ipv4" : "ipv6";
+      if (deny.check(address, family) || condition.allowIps.length && !allow.check(address, family))
+        return addressDenied;
+    }
+    if (readTime) {
+      const { day, time } = readTime(Date.now());
+      const previous = day === 1 ? 7 : day - 1;
+      if (!condition.windows.some((window) => window.start < window.end ? window.days.includes(day) && time >= window.start && time < window.end : window.days.includes(day) && time >= window.start || window.days.includes(previous) && time < window.end)) {
+        return timeDenied;
+      }
+    }
+    return allowed;
+  };
+}
+function createConditionCheck(input) {
+  const condition = AccessConditionSchema.parse(input);
+  return compileCondition(condition, condition.windows.length ? timeReader(condition.timezone) : void 0);
+}
+function loadPolicy(input = false, baseDirectory = process4.cwd()) {
+  const config2 = RequestAccessConfigSchema.parse(input);
+  if (config2 === false || !("file" in config2))
+    return config2;
+  let descriptor;
+  let content;
+  try {
+    descriptor = openSync(path.resolve(baseDirectory, config2.file), constants.O_RDONLY | constants.O_NONBLOCK);
+    const stat = fstatSync(descriptor);
+    if (!stat.isFile() || stat.size > maximumPolicyBytes)
+      throw new Error("Invalid policy file size or type");
+    const bytes = Buffer.alloc(Math.min(stat.size + 1, maximumPolicyBytes + 1));
+    let length = 0;
+    while (length < bytes.length) {
+      const read = readSync(descriptor, bytes, length, bytes.length - length, null);
+      if (!read)
         break;
-      const [fullMatch, varName, defaultValue] = match;
-      const envValue = process2.env[varName];
-      if (envValue === void 0 && defaultValue === void 0) {
-        return err(HaiConfigError.CONFIG_ENV_VAR_MISSING, i18n.coreM("core_configEnvVarMissing", { params: { varName } }));
+      length += read;
+    }
+    if (length > maximumPolicyBytes || length !== stat.size)
+      throw new Error("Policy file changed while reading");
+    content = bytes.subarray(0, length).toString("utf8");
+  } catch {
+    throw new Error("Request access policy file could not be read; use a regular YAML file no larger than 1 MiB");
+  } finally {
+    if (descriptor !== void 0)
+      closeSync(descriptor);
+  }
+  let parsed;
+  try {
+    parsed = parse(content, { maxAliasCount: 0, uniqueKeys: true });
+  } catch {
+    throw new Error("Request access policy YAML is invalid; aliases and duplicate keys are not allowed");
+  }
+  const validated = RequestAccessPolicySchema.safeParse(parsed);
+  if (!validated.success)
+    throw new Error(`Request access policy is invalid at ${validated.error.issues.map((issue) => issue.path.join(".") || "root").join(", ")}`);
+  return validated.data;
+}
+function normalizeRequestPath(value) {
+  if (value.length > 8192)
+    return void 0;
+  let decoded = value;
+  if (value.includes("%")) {
+    if (/%(?:2f|5c|00)/i.test(value))
+      return void 0;
+    try {
+      decoded = decodeURIComponent(value);
+    } catch {
+      return void 0;
+    }
+  }
+  if (!decoded.startsWith("/") || /[\\%?#\u0000-\u0020\u007F]/.test(decoded) || decoded.includes("//"))
+    return void 0;
+  if (/(?:^|\/)\.\.?(?:\/|$)/.test(decoded))
+    return void 0;
+  return decoded.length > 1 && decoded.endsWith("/") ? decoded.slice(0, -1) : decoded;
+}
+function createRequestCheck(input = false) {
+  const policy = loadPolicy(input);
+  if (policy === false)
+    return Object.assign(() => allowed, { encryption: () => void 0, requiresEncryption: false });
+  const clocks = /* @__PURE__ */ new Map();
+  const compile = (condition, id) => {
+    let readTime;
+    if (condition.windows.length) {
+      readTime = clocks.get(condition.timezone) ?? timeReader(condition.timezone);
+      clocks.set(condition.timezone, readTime);
+    }
+    return compileCondition(condition, readTime, id);
+  };
+  const globalCheck = policy.global ? compile(policy.global) : () => allowed;
+  const exact = /* @__PURE__ */ new Map();
+  const prefixes = { children: /* @__PURE__ */ new Map(), rules: [] };
+  const allMethods = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "CONNECT", "TRACE", "*"];
+  let requiresEncryption = false;
+  let hasEncryption = false;
+  for (const rule of policy.rules) {
+    const compiled = { methods: new Set(rule.methods), check: compile(rule, rule.id) };
+    for (const pattern of new Set(rule.paths)) {
+      if (rule.encryption) {
+        hasEncryption = true;
+        requiresEncryption ||= rule.encryption === "required";
+        const prefix = pattern.endsWith("/**");
+        const nodes = [prefixes];
+        let node = prefixes;
+        const path2 = normalizeRequestPath(prefix ? pattern.slice(0, -3) || "/" : pattern);
+        for (const segment2 of path2.split("/").filter(Boolean)) {
+          let child = node.children.get(segment2);
+          if (!child) {
+            child = { children: /* @__PURE__ */ new Map(), rules: [] };
+            node.children.set(segment2, child);
+          }
+          node = child;
+          nodes.push(node);
+        }
+        const bit = rule.encryption === "required" ? 1 : 2;
+        const opposite = bit === 1 ? 2 : 1;
+        const methods = rule.methods.length ? rule.methods : allMethods;
+        for (const method of methods) {
+          if (nodes.some((parent) => parent.encryption?.has(method) && parent.encryption.get(method) !== rule.encryption) || (prefix ? (node.encryptionBelow?.get(method) ?? 0) & opposite : node.exactEncryption?.has(method) && node.exactEncryption.get(method) !== rule.encryption)) {
+            throw new Error(`Request access encryption conflicts at rule ${rule.id}`);
+          }
+          const modes = prefix ? node.encryption ??= /* @__PURE__ */ new Map() : node.exactEncryption ??= /* @__PURE__ */ new Map();
+          modes.set(method, rule.encryption);
+          for (const parent of nodes) {
+            parent.encryptionBelow ??= /* @__PURE__ */ new Map();
+            parent.encryptionBelow.set(method, (parent.encryptionBelow.get(method) ?? 0) | bit);
+          }
+        }
+      }
+      if (pattern.endsWith("/**")) {
+        let node = prefixes;
+        for (const segment2 of pattern.slice(0, -3).split("/").filter(Boolean)) {
+          let child = node.children.get(segment2);
+          if (!child) {
+            child = { children: /* @__PURE__ */ new Map(), rules: [] };
+            node.children.set(segment2, child);
+          }
+          node = child;
+        }
+        node.rules.push(compiled);
+      } else {
+        const path2 = normalizeRequestPath(pattern);
+        const rules = exact.get(path2) ?? [];
+        rules.push(compiled);
+        exact.set(path2, rules);
       }
-      result = result.replace(fullMatch, envValue ?? defaultValue ?? "");
     }
-    if (FULL_VAR_PATTERN.test(value)) {
+  }
+  const check = (pathname, method, ip) => {
+    const global = globalCheck(ip);
+    if (!global.allowed)
+      return global;
+    const path2 = normalizeRequestPath(pathname);
+    if (!path2)
+      return invalidPath;
+    for (const rule of exact.get(path2) ?? []) {
+      if (!rule.methods.size || rule.methods.has(method)) {
+        const decision = rule.check(ip);
+        if (!decision.allowed)
+          return decision;
+      }
+    }
+    let node = prefixes;
+    for (const rule of node.rules) {
+      if (!rule.methods.size || rule.methods.has(method)) {
+        const decision = rule.check(ip);
+        if (!decision.allowed)
+          return decision;
+      }
+    }
+    if (node.children.size) {
+      for (const segment2 of path2.split("/").filter(Boolean)) {
+        node = node.children.get(segment2);
+        if (!node)
+          break;
+        for (const rule of node.rules) {
+          if (!rule.methods.size || rule.methods.has(method)) {
+            const decision = rule.check(ip);
+            if (!decision.allowed)
+              return decision;
+          }
+        }
+      }
+    }
+    return allowed;
+  };
+  const encryption = (pathname, method) => {
+    const path2 = normalizeRequestPath(pathname);
+    if (!path2)
+      return void 0;
+    let node = prefixes;
+    let mode = node.encryption?.get(method) ?? node.encryption?.get("*");
+    for (const segment2 of path2.split("/").filter(Boolean)) {
+      node = node.children.get(segment2);
+      if (!node)
+        return mode;
+      mode ??= node.encryption?.get(method) ?? node.encryption?.get("*");
+    }
+    return mode ?? node?.exactEncryption?.get(method) ?? node?.exactEncryption?.get("*");
+  };
+  return Object.assign(check, { encryption: hasEncryption ? encryption : () => void 0, requiresEncryption });
+}
+var access = { normalizeClientIp, createClientIpResolver, createConditionCheck, createRequestCheck, loadPolicy };
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function segment(value) {
+  return value.replace(/[^a-z0-9]+/gi, "_").replace(/^_+|_+$/g, "").toUpperCase();
+}
+function shapes(node, root, value, depth = 0) {
+  if (depth > 32)
+    return [];
+  const result = [node];
+  if (typeof node.$ref === "string" && node.$ref.startsWith("#/")) {
+    let target = root;
+    for (const key of node.$ref.slice(2).split("/").map((item) => item.replaceAll("~1", "/").replaceAll("~0", "~")))
+      target = object(target)?.[key];
+    if (object(target))
+      result.push(...shapes(object(target), root, value, depth + 1));
+  }
+  for (const keyword of ["anyOf", "oneOf", "allOf"]) {
+    if (!Array.isArray(node[keyword]))
+      continue;
+    for (const item of node[keyword]) {
+      const branch = object(item);
+      if (!branch)
+        continue;
+      const fields = object(branch.properties);
+      const input = object(value);
+      if (fields && input && Object.entries(fields).some(([key, field]) => input[key] !== void 0 && object(field)?.const !== void 0 && object(field).const !== input[key]))
+        continue;
+      result.push(...shapes(branch, root, value, depth + 1));
+    }
+  }
+  return result;
+}
+function combined(nodes) {
+  const entries = nodes.map(object).filter((item) => item !== void 0);
+  return entries.length === 1 ? entries[0] : { anyOf: entries };
+}
+function scalar(text, node, root) {
+  const types = new Set(shapes(node, root).flatMap((item) => Array.isArray(item.type) ? item.type : typeof item.type === "string" ? [item.type] : []));
+  if (types.has("string") && [...types].every((type) => type === "string" || type === "null") && !(text === "null" && types.has("null")))
+    return text;
+  if (text === "")
+    return "";
+  try {
+    return parse(text) ?? (text === "null" ? null : text);
+  } catch {
+    return text;
+  }
+}
+function mergeEnv(layers) {
+  const values = {};
+  for (const layer of layers) {
+    for (const name of Object.keys(layer).sort((left, right) => left.length - right.length || left.localeCompare(right))) {
+      if (layer[name] === void 0)
+        continue;
+      if (name.startsWith("HAI_")) {
+        for (const previous of Object.keys(values)) {
+          if (previous.startsWith(`${name}_`))
+            delete values[previous];
+        }
+      }
+      values[name] = layer[name];
+    }
+  }
+  return values;
+}
+function parseEnvironment(text) {
+  const result = parseEnv(text);
+  const names = /* @__PURE__ */ new Set();
+  const assignments = /^(?:export\s+)?([A-Z_]\w*)\s*=\s*('[^']*'|"(?:[^"\\]|\\.)*"|`[^`]*`|[^\r\n]*)/gim;
+  for (const match of text.matchAll(assignments)) {
+    const name = match[1];
+    if (names.has(name))
+      throw new Error(`Duplicate environment variable: ${name}`);
+    names.add(name);
+    if (match[2].startsWith('"') && (match[2].includes('\\"') || match[2].includes("\\u0027"))) {
       try {
-        const coerced = parse(result);
-        if (coerced !== void 0)
-          return ok(coerced);
+        result[name] = JSON.parse(match[2]);
       } catch {
       }
     }
-    return ok(result);
   }
-  if (Array.isArray(value)) {
-    const results = [];
-    for (const item of value) {
-      const r = interpolateEnv(item);
-      if (!r.success)
-        return r;
-      results.push(r.data);
+  return Object.fromEntries(Object.entries(result).filter((entry) => entry[1] !== void 0));
+}
+function stringifyEnv(values, options = {}) {
+  return `${Object.keys(values).sort().map((name) => {
+    if (!/^[A-Z_]\w*$/i.test(name))
+      throw new Error("Invalid environment variable name");
+    const value = values[name];
+    let literal;
+    if (!value.includes("'"))
+      literal = `'${value}'`;
+    else if (options.target === "compose")
+      literal = JSON.stringify(value).replaceAll("$", () => "$$");
+    else literal = JSON.stringify(value).replaceAll("'", "\\u0027");
+    return `${name}=${literal}`;
+  }).join("\n")}
+`;
+}
+function resolveEnvironment(options, literal = false) {
+  const environment = options.environment ?? process4.env;
+  const missingNames = /* @__PURE__ */ new Set();
+  let root;
+  try {
+    root = options.schema ? options.schema.toJSONSchema({ io: "input", unrepresentable: "any" }) : options.shape ?? {};
+  } catch {
+    root = {};
+  }
+  const prefix = `HAI_${segment(options.name)}`;
+  function visit(original, name, node, inheritedLiteral, depth, declaration = original) {
+    if (depth > 32)
+      throw new Error(name);
+    let value = original;
+    let fromEnvironment = inheritedLiteral;
+    if (environment[name] !== void 0) {
+      value = scalar(environment[name], node, root);
+      fromEnvironment = true;
+    }
+    const alternatives = shapes(node, root);
+    const discriminators = /* @__PURE__ */ new Map();
+    for (const candidate of alternatives) {
+      for (const [key, field] of Object.entries(object(candidate.properties) ?? {})) {
+        if (shapes(object(field) ?? {}, root).some((item) => Object.hasOwn(item, "const")))
+          discriminators.set(key, [...discriminators.get(key) ?? [], field]);
+      }
+    }
+    const selection = { ...object(value) };
+    for (const [key, fields] of discriminators) {
+      const text = environment[`${name}_${segment(key)}`];
+      if (text !== void 0)
+        selection[key] = scalar(text, combined(fields), root);
+    }
+    const candidates = shapes(node, root, Object.keys(selection).length ? selection : value);
+    const synthesized = value === void 0;
+    const valueType = typeof value;
+    const primitiveOverride = value === void 0 || candidates.some((candidate) => value !== null && candidate.type === valueType || candidate.const === value || value === null && candidate.type === "null");
+    if (primitiveOverride && !object(value) && !Array.isArray(value)) {
+      const declared = /* @__PURE__ */ new Set([...Object.keys(object(declaration) ?? {}), ...candidates.flatMap((candidate) => Object.keys(object(candidate.properties) ?? {}))]);
+      const specified = [...declared].filter((key) => Object.keys(environment).some((candidate) => environment[candidate] !== void 0 && (candidate === `${name}_${segment(key)}` || candidate.startsWith(`${name}_${segment(key)}_`))));
+      if (specified.length)
+        value = Object.fromEntries(specified.map((key) => [key, void 0]));
     }
-    return ok(results);
+    if (value === void 0 && Object.keys(environment).some((key) => environment[key] !== void 0 && key.startsWith(`${name}_`))) {
+      if (candidates.some((item) => item.type === "object" || object(item.properties)))
+        value = {};
+    }
+    const indexed = Object.keys(environment).filter((key) => environment[key] !== void 0 && key.startsWith(`${name}_`) && /^\d+(?:_|$)/.test(key.slice(name.length + 1)));
+    if (value === void 0 && indexed.length && candidates.some((candidate) => candidate.type === "array")) {
+      const defaults = candidates.find((candidate) => Array.isArray(candidate.default))?.default;
+      if (!Array.isArray(defaults))
+        throw new Error(indexed[0]);
+      value = structuredClone(defaults);
+    }
+    if (Array.isArray(value)) {
+      const itemShape = combined(candidates.map((item) => item.items));
+      for (const key of indexed) {
+        const index = key.slice(name.length + 1).split("_")[0];
+        if (/^\d+$/.test(index) && (String(Number(index)) !== index || Number(index) >= value.length))
+          throw new Error(key);
+      }
+      return value.map((item, index) => visit(item, `${name}_${index}`, itemShape, fromEnvironment, depth + 1, Array.isArray(declaration) ? declaration[index] : void 0));
+    }
+    const input = object(value);
+    if (input) {
+      const properties = /* @__PURE__ */ new Map();
+      for (const candidate of candidates) {
+        for (const [key, field] of Object.entries(object(candidate.properties) ?? {}))
+          properties.set(key, [...properties.get(key) ?? [], field]);
+      }
+      const declaredKeys = /* @__PURE__ */ new Set([...Object.keys(object(declaration) ?? {}), ...properties.keys()]);
+      const keys = /* @__PURE__ */ new Set([...Object.keys(input), ...[...declaredKeys].filter((key) => Object.keys(environment).some((nameInEnv) => environment[nameInEnv] !== void 0 && (nameInEnv === `${name}_${segment(key)}` || nameInEnv.startsWith(`${name}_${segment(key)}_`))))]);
+      const entries = [...keys].map((key) => {
+        if (["__proto__", "prototype", "constructor"].includes(key))
+          throw new Error(name);
+        return [key, visit(input[key], `${name}_${segment(key)}`, combined(properties.get(key) ?? candidates.map((candidate) => candidate.additionalProperties)), fromEnvironment, depth + 1, object(declaration)?.[key])];
+      }).filter(([, child]) => child !== void 0);
+      return synthesized && !entries.length ? void 0 : Object.fromEntries(entries);
+    }
+    if (typeof value !== "string" || fromEnvironment)
+      return value;
+    const full = /^\$\{[^}:]+(?::[^}]*)?\}$/.test(value);
+    const resolved = value.replace(/\$\{([^}:]+)(?::([^}]*))?\}/g, (_match, key, fallback) => {
+      if (environment[key] === void 0 && fallback === void 0 && options.missing !== "empty") {
+        missingNames.add(key);
+        throw new Error(key);
+      }
+      return environment[key] ?? fallback ?? "";
+    });
+    return full ? scalar(resolved, node, root) : resolved;
+  }
+  try {
+    return ok(visit(options.value, prefix, root, literal, 0));
+  } catch (failure) {
+    const name = failure instanceof Error && /^[A-Z_]\w*$/i.test(failure.message) ? failure.message : prefix;
+    if (!missingNames.has(name))
+      return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"), { fields: [name] });
+    return err(HaiConfigError.CONFIG_ENV_VAR_MISSING, i18n.coreM("core_configEnvVarMissing", { params: { varName: name } }));
   }
-  if (typeUtils.isObject(value)) {
-    const results = {};
-    for (const [k, v] of Object.entries(value)) {
-      const r = interpolateEnv(v);
-      if (!r.success)
-        return r;
-      results[k] = r.data;
+}
+function toEnv(options) {
+  const result = {};
+  const root = options.schema ? options.schema.toJSONSchema({ io: "input", unrepresentable: "any" }) : options.shape ?? {};
+  function visit(value, name, node) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name))
+      throw new Error("Invalid environment variable name");
+    if (value === void 0)
+      return;
+    const input = object(value);
+    const candidates = shapes(node, root, value);
+    const properties = Object.assign({}, ...candidates.map((candidate) => object(candidate.properties) ?? {}));
+    const dynamic = candidates.some((candidate) => candidate.additionalProperties === true || object(candidate.additionalProperties));
+    if (input && Object.keys(input).length && !dynamic && Object.keys(input).every((key) => /^[a-z][a-zA-Z0-9]*$/.test(key))) {
+      for (const [key, item] of Object.entries(input))
+        visit(item, `${name}_${segment(key)}`, object(properties[key]) ?? {});
+    } else {
+      result[name] = value === null || typeof value === "object" ? JSON.stringify(value) : String(value);
     }
-    return ok(results);
   }
-  return ok(value);
+  visit(options.value, options.prefix, root);
+  return result;
 }
+
+// src/functions/core-function-config.node.ts
 var configCache = /* @__PURE__ */ new Map();
 var watchEntries = /* @__PURE__ */ new Map();
 function createNotLoadedError(name) {
@@ -84,20 +556,20 @@ function notifyWatchCallbacks(name, result) {
     }
   }
 }
-function loadYaml(filePath) {
+function loadYaml(name, filePath, schema) {
   if (!existsSync(filePath)) {
     return err(HaiConfigError.CONFIG_FILE_NOT_FOUND, i18n.coreM("core_configFileNotExist", { params: { filePath } }));
   }
   try {
     const content = readFileSync(filePath, "utf-8");
     const parsed = parse(content);
-    return interpolateEnv(parsed);
+    return resolveEnvironment({ name, value: parsed, schema });
   } catch (error) {
     return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", { params: { filePath } }), error);
   }
 }
-function loadConfig(filePath, schema) {
-  const yamlResult = loadYaml(filePath);
+function loadConfig(name, filePath, schema) {
+  const yamlResult = loadYaml(name, filePath, schema);
   if (!yamlResult.success)
     return yamlResult;
   const parseResult = schema.safeParse(yamlResult.data);
@@ -107,7 +579,7 @@ function loadConfig(filePath, schema) {
   return ok(parseResult.data);
 }
 function loadAndCache(name, filePath, schema) {
-  const result = schema ? loadConfig(filePath, schema) : loadYaml(filePath);
+  const result = schema ? loadConfig(name, filePath, schema) : loadYaml(name, filePath);
   if (result.success) {
     configCache.set(name, {
       data: result.data,
@@ -118,12 +590,21 @@ function loadAndCache(name, filePath, schema) {
   }
   return result;
 }
+function loadConfigStructure(name, filePath, schemaHint) {
+  const result = loadYaml(name, filePath, schemaHint);
+  if (result.success)
+    configCache.set(name, { data: result.data, filePath, schemaHint, loadedAt: Date.now() });
+  return result;
+}
 function validateLoadedConfig(name, schema) {
   const entry = configCache.get(name);
   if (!entry) {
     return err(createNotLoadedError(name));
   }
-  const parseResult = schema.safeParse(entry.data);
+  const resolved = resolveEnvironment({ name, value: entry.data, schema }, true);
+  if (!resolved.success)
+    return resolved;
+  const parseResult = schema.safeParse(resolved.data);
   if (!parseResult.success) {
     return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"), parseResult.error.issues);
   }
@@ -143,7 +624,7 @@ function reloadAndNotify(name) {
     notifyWatchCallbacks(name, result2);
     return result2;
   }
-  const result = entry.schema ? loadConfig(entry.filePath, entry.schema) : loadYaml(entry.filePath);
+  const result = entry.schema ? loadConfig(name, entry.filePath, entry.schema) : loadYaml(name, entry.filePath, entry.schemaHint);
   if (result.success) {
     configCache.set(name, {
       ...entry,
@@ -167,15 +648,18 @@ function startFileWatcher(name) {
       callbacks: /* @__PURE__ */ new Set(),
       debounceTimer: null
     };
-    const watcher = watch(entry.filePath, (eventType) => {
-      if (eventType === "change") {
-        if (watchEntry.debounceTimer)
-          clearTimeout(watchEntry.debounceTimer);
-        watchEntry.debounceTimer = setTimeout(() => {
-          watchEntry.debounceTimer = null;
+    const filePath = resolve(entry.filePath);
+    const fileName = basename(filePath);
+    const watcher = watch(dirname(filePath), (_eventType, changedName) => {
+      if (changedName !== null && changedName.toString() !== fileName)
+        return;
+      if (watchEntry.debounceTimer)
+        clearTimeout(watchEntry.debounceTimer);
+      watchEntry.debounceTimer = setTimeout(() => {
+        watchEntry.debounceTimer = null;
+        if (watchEntries.get(name) === watchEntry)
           reloadAndNotify(name);
-        }, 100);
-      }
+      }, 100);
     });
     watchEntry.watcher = watcher;
     watchEntries.set(name, watchEntry);
@@ -194,7 +678,7 @@ function registerWatch(name, callback) {
   entry.callbacks.add(callback);
   return () => {
     const current = watchEntries.get(name);
-    if (!current)
+    if (current !== entry)
       return;
     current.callbacks.delete(callback);
     if (current.callbacks.size === 0) {
@@ -233,6 +717,101 @@ function clearCache(name) {
   }
 }
 var config = {
+  /**
+   * 合并从低到高的环境来源；高来源父项替换旧节点，同来源细项覆盖父 JSON。
+   * @param layers - 按优先级排列的字面变量。
+   * @returns 合并后的变量，可能含秘密。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.mergeEnv([{ HAI_APP_NAME: 'base' }, { HAI_APP_NAME: 'test' }])
+   * ```
+   */
+  mergeEnv,
+  /**
+   * 解析 dotenv 字面文本，拒绝重复键，不执行 shell 或变量展开。
+   * @param text - dotenv 文本，可能包含秘密。
+   * @returns 字面变量；重复键抛出不含变量值的错误。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.parseEnv('HAI_APP_NAME=Example\n')
+   * ```
+   */
+  parseEnv: parseEnvironment,
+  /**
+   * 无损编码 dotenv，父变量排在细项前；含秘密时只能写入受保护文件。
+   * @param values - 字面变量，不进行脱敏。
+   * @param options - 输出语法目标，默认 Node dotenv。
+   * @param options.target - Compose 目标同时处理其美元符号插值规则。
+   * @returns dotenv 文本；非法变量名抛错。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.stringifyEnv({ HAI_APP_NAME: 'Example' })
+   * ```
+   */
+  stringifyEnv,
+  /**
+   * 按已有结构或 Schema 解析父 JSON 和细项，不修改缓存或进程环境。
+   * @param options - 配置名、原始结构、变量、可选 Schema 和缺失插值规则。
+   * @returns 解析结果；调用方仍须执行最终 Schema 校验。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.resolve({ name: 'app', value: { name: 'Example' }, environment: { HAI_APP_NAME: 'Test' } })
+   * ```
+   */
+  resolve: (options) => resolveEnvironment(options),
+  /**
+   * 默认将对象展开为细项；数组、动态字典和空对象保留 JSON。
+   * @param options - 完整变量前缀、配置值和可选 Schema。
+   * @returns 字面环境变量，不脱敏；非法名称抛错。
+   * @example
+   * ```ts
+   * import { core } from '@h-ai/core'
+   * const value = core.config.toEnv({ prefix: 'HAI_APP', value: { name: 'Example', tags: ['demo'] } })
+   * ```
+   */
+  toEnv,
+  /**
+   * 读取 dotenv 文件并按统一顺序合并，不修改进程环境。
+   *
+   * 优先级：已有进程环境 > .env.<mode>.local > .env.local > .env.<mode> > .env。
+   * development/production 分别映射到 dev/prod；不存在的文件跳过。
+   * 返回值可能包含私有配置，仅在 Node 启动/构建边界注入，不下发浏览器。
+   * @param options - 文件所在目录及环境模式
+   * @param options.mode - dev/test/prod 或 Vite 的 development/production
+   * @param options.envDir - dotenv 所在目录，默认进程工作目录
+   * @returns 已合并的变量；非法模式或读取失败返回配置错误，不包含文件内容
+   * @example
+   * ```ts
+   * const env = core.config.loadEnvFiles({ mode: 'dev', envDir: '.' })
+   * if (!env.success) throw new Error(env.error.message)
+   * Object.assign(process.env, env.data)
+   * core.init({ configDir: './config' })
+   * ```
+   */
+  loadEnvFiles(options) {
+    const mode = options.mode === "development" ? "dev" : options.mode === "production" ? "prod" : options.mode;
+    if (!/^[a-z0-9][\w-]*$/i.test(mode))
+      return err(HaiConfigError.CONFIG_VALIDATION_ERROR, i18n.coreM("core_configValidationFailed"));
+    const envDir = options.envDir ?? process4.cwd();
+    try {
+      const layers = [];
+      for (const name of [".env", `.env.${mode}`, ".env.local", `.env.${mode}.local`]) {
+        const file = join(envDir, name);
+        if (existsSync(file))
+          layers.push(parseEnvironment(readFileSync(file, "utf8")));
+      }
+      const declared = new Set(layers.flatMap((layer) => Object.keys(layer)));
+      layers.push(Object.fromEntries(Object.entries(process4.env).filter(([name]) => declared.has(name) || name.startsWith("HAI_"))));
+      const merged = mergeEnv(layers);
+      return ok(merged);
+    } catch {
+      return err(HaiConfigError.CONFIG_PARSE_ERROR, i18n.coreM("core_configParseFailed", { params: { filePath: envDir } }));
+    }
+  },
   /**
    * 加载配置到缓存。
    *
@@ -376,7 +955,8 @@ var config = {
   /**
    * 监听配置文件变更并自动重载。
    *
-   * 文件变更时自动重新加载并调用回调。配置未加载时立即回调 NOT_LOADED 错误。
+   * 普通写入、原子替换及删除重建均触发重载；失败保留最近成功的缓存并通知错误。
+   * 配置未加载时立即回调 NOT_LOADED 错误。
    *
    * @param name - 配置名称
    * @param callback - 配置变更回调，接收新配置或错误
@@ -426,18 +1006,16 @@ var config = {
     return watchEntries.has(name);
   }
 };
-if (process2.platform === "win32" && process2.stdout.isTTY) {
+var nodeRequire = createRequire(import.meta.url);
+if (process4.platform === "win32" && process4.stdout.isTTY) {
   try {
     execSync("chcp 65001 > nul", { stdio: "ignore" });
-    if (process2.stdout.setDefaultEncoding) {
-      process2.stdout.setDefaultEncoding("utf8");
+    if (process4.stdout.setDefaultEncoding) {
+      process4.stdout.setDefaultEncoding("utf8");
     }
-    if (process2.stderr.setDefaultEncoding) {
-      process2.stderr.setDefaultEncoding("utf8");
+    if (process4.stderr.setDefaultEncoding) {
+      process4.stderr.setDefaultEncoding("utf8");
     }
-    process2.env.LANG = "zh_CN.UTF-8";
-    process2.env.LC_ALL = "zh_CN.UTF-8";
-    process2.env.PYTHONIOENCODING = "utf-8";
   } catch (_e) {
   }
 }
@@ -445,17 +1023,21 @@ var globalLevel = "info";
 var globalFormat = "pretty";
 var globalContext = {};
 var globalRedact = [];
+var outputRevision = 0;
 var defaultLogger = null;
 function configureLogger(config2) {
   if (config2.level)
     globalLevel = config2.level;
-  if (config2.format)
+  if (config2.format) {
     globalFormat = config2.format;
+    outputRevision++;
+  }
   if (config2.context)
     globalContext = { ...globalContext, ...config2.context };
-  if (config2.redact)
-    globalRedact = config2.redact;
-  defaultLogger = null;
+  if (config2.redact) {
+    globalRedact = [...config2.redact];
+    outputRevision++;
+  }
 }
 function setLogLevel(level) {
   globalLevel = level;
@@ -463,35 +1045,68 @@ function setLogLevel(level) {
 function getLogLevel() {
   return globalLevel;
 }
-function wrapPino(pinoLogger, context) {
+function sanitizeLogContext(ctx) {
+  if (!ctx || Object.keys(ctx).length === 0) {
+    return ctx;
+  }
+  return sanitizeLogFields(ctx, globalRedact);
+}
+function wrapPino(resolvePino, resolveContext) {
+  const write = (level, message, ctx) => {
+    const output = resolvePino();
+    if (!output.isLevelEnabled(level))
+      return;
+    const context = sanitizeLogContext({ ...resolveContext(), ...ctx, ...requestContext.get() }) ?? {};
+    message = sanitize.sanitizeText(message);
+    output[level](context, message);
+    if (!requestContext.get().suppressLogObservers)
+      emitLogRecord({ timestamp: Date.now(), level, message, context });
+  };
   return {
     trace(message, ctx) {
-      pinoLogger.trace({ ...context, ...ctx }, message);
+      write("trace", message, ctx);
     },
     debug(message, ctx) {
-      pinoLogger.debug({ ...context, ...ctx }, message);
+      write("debug", message, ctx);
     },
     info(message, ctx) {
-      pinoLogger.info({ ...context, ...ctx }, message);
+      write("info", message, ctx);
     },
     warn(message, ctx) {
-      pinoLogger.warn({ ...context, ...ctx }, message);
+      write("warn", message, ctx);
     },
     error(message, ctx) {
-      pinoLogger.error({ ...context, ...ctx }, message);
+      write("error", message, ctx);
     },
     fatal(message, ctx) {
-      pinoLogger.fatal({ ...context, ...ctx }, message);
+      write("fatal", message, ctx);
     },
     child(childContext) {
-      return wrapPino(pinoLogger.child(childContext), { ...context, ...childContext });
+      return wrapPino(resolvePino, () => ({ ...resolveContext(), ...childContext }));
     }
   };
 }
 function createLogger(options = {}) {
+  const localOptions = { ...options, context: { ...options.context } };
+  let revision = outputRevision;
+  let output = createPinoOutput(localOptions);
+  const resolvePino = () => {
+    if (revision !== outputRevision) {
+      const updated = createPinoOutput(localOptions);
+      output.close();
+      output = updated;
+      revision = outputRevision;
+    }
+    const level = localOptions.level ?? globalLevel;
+    if (output.instance.level !== level)
+      output.instance.level = level;
+    return output.instance;
+  };
+  return wrapPino(resolvePino, () => ({ ...globalContext, ...localOptions.context }));
+}
+function createPinoOutput(options) {
   const level = options.level ?? globalLevel;
   const format = options.format ?? globalFormat;
-  const context = { ...globalContext, ...options.context };
   const pinoOptions = {
     level,
     name: options.name,
@@ -506,22 +1121,44 @@ function createLogger(options = {}) {
     };
   }
   let pinoInstance;
-  if (format === "pretty") {
-    pinoInstance = pino({
-      ...pinoOptions,
-      transport: {
+  let transport;
+  if (format === "pretty" && isPrettyTransportAvailable()) {
+    try {
+      transport = pino.transport({
         target: "pino-pretty",
         options: {
           colorize: true,
           translateTime: "SYS:standard",
           ignore: "pid,hostname"
         }
+      });
+      pinoInstance = pino(pinoOptions, transport);
+      if ("unref" in transport && typeof transport.unref === "function")
+        transport.unref();
+    } catch (error) {
+      if (isPrettyTransportUnavailable(error)) {
+        pinoInstance = pino(pinoOptions);
+      } else {
+        throw error;
       }
-    });
+    }
   } else {
     pinoInstance = pino(pinoOptions);
   }
-  return wrapPino(pinoInstance, context);
+  return { instance: pinoInstance, close: () => transport?.end() };
+}
+function isPrettyTransportAvailable() {
+  try {
+    nodeRequire.resolve("pino-pretty");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isPrettyTransportUnavailable(error) {
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : "";
+  const normalized = message.toLowerCase();
+  return normalized.includes("pino-pretty") && (normalized.includes("cannot find module") || normalized.includes("unable to determine transport target") || normalized.includes("cannot load") || normalized.includes("not found"));
 }
 function getLogger() {
   if (!defaultLogger) {
@@ -538,6 +1175,9 @@ var logger = {
 };
 
 // src/core-main.node.ts
+installRequestLocales(new AsyncLocalStorage());
+installRequestContext(new AsyncLocalStorage());
+var YAML_EXTENSION_REGEX = /\.ya?ml$/;
 function createNodeCore() {
   const baseCore = createCore({
     createLogger: logger.createLogger,
@@ -548,6 +1188,28 @@ function createNodeCore() {
   });
   return {
     ...baseCore,
+    /** Node 专属的可信地址、策略文件读取与已编译访问检查。 */
+    access,
+    string: {
+      ...baseCore.string,
+      /**
+       * Node 凭证比较使用原生恒时原语；不同长度直接失败，长度本身不受保护。
+       * UTF-16LE 保留孤立代理项，避免 UTF-8 替换字符把两个不同字符串误判为相等。
+       * @param a - 第一个原始字符串，不做 Unicode 归一化。
+       * @param b - 第二个原始字符串，不做 Unicode 归一化。
+       * @returns 字符串的 UTF-16 单元是否完全一致。
+       * @example
+       * ```ts
+       * import { core } from '@h-ai/core'
+       * const matches = core.string.constantTimeEqual('example-only', 'example-only')
+       * ```
+       */
+      constantTimeEqual(a, b) {
+        return a.length === b.length && timingSafeEqual(Buffer.from(a, "utf16le"), Buffer.from(b, "utf16le"));
+      }
+    },
+    /** Zod 校验错误 → i18n 消息映射工具（kit / serv / api-client 共享）。 */
+    zodValidation: baseCore.zodValidation,
     /** 配置管理 */
     config,
     /** 初始化 Core */
@@ -567,7 +1229,7 @@ function scanConfigDir(configDir) {
   );
   for (const file of files) {
     const filePath = join(configDir, file);
-    const baseName = file.replace(/\.ya?ml$/, "");
+    const baseName = file.replace(YAML_EXTENSION_REGEX, "");
     if (baseName.startsWith("_")) {
       const moduleName = baseName.slice(1);
       items.push({
@@ -589,11 +1251,11 @@ function initCore(options = {}) {
   if (options.logging) {
     core.logger.configure(options.logging);
   }
-  logger2.info("[core] Initializing...");
   let configItems = [];
   if (options.configDir) {
     configItems = scanConfigDir(options.configDir);
   }
+  configItems.sort((left, right) => Number(right.name === "core") - Number(left.name === "core"));
   for (const item of configItems) {
     if (item.name === "core") {
       const result = config.load(item.name, item.filePath, CoreConfigSchema);
@@ -608,7 +1270,7 @@ function initCore(options = {}) {
         });
       }
     } else {
-      const result = config.load(item.name, item.filePath);
+      const result = loadConfigStructure(item.name, item.filePath, options.configSchemas?.[item.name]);
       if (result.success) {
         logger2.info(`[core] Config loaded: ${item.name} <- ${item.filePath}`);
       } else {