blun-king-cli 9.1.587 → 9.1.588

package/standard-skills/translate-native/integrations/adapters/node-language-guard.js

@@ -0,0 +1,230 @@
+"use strict";
+
+const net = require("node:net");
+
+const MAX_BYTES = 8 * 1024 * 1024;
+const EXACT_LANGUAGE = /^(?:[A-Za-z]{2,8}|x)(?:-[A-Za-z0-9]{1,8})*$/;
+const TRANSLATION_OPERATIONS = new Set([
+  "translate", "translation", "localize", "localization", "transcreate",
+  "translation-review", "translation-proofread", "i18n", "l10n",
+]);
+const RESPONSE_OPERATIONS = new Set(["respond", "response", "chat", "answer", "compose"]);
+const HOST_FIELDS = new Set([
+  "task_kind", "language", "source_text", "content_type",
+  "short_text_reviewed", "key_path", "delivery_channel",
+]);
+
+class LanguageGuardBlocked extends Error {
+  constructor(message, code = "language_guard_blocked") {
+    super(message);
+    this.name = "LanguageGuardBlocked";
+    this.code = code;
+  }
+}
+
+function strictString(value, field, required = false) {
+  if (value === undefined || value === null) return "";
+  if (typeof value !== "string") throw new LanguageGuardBlocked(`${field} must be a string`, "invalid_host_context");
+  if (required && !value.trim()) throw new LanguageGuardBlocked(`${field} is required`, "invalid_host_context");
+  return value;
+}
+
+function routeHostContext(context = {}) {
+  if (!context || typeof context !== "object" || Array.isArray(context)) {
+    throw new LanguageGuardBlocked("host context must be an object", "invalid_host_context");
+  }
+  const explicit = strictString(context.task_kind, "task_kind").trim().toLowerCase();
+  const operation = strictString(context.operation, "operation").trim().toLowerCase();
+  const sourceText = strictString(context.source_text, "source_text");
+  const contentType = strictString(context.content_type, "content_type").trim() || "prose";
+  if (!new Set(["prose", "title", "meta_description", "ui"]).has(contentType)) {
+    throw new LanguageGuardBlocked("invalid content_type", "invalid_host_context");
+  }
+  const translationEvidence = Boolean(sourceText.trim()) || TRANSLATION_OPERATIONS.has(operation);
+  let taskKind;
+  if (explicit) {
+    if (!new Set(["response", "translation"]).has(explicit)) {
+      throw new LanguageGuardBlocked("invalid task_kind", "invalid_host_context");
+    }
+    taskKind = explicit;
+  } else if (translationEvidence) taskKind = "translation";
+  else if (!operation || RESPONSE_OPERATIONS.has(operation)) taskKind = "response";
+  else throw new LanguageGuardBlocked("unknown host operation", "invalid_host_context");
+
+  if (taskKind === "translation" && !sourceText.trim()) {
+    throw new LanguageGuardBlocked("translation route requires complete source_text", "invalid_host_context");
+  }
+  if (taskKind === "response" && sourceText.trim()) {
+    throw new LanguageGuardBlocked("source_text cannot be downgraded to response", "mode_confusion");
+  }
+  if (taskKind === "response" && TRANSLATION_OPERATIONS.has(operation)) {
+    throw new LanguageGuardBlocked("translation operation cannot be downgraded to response", "mode_confusion");
+  }
+  if (taskKind === "translation" && RESPONSE_OPERATIONS.has(operation)) {
+    throw new LanguageGuardBlocked("response operation conflicts with translation source", "mode_confusion");
+  }
+  const language = strictString(
+    taskKind === "translation"
+      ? (context.target_language || context.language)
+      : (context.response_language || context.language),
+    taskKind === "translation" ? "target_language" : "response_language",
+    true,
+  ).trim();
+  if (["auto", "all"].includes(language.toLowerCase()) || !EXACT_LANGUAGE.test(language)) {
+    throw new LanguageGuardBlocked("exact language or locale is required", "invalid_host_context");
+  }
+  return { taskKind, language, sourceText: taskKind === "translation" ? sourceText : "", contentType };
+}
+
+function parseAgentEnvelope(raw) {
+  const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw ?? "");
+  if (Buffer.byteLength(text, "utf8") > MAX_BYTES) {
+    throw new LanguageGuardBlocked("agent envelope is too large", "invalid_envelope");
+  }
+  let envelope;
+  try {
+    envelope = JSON.parse(text.replace(/^\uFEFF/, ""));
+  } catch {
+    throw new LanguageGuardBlocked("agent output is not one JSON release envelope", "invalid_envelope");
+  }
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    throw new LanguageGuardBlocked("agent envelope must be an object", "invalid_envelope");
+  }
+  for (const field of Object.keys(envelope)) {
+    if (HOST_FIELDS.has(field)) {
+      throw new LanguageGuardBlocked(`agent attempted to override host field ${field}`, "host_override");
+    }
+    if (!new Set(["target_text", "release_token"]).has(field)) {
+      throw new LanguageGuardBlocked(`unsupported agent envelope field ${field}`, "invalid_envelope");
+    }
+  }
+  if (typeof envelope.target_text !== "string" || !envelope.target_text.trim()) {
+    throw new LanguageGuardBlocked("target_text is required", "invalid_envelope");
+  }
+  if (typeof envelope.release_token !== "string" || !envelope.release_token.trim()) {
+    throw new LanguageGuardBlocked("release_token is required", "invalid_envelope");
+  }
+  return envelope;
+}
+
+function endpointOptions(endpoint) {
+  const value = String(endpoint || "").trim();
+  if (value.startsWith("unix:") && value.slice(5)) return { path: value.slice(5) };
+  if (value.startsWith("tcp:")) {
+    const match = /^tcp:(127\.0\.0\.1|localhost|::1):(\d+)$/.exec(value);
+    const port = match ? Number(match[2]) : 0;
+    if (match && port >= 1 && port <= 65535) return { host: match[1], port };
+  }
+  throw new LanguageGuardBlocked("invalid isolated guard endpoint", "guard_unavailable");
+}
+
+function callGuardService(endpoint, request, { serviceToken = "", timeoutMs = 10000 } = {}) {
+  const payload = { ...request };
+  if (serviceToken) payload.service_token = serviceToken;
+  const encoded = `${JSON.stringify(payload)}\n`;
+  if (Buffer.byteLength(encoded, "utf8") > MAX_BYTES) {
+    return Promise.reject(new LanguageGuardBlocked("guard request is too large", "guard_unavailable"));
+  }
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let raw = "";
+    const socket = net.createConnection(endpointOptions(endpoint));
+    const finish = (error, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.destroy();
+      if (error) reject(error);
+      else resolve(value);
+    };
+    const timer = setTimeout(() => finish(new LanguageGuardBlocked("guard service timed out", "guard_unavailable")), timeoutMs);
+    timer.unref?.();
+    socket.setEncoding("utf8");
+    socket.once("connect", () => socket.write(encoded));
+    socket.on("data", chunk => {
+      raw += chunk;
+      if (Buffer.byteLength(raw, "utf8") > MAX_BYTES) {
+        finish(new LanguageGuardBlocked("guard response is too large", "guard_unavailable"));
+        return;
+      }
+      const newline = raw.indexOf("\n");
+      if (newline < 0) return;
+      try {
+        const response = JSON.parse(raw.slice(0, newline));
+        finish(null, response);
+      } catch {
+        finish(new LanguageGuardBlocked("guard returned invalid JSON", "guard_unavailable"));
+      }
+    });
+    socket.once("error", () => finish(new LanguageGuardBlocked("guard service is unavailable", "guard_unavailable")));
+    socket.once("end", () => {
+      if (!settled) finish(new LanguageGuardBlocked("guard closed without a decision", "guard_unavailable"));
+    });
+  });
+}
+
+async function verifyForDelivery({ rawEnvelope, hostContext, endpoint, serviceToken = "", agentId = "", channel = "" }) {
+  const envelope = parseAgentEnvelope(rawEnvelope);
+  const route = routeHostContext(hostContext);
+  const result = await callGuardService(endpoint, {
+    operation: "verify",
+    task_kind: route.taskKind,
+    source_text: route.sourceText,
+    target_text: envelope.target_text,
+    language: route.language,
+    release_token: envelope.release_token,
+    content_type: route.contentType,
+    short_text_reviewed: hostContext.short_text_reviewed === true,
+    agent_id: String(agentId || ""),
+    channel: String(channel || ""),
+  }, { serviceToken });
+  if (result?.valid !== true) {
+    const failedChecks = result?.checks && typeof result.checks === "object"
+      ? Object.entries(result.checks).filter(([, passed]) => passed !== true).map(([name]) => name)
+      : [];
+    const detail = failedChecks.length ? ` (failed checks: ${failedChecks.join(", ")})` : "";
+    throw new LanguageGuardBlocked(`isolated guard rejected the exact output${detail}`, "receipt_rejected");
+  }
+  return { text: envelope.target_text, route, verification: result };
+}
+
+function splitTelegramMessage(value, limit = 3900) {
+  const chunks = [];
+  let remaining = String(value || "").trim();
+  while (remaining.length > limit) {
+    let splitAt = remaining.lastIndexOf("\n", limit);
+    if (splitAt < Math.floor(limit * 0.55)) splitAt = remaining.lastIndexOf(" ", limit);
+    if (splitAt < Math.floor(limit * 0.55)) splitAt = limit;
+    chunks.push(remaining.slice(0, splitAt).trimEnd());
+    remaining = remaining.slice(splitAt).trimStart();
+  }
+  if (remaining) chunks.push(remaining);
+  return chunks;
+}
+
+async function guardedTelegramSend(options) {
+  const verified = await verifyForDelivery({ ...options, channel: options.channel || "telegram" });
+  if (typeof options.telegramRequest !== "function") {
+    throw new LanguageGuardBlocked("Telegram transport is unavailable", "delivery_unavailable");
+  }
+  let lastResult = null;
+  for (const text of splitTelegramMessage(verified.text)) {
+    lastResult = await options.telegramRequest(options.botToken, "sendMessage", {
+      chat_id: options.chatId,
+      text,
+      ...(options.topicId ? { message_thread_id: options.topicId } : {}),
+      ...(options.replyParameters ? { reply_parameters: options.replyParameters } : {}),
+    });
+  }
+  return { sent: true, chunks: splitTelegramMessage(verified.text).length, lastResult, verification: verified.verification };
+}
+
+module.exports = {
+  LanguageGuardBlocked,
+  routeHostContext,
+  parseAgentEnvelope,
+  callGuardService,
+  verifyForDelivery,
+  splitTelegramMessage,
+  guardedTelegramSend,
+};

package/standard-skills/translate-native/integrations/audit_log.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Content-free audit records for language-guard release decisions."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import stat
+import time
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Any, Iterator
+
+
+SAFE_LABEL = re.compile(r"[^A-Za-z0-9_.:@/-]+")
+
+
+def _file_identity(details: os.stat_result) -> tuple[int, int, int, int, int]:
+    return (
+        details.st_dev,
+        details.st_ino,
+        details.st_size,
+        details.st_ctime_ns,
+        details.st_mtime_ns,
+    )
+
+
+def _directory_identity(details: os.stat_result) -> tuple[int, int, int, int, int]:
+    return (
+        details.st_dev,
+        details.st_ino,
+        details.st_mode,
+        details.st_uid,
+        details.st_gid,
+    )
+
+
+def _validate_directory(path: Path, details: os.stat_result) -> None:
+    if not stat.S_ISDIR(details.st_mode) or stat.S_ISLNK(details.st_mode):
+        raise RuntimeError(f"audit directory must be a real directory: {path}")
+    if os.name != "nt" and stat.S_IMODE(details.st_mode) & 0o022:
+        raise RuntimeError(f"audit directory must not be writable outside its owner: {path}")
+    if hasattr(os, "getuid") and details.st_uid != os.getuid():
+        raise RuntimeError(f"audit directory owner is invalid: {path}")
+
+
+def _existing_directory_anchor(path: Path) -> Path:
+    candidate = path
+    while True:
+        try:
+            candidate.lstat()
+            return candidate
+        except FileNotFoundError:
+            parent = candidate.parent
+            if parent == candidate:
+                raise RuntimeError(f"audit directory has no existing anchor: {path}")
+            candidate = parent
+
+
+def _assert_directory_unchanged(
+    path: Path, expected: tuple[int, int, int, int, int],
+) -> None:
+    try:
+        current = path.lstat()
+    except OSError as error:
+        raise RuntimeError(f"audit directory cannot be rechecked: {path}") from error
+    _validate_directory(path, current)
+    if _directory_identity(current) != expected:
+        raise RuntimeError(f"audit directory changed during operation: {path}")
+
+
+@contextmanager
+def _open_audit_directory(path: Path, *, create: bool) -> Iterator[int | None]:
+    if os.name == "nt":
+        if create:
+            path.parent.mkdir(parents=True, exist_ok=True)
+        yield None
+        return
+    anchor = Path.home()
+    try:
+        relative = path.parent.relative_to(anchor)
+    except ValueError:
+        anchor = _existing_directory_anchor(path.parent)
+        relative = path.parent.relative_to(anchor)
+    flags = (
+        os.O_RDONLY
+        | getattr(os, "O_BINARY", 0)
+        | getattr(os, "O_DIRECTORY", 0)
+        | getattr(os, "O_NOFOLLOW", 0)
+    )
+    descriptor = None
+    current_path = anchor
+    try:
+        try:
+            descriptor = os.open(anchor, flags)
+            _validate_directory(anchor, os.fstat(descriptor))
+            for component in relative.parts:
+                current_path = current_path / component
+                try:
+                    child = os.open(component, flags, dir_fd=descriptor)
+                except FileNotFoundError:
+                    if not create:
+                        raise
+                    try:
+                        os.mkdir(component, mode=0o700, dir_fd=descriptor)
+                    except FileExistsError:
+                        pass
+                    child = os.open(component, flags, dir_fd=descriptor)
+                try:
+                    _validate_directory(current_path, os.fstat(child))
+                except Exception:
+                    os.close(child)
+                    raise
+                os.close(descriptor)
+                descriptor = child
+            expected = _directory_identity(os.fstat(descriptor))
+        except (FileNotFoundError, RuntimeError):
+            raise
+        except OSError as error:
+            raise RuntimeError(
+                f"audit directory cannot be opened safely: {current_path}"
+            ) from error
+        try:
+            yield descriptor
+        finally:
+            _assert_directory_unchanged(path.parent, expected)
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def _validate_file(path: Path, details: os.stat_result, label: str) -> None:
+    if not stat.S_ISREG(details.st_mode) or stat.S_ISLNK(details.st_mode):
+        raise RuntimeError(f"{label} must be a regular file: {path}")
+    if details.st_nlink != 1:
+        raise RuntimeError(f"{label} must not have additional hard links: {path}")
+    if os.name != "nt" and stat.S_IMODE(details.st_mode) & 0o022:
+        raise RuntimeError(f"{label} must not be writable outside its owner: {path}")
+    if hasattr(os, "getuid") and details.st_uid != os.getuid():
+        raise RuntimeError(f"{label} owner is invalid: {path}")
+
+
+def _audit_lstat(path: Path, directory: int | None) -> os.stat_result:
+    if directory is None:
+        return path.lstat()
+    return os.stat(path.name, dir_fd=directory, follow_symlinks=False)
+
+
+def _open_audit_file(path: Path, directory: int | None, flags: int, mode: int = 0o600) -> int:
+    if directory is None:
+        return os.open(path, flags, mode)
+    return os.open(path.name, flags, mode, dir_fd=directory)
+
+
+def _path_matches_handle(path: Path, handle, label: str, directory: int | None) -> None:
+    try:
+        opened = os.fstat(handle.fileno())
+        current = _audit_lstat(path, directory)
+    except OSError as error:
+        raise RuntimeError(f"{label} is unreadable: {path}") from error
+    _validate_file(path, opened, label)
+    _validate_file(path, current, label)
+    if _file_identity(opened) != _file_identity(current):
+        raise RuntimeError(f"{label} changed while in use: {path}")
+
+
+@contextmanager
+def _protected_append(
+    path: Path, label: str, encoding: str, directory: int | None,
+) -> Iterator[Any]:
+    """Open one append-only state file without following or replacing links."""
+    descriptor = None
+    for _attempt in range(3):
+        try:
+            before = _audit_lstat(path, directory)
+        except FileNotFoundError:
+            flags = (
+                os.O_RDWR | os.O_APPEND | os.O_CREAT | os.O_EXCL
+                | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+            )
+            try:
+                descriptor = _open_audit_file(path, directory, flags)
+                before = None
+                break
+            except FileExistsError:
+                continue
+            except OSError as error:
+                raise RuntimeError(f"{label} cannot be created: {path}") from error
+        except OSError as error:
+            raise RuntimeError(f"{label} is unreadable: {path}") from error
+        _validate_file(path, before, label)
+        flags = (
+            os.O_RDWR | os.O_APPEND
+            | getattr(os, "O_BINARY", 0) | getattr(os, "O_NOFOLLOW", 0)
+        )
+        try:
+            descriptor = _open_audit_file(path, directory, flags)
+        except OSError as error:
+            raise RuntimeError(f"{label} cannot be opened safely: {path}") from error
+        try:
+            opened = os.fstat(descriptor)
+            _validate_file(path, opened, label)
+            if _file_identity(opened) != _file_identity(before):
+                raise RuntimeError(f"{label} changed while opening: {path}")
+        except (OSError, RuntimeError):
+            os.close(descriptor)
+            descriptor = None
+            raise
+        break
+    if descriptor is None:
+        raise RuntimeError(f"{label} could not be reserved safely: {path}")
+    try:
+        with os.fdopen(descriptor, "a+", encoding=encoding, newline="\n") as handle:
+            descriptor = None
+            _path_matches_handle(path, handle, label, directory)
+            try:
+                yield handle
+            finally:
+                handle.flush()
+                os.fsync(handle.fileno())
+                _path_matches_handle(path, handle, label, directory)
+    finally:
+        if descriptor is not None:
+            os.close(descriptor)
+
+
+def audit_paths_healthy(path: Path) -> bool:
+    """Inspect existing audit state without creating or modifying it."""
+    try:
+        with _open_audit_directory(path, create=False) as directory:
+            for candidate, label in (
+                (path, "audit log"),
+                (path.with_suffix(path.suffix + ".lock"), "audit lock"),
+            ):
+                try:
+                    details = _audit_lstat(candidate, directory)
+                except FileNotFoundError:
+                    continue
+                except OSError:
+                    return False
+                try:
+                    _validate_file(candidate, details, label)
+                except RuntimeError:
+                    return False
+            return True
+    except FileNotFoundError:
+        return True
+    except (OSError, RuntimeError):
+        return False
+
+
+def safe_label(value: Any, limit: int = 160) -> str:
+    return SAFE_LABEL.sub("_", str(value or "").strip())[:limit]
+
+
+def finding_codes(result: dict[str, Any]) -> list[str]:
+    output: list[str] = []
+    for finding in result.get("findings", []):
+        if isinstance(finding, dict) and finding.get("code"):
+            output.append(safe_label(finding["code"], 80))
+    reason = result.get("reason")
+    if reason:
+        output.append(safe_label(reason, 80))
+    checks = result.get("checks")
+    if isinstance(checks, dict):
+        output.extend(
+            f"failed-{safe_label(name, 70)}"
+            for name, passed in checks.items()
+            if passed is not True
+        )
+    return sorted(set(filter(None, output)))[:40]
+
+
+@contextmanager
+def _exclusive_lock(handle) -> Iterator[None]:
+    if os.name == "nt":
+        import msvcrt
+
+        handle.seek(0)
+        if not handle.read(1):
+            handle.seek(0)
+            handle.write("0")
+            handle.flush()
+        handle.seek(0)
+        msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
+        try:
+            yield
+        finally:
+            handle.seek(0)
+            msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+    else:
+        import fcntl
+
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def append_audit(path: Path, record: dict[str, Any]) -> None:
+    """Append a bounded record. Callers must never pass source or target text."""
+    forbidden = {"source", "source_text", "target", "target_text", "release_token", "service_token"}
+    if forbidden.intersection(record):
+        raise ValueError("audit records cannot contain text or tokens")
+    payload = {
+        "ts": int(time.time()),
+        "event": safe_label(record.get("event", "decision"), 40),
+        "allowed": record.get("allowed") is True,
+        "task_kind": safe_label(record.get("task_kind"), 24),
+        "language": safe_label(record.get("language"), 40),
+        "agent_id": safe_label(record.get("agent_id"), 120),
+        "channel": safe_label(record.get("channel"), 80),
+        "source_sha256": safe_label(record.get("source_sha256"), 64),
+        "target_sha256": safe_label(record.get("target_sha256"), 64),
+        "guard_version": safe_label(record.get("guard_version"), 32),
+        "codes": [safe_label(value, 80) for value in record.get("codes", [])[:40]],
+    }
+    line = json.dumps(payload, ensure_ascii=True, separators=(",", ":")) + "\n"
+    lock_path = path.with_suffix(path.suffix + ".lock")
+    with _open_audit_directory(path, create=True) as directory:
+        with _protected_append(lock_path, "audit lock", "ascii", directory) as lock_handle:
+            with _exclusive_lock(lock_handle):
+                _path_matches_handle(lock_path, lock_handle, "audit lock", directory)
+                with _protected_append(path, "audit log", "utf-8", directory) as handle:
+                    handle.write(line)