dsh-desktop-kit 2.2.0 → 2.7.2

package/plugins/dsh-memory-bridge/lib/bridge.js

@@ -0,0 +1,636 @@
+/**
+ * dsh-memory-bridge — portable bundle format, redaction, crypto and path safety.
+ *
+ * Pure Node module (node:fs/promises, node:path, node:crypto, node:os), no network.
+ * The format is one self-contained UTF-8 JSON file per machine and project:
+ *
+ *   {
+ *     "format": "dsh-memory-bridge", "version": 1, "encrypted": false,
+ *     "machineId": "...", "createdAt": "...", "revision": 7, "contentHash": "...",
+ *     "project": { "key": "<12 hex>", "fingerprint": "git:...", ... },
+ *     "files":   [ { "path": "PROJECT.md", "sha256": "...", "bytes": 123 } ],
+ *     "content": { "PROJECT.md": "..." }
+ *   }
+ *
+ * Encrypted bundles keep `project/files/content` inside an AES-256-GCM payload.
+ */
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+export const FORMAT = "dsh-memory-bridge";
+export const VERSION = 1;
+export const REDACTION_VERSION = 1;
+
+export const SECTION_FILES = Object.freeze([
+  "PROJECT.md",
+  "ARCHITECTURE.md",
+  "CODE-MAP.md",
+  "INVARIANTS.md",
+  "GOTCHAS.md",
+  "RUNBOOK.md",
+]);
+
+export const JOURNAL_FILE = /^JOURNAL\/\d{4}-\d{2}\.md$/u;
+export const PROJECT_KEY = /^[a-f0-9]{12}$/u;
+export const SHA256_HEX = /^[a-f0-9]{64}$/u;
+
+export const DEFAULT_LIMITS = Object.freeze({
+  maxFileBytes: 2 * 1024 * 1024,
+  maxBundleBytes: 10 * 1024 * 1024,
+  maxFiles: 200,
+  maxPathLength: 240,
+  maxSegmentLength: 120,
+});
+
+const RESERVED_NAMES = new Set(["__proto__", "constructor", "prototype"]);
+const WINDOWS_RESERVED = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\..*)?$/iu;
+const WINDOWS_INVALID = /[<>:"|?*\u0000-\u001f]/u;
+const AUTO_SCAN_BLOCK = /<!--\s*AUTO-SCAN:START[^>]*-->[\s\S]*?<!--\s*AUTO-SCAN:END\s*-->/gu;
+const PLACEHOLDER = /\(не заполнено\)/iu;
+
+/** Typed, user-facing error with a stable code. */
+export class BridgeError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "BridgeError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function sha256(data) {
+  return crypto.createHash("sha256").update(data).digest("hex");
+}
+
+export function normalizeLf(text) {
+  return String(text ?? "").replace(/\r\n/gu, "\n");
+}
+
+export function delay(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* filesystem helpers                                                  */
+/* ------------------------------------------------------------------ */
+
+export function dshHome() {
+  const configured = process.env.DSH_HOME;
+  return typeof configured === "string" && configured.trim().length > 0
+    ? path.resolve(configured.trim())
+    : path.join(os.homedir(), ".dsh");
+}
+
+export function memoryRoot(home = dshHome()) {
+  return path.join(home, "projects-memory");
+}
+
+export function syncRoot(home = dshHome()) {
+  return path.join(home, "memory-sync");
+}
+
+export async function ensureDir(directory) {
+  await fsp.mkdir(directory, { recursive: true, mode: 0o700 });
+  try {
+    await fsp.chmod(directory, 0o700);
+  } catch {
+    /* best effort on Windows */
+  }
+}
+export function ensureDirSync(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  try {
+    fs.chmodSync(directory, 0o700);
+  } catch {
+    /* best effort on Windows */
+  }
+}
+
+export async function exists(file) {
+  try {
+    await fsp.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function readTextIfExists(file) {
+  try {
+    return await fsp.readFile(file, "utf8");
+  } catch (error) {
+    if (error?.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export async function readJsonIfExists(file) {
+  const raw = await readTextIfExists(file);
+  if (raw === undefined) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+/** tmp + rename, with retries for cloud/AV locks on Windows. */
+export async function writeFileAtomic(file, data, { mode = 0o600 } = {}) {
+  const directory = path.dirname(file);
+  await ensureDir(directory);
+  const tmp = path.join(directory, `.${path.basename(file)}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`);
+  await fsp.writeFile(tmp, data, { mode });
+  try {
+    await fsp.chmod(tmp, mode);
+  } catch {
+    /* best effort */
+  }
+  let lastError;
+  for (let attempt = 0; attempt < 6; attempt += 1) {
+    try {
+      await fsp.rename(tmp, file);
+      return;
+    } catch (error) {
+      lastError = error;
+      await delay(40 * (attempt + 1));
+    }
+  }
+  try {
+    await fsp.rm(tmp, { force: true });
+  } catch {
+    /* ignore */
+  }
+  throw lastError;
+}
+
+export async function writeJsonAtomic(file, value, options) {
+  return writeFileAtomic(file, `${JSON.stringify(value, null, 2)}\n`, options);
+}
+
+export async function removeFileQuiet(file) {
+  try {
+    await fsp.rm(file, { force: true });
+  } catch {
+    /* ignore */
+  }
+}
+
+export function assertInside(base, target) {
+  const root = path.resolve(base);
+  const resolved = path.resolve(target);
+  const relative = path.relative(root, resolved);
+  if (relative.length === 0) return resolved;
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new BridgeError("path/outside", `путь вне разрешённого каталога: ${target}`);
+  }
+  return resolved;
+}
+
+/* ------------------------------------------------------------------ */
+/* redaction                                                           */
+/* ------------------------------------------------------------------ */
+
+const REDACTION_RULES = [
+  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/gu, "[REDACTED:PRIVATE_KEY]"],
+  [/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/gu, "[REDACTED:JWT]"],
+  [/\b(?:sk|rk)-[A-Za-z0-9_-]{16,}\b/gu, "[REDACTED:KEY]"],
+  [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{16,}\b/gu, "[REDACTED:GITHUB_TOKEN]"],
+  [/\bgithub_pat_[A-Za-z0-9_]{16,}\b/gu, "[REDACTED:GITHUB_TOKEN]"],
+  [/\bglpat-[A-Za-z0-9_-]{20,}\b/gu, "[REDACTED:GITLAB_TOKEN]"],
+  [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/gu, "[REDACTED:SLACK_TOKEN]"],
+  [/\bAKIA[0-9A-Z]{16}\b/gu, "[REDACTED:AWS_KEY]"],
+  [/\bAIza[0-9A-Za-z_-]{30,}\b/gu, "[REDACTED:GOOGLE_KEY]"],
+  [/\bsk_live_[0-9A-Za-z]{16,}\b/gu, "[REDACTED:STRIPE_KEY]"],
+  [/\bya29\.[A-Za-z0-9_-]{20,}\b/gu, "[REDACTED:GOOGLE_OAUTH]"],
+  [/\bnpm_[A-Za-z0-9]{36}\b/gu, "[REDACTED:NPM_TOKEN]"],
+  [/\bSG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\b/gu, "[REDACTED:SENDGRID_KEY]"],
+  [/\b\d{8,10}:[A-Za-z0-9_-]{30,}\b/gu, "[REDACTED:TELEGRAM_TOKEN]"],
+  [/\bAccountKey\s*=\s*[A-Za-z0-9+/=]{20,}/giu, "AccountKey=[REDACTED]"],
+  [/\b(?:Set-)?Cookie\s*:\s*[^\r\n]+/giu, "[REDACTED:COOKIE]"],
+  [/\bAuthorization:\s*(?:Bearer|Basic|Token)\s+[^\s]+/giu, "Authorization: [REDACTED]"],
+  [/\b(\w+:\/\/)[^:@/\s]+:[^@/\s]+@/gu, "$1[REDACTED]@"],
+  [/\b([A-Z0-9_]*(?:PASSWORD|PASSWD|PASSPHRASE|PASS|APP_KEY|SECRET|TOKEN|API[_-]?KEY|PRIVATE[_-]?KEY|KEY|DSN|DATABASE_URL|REDIS_URL|ACCESS[_-]?KEY)[A-Z0-9_]*)\s*[:=]\s*["']?[^\s"',;]+/giu, "$1=[REDACTED]"],
+  [/(^|\n)(\s*(?:password|passwd|pwd|passphrase|secret|token|api[_-]?key|authorization)\s*[:=]\s*)[^\n]*/giu, "$1$2[REDACTED]"],
+  [/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/giu, "[email]"],
+  [/(?:\+7|8)[\s(-]*\d{3}[\s)-]*\d{3}[\s-]*\d{2}[\s-]*\d{2}\b/gu, "[phone]"],
+];
+
+/** Remove secrets/PII before anything is written to a bundle or a dossier. */
+export function redactSecrets(input) {
+  let text = String(input ?? "");
+  for (const [pattern, replacement] of REDACTION_RULES) text = text.replace(pattern, replacement);
+  return text;
+}
+
+/** Rows where redaction would change the text — for the `/sync audit` command. */
+export function findSecretHits(text) {
+  const value = String(text ?? "");
+  const hits = [];
+  for (const [pattern] of REDACTION_RULES) {
+    const re = new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+    let match;
+    while ((match = re.exec(value)) !== null) {
+      const index = match.index ?? 0;
+      const line = value.slice(0, index).split(/\r?\n/u).length;
+      hits.push({ line, sample: shorten(match[0]) });
+      if (match.index === re.lastIndex) re.lastIndex += 1;
+      if (hits.length > 200) return hits;
+    }
+  }
+  return hits;
+}
+
+function shorten(value, max = 60) {
+  const text = String(value ?? "").replace(/\s+/gu, " ").trim();
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
+/* ------------------------------------------------------------------ */
+/* AUTO-SCAN and dossier helpers                                       */
+/* ------------------------------------------------------------------ */
+
+export function stripAutoScan(text) {
+  return String(text ?? "")
+    .replace(AUTO_SCAN_BLOCK, "")
+    .replace(/\n{3,}/gu, "\n\n")
+    .trim();
+}
+
+export function extractAutoScanBlocks(text) {
+  const blocks = String(text ?? "").match(AUTO_SCAN_BLOCK);
+  return blocks ? blocks.slice(0, 4) : [];
+}
+
+/**
+ * A freshly registered project is created with template files that contain
+ * "(не заполнено)" markers. Such a dossier is safe to bootstrap from a remote
+ * bundle: the local side has no user knowledge to lose.
+ *
+ * The check is deliberately strict: every non-heading line must look like the
+ * kit's generated default. A real dossier that only left one "(не заполнено)"
+ * field but filled others is NOT a template.
+ */
+const TEMPLATE_LINES = [
+  /^[-*]\s*\(не заполнено\)$/iu,
+  /^[-*]\s*(?:Назначение|Прод|Как запускать локально):\s*\(не заполнено\)/iu,
+  /^[-*]\s*Стек:\s*(?:\(не определён\))?$/iu,
+  /^[-*]\s*Slug:\s*`[^`]*`$/u,
+  /^[-*]\s*Корни:\s*`[^`]*`(?:\s*,\s*`[^`]*`)*$/u,
+  /^[-*]\s*Создано:\s*\d{4}-\d{2}-\d{2}T\S*$/u,
+  /^[-*]\s*Уверенность памяти:\s*\S.*$/u,
+  /^[-*]\s*Последний глубокий анализ:\s*(?:—|-)?\s*$/u,
+  /^[-*]\s*Git:\s*(?:не git или неизвестно|[A-Za-z0-9._/-]+@[0-9a-f]{4,})$/u,
+  /^[-*]\s*\(нет\)$/iu,
+  /^\(не заполнено\)$/iu,
+  /^(?:Симптом|Причина|Решение|Как обнаружить заранее):\s*\([^)]*\)$/u,
+  /^Уверенность:\s*\[[^\]]*\]$/u,
+  /^<!--[\s\S]*-->$/u,
+];
+
+export function isTemplateContent(text) {
+  const value = String(text ?? "");
+  const manual = stripAutoScan(value);
+  if (manual.trim().length === 0) return true;
+  if (!PLACEHOLDER.test(manual)) return false;
+  for (const line of manual.split(/\r?\n/u)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    if (trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith(">")) continue;
+    if (TEMPLATE_LINES.some((pattern) => pattern.test(trimmed))) continue;
+    return false;
+  }
+  return true;
+}
+
+/* ------------------------------------------------------------------ */
+/* portable paths (home directory is machine-specific)                 */
+/* ------------------------------------------------------------------ */
+
+export const HOME_TOKEN = "%DSH_HOME%";
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+/**
+ * Replace the local home directory with a stable token before content is
+ * hashed, compared or written into a bundle. This keeps base hashes identical
+ * on machines with different user names while the dossier itself keeps real
+ * local paths.
+ */
+export function canonicalizePaths(text, home = os.homedir()) {
+  const value = String(text ?? "");
+  if (value.length === 0 || typeof home !== "string" || home.length < 3) return value;
+  return value.replace(new RegExp(escapeRegExp(home), "giu"), HOME_TOKEN);
+}
+
+export function localizePaths(text, home = os.homedir()) {
+  const value = String(text ?? "");
+  if (value.length === 0 || typeof home !== "string" || home.length === 0) return value;
+  return value.split(HOME_TOKEN).join(home);
+}
+
+/* ------------------------------------------------------------------ */
+/* path safety                                                         */
+/* ------------------------------------------------------------------ */
+
+/** Validate and canonicalise a bundle-relative path (`/` separators). */
+export function safeRelPath(raw, limits = DEFAULT_LIMITS) {
+  if (typeof raw !== "string" || raw.trim().length === 0) {
+    throw new BridgeError("path/bad", "пустое имя файла в пакете");
+  }
+  const value = raw.replaceAll("\\", "/").trim();
+  if (value.length > limits.maxPathLength) throw new BridgeError("path/too-long", `слишком длинный путь: ${shorten(value)}`);
+  if (value.startsWith("/") || /^[A-Za-z]:/u.test(value) || value.startsWith("//")) {
+    throw new BridgeError("path/absolute", `абсолютный путь в пакете: ${shorten(value)}`);
+  }
+  const parts = value.split("/");
+  for (const part of parts) {
+    if (part.length === 0 || part === "." || part === "..") {
+      throw new BridgeError("path/bad", `недопустимый сегмент пути: ${shorten(value)}`);
+    }
+    if (part.length > limits.maxSegmentLength) throw new BridgeError("path/too-long", `слишком длинный сегмент пути: ${shorten(part)}`);
+    if (WINDOWS_INVALID.test(part)) throw new BridgeError("path/bad", `недопустимые символы в пути: ${shorten(value)}`);
+    if (RESERVED_NAMES.has(part.toLowerCase())) throw new BridgeError("path/bad", `служебное имя файла: ${shorten(value)}`);
+    if (WINDOWS_RESERVED.test(part)) throw new BridgeError("path/bad", `зарезервированное имя Windows: ${shorten(value)}`);
+    if (part.endsWith(".") || part.endsWith(" ") || part.startsWith(" ")) {
+      throw new BridgeError("path/bad", `недопустимое окончание сегмента пути: ${shorten(value)}`);
+    }
+  }
+  return parts.join("/");
+}
+
+export function isAllowedSyncPath(relativePath) {
+  return SECTION_FILES.includes(relativePath) || JOURNAL_FILE.test(relativePath);
+}
+
+/* ------------------------------------------------------------------ */
+/* content hashing                                                     */
+/* ------------------------------------------------------------------ */
+
+/** Deterministic content hash over sorted `path -> sha256(text)` pairs. */
+export function hashContentMap(content) {
+  const lines = [];
+  for (const key of [...content.keys()].sort()) lines.push(`${key}\u0000${sha256(content.get(key))}`);
+  return sha256(lines.join("\n"));
+}
+
+export function fileEntries(content, bases = new Map()) {
+  const baseMap = bases instanceof Map ? bases : new Map(Object.entries(bases ?? {}));
+  return [...content.keys()].sort().map((key) => {
+    const text = content.get(key);
+    const base = baseMap.get(key);
+    return {
+      path: key,
+      sha256: sha256(text),
+      bytes: Buffer.byteLength(text, "utf8"),
+      base: typeof base === "string" && SHA256_HEX.test(base) ? base : null,
+    };
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* encryption (optional, key file; the key is copied between machines) */
+/* ------------------------------------------------------------------ */
+
+export function keyIdOf(key) {
+  return sha256(key).slice(0, 12);
+}
+
+export async function loadKeyFile(file) {
+  const raw = (await fsp.readFile(file, "utf8")).trim();
+  let key;
+  try {
+    key = Buffer.from(raw, "base64");
+  } catch {
+    key = Buffer.from(raw, "utf8");
+  }
+  if (key.length === 32) return key;
+  const utf8 = Buffer.from(raw, "utf8");
+  if (utf8.length === 32) return utf8;
+  throw new BridgeError("crypto/bad-key", "ключ синхронизации должен быть 32 байта (base64 в файле)");
+}
+
+export async function generateKeyFile(file) {
+  const key = crypto.randomBytes(32);
+  await ensureDir(path.dirname(file));
+  await writeFileAtomic(file, `${key.toString("base64")}\n`, { mode: 0o600 });
+  return key;
+}
+
+function bundleAad(header) {
+  return Buffer.from(
+    JSON.stringify({
+      format: header.format,
+      version: header.version,
+      machineId: header.machineId,
+      createdAt: header.createdAt,
+      revision: header.revision,
+      keyId: header.keyId ?? null,
+    }),
+    "utf8",
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/* bundle build / parse                                                */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Build the JSON value for one bundle.
+ * @param {{machineId:string, createdAt:string, revision:number,
+ *          project:object, content:Map<string,string>, key?:Buffer|null,
+ *          bases?:Map<string,string>|Record<string,string>, limits?:object}} input
+ */
+export function buildBundle(input) {
+  const limits = { ...DEFAULT_LIMITS, ...(input.limits ?? {}) };
+  const content = input.content;
+  if (!(content instanceof Map)) throw new BridgeError("bundle/internal", "content must be a Map");
+  if (content.size > limits.maxFiles) throw new BridgeError("bundle/too-many-files", `слишком много файлов: ${content.size}`);
+  const safeContent = new Map();
+  for (const [rawPath, text] of content) {
+    const relativePath = safeRelPath(rawPath, limits);
+    if (!isAllowedSyncPath(relativePath)) throw new BridgeError("bundle/bad-path", `файл не входит в память проекта: ${relativePath}`);
+    if (typeof text !== "string") throw new BridgeError("bundle/bad-content", `содержимое ${relativePath} должно быть строкой`);
+    safeContent.set(relativePath, text);
+  }
+  const files = fileEntries(safeContent, input.bases);
+  let totalBytes = 0;
+  for (const entry of files) {
+    if (entry.bytes > limits.maxFileBytes) {
+      throw new BridgeError("bundle/file-too-large", `файл ${entry.path} больше лимита (${entry.bytes} B)`);
+    }
+    totalBytes += entry.bytes;
+  }
+  if (totalBytes > limits.maxBundleBytes) throw new BridgeError("bundle/too-large", `пакет больше лимита (${totalBytes} B)`);
+  const contentHash = hashContentMap(safeContent);
+  const header = {
+    format: FORMAT,
+    version: VERSION,
+    encrypted: Boolean(input.key),
+    machineId: String(input.machineId),
+    createdAt: String(input.createdAt),
+    revision: Number.isFinite(input.revision) ? Math.max(0, Math.trunc(input.revision)) : 0,
+    contentHash,
+  };
+  if (!input.key) {
+    return {
+      ...header,
+      project: input.project,
+      files,
+      content: Object.fromEntries(safeContent),
+    };
+  }
+  const key = input.key;
+  const keyId = keyIdOf(key);
+  const headerWithKey = { ...header, keyId };
+  const iv = crypto.randomBytes(12);
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+  cipher.setAAD(bundleAad(headerWithKey));
+  const payload = Buffer.concat([
+    cipher.update(JSON.stringify({ project: input.project, files, content: Object.fromEntries(safeContent) }), "utf8"),
+    cipher.final(),
+  ]);
+  return {
+    ...headerWithKey,
+    kdf: { alg: "raw", keyId },
+    cipher: { alg: "aes-256-gcm", iv: iv.toString("base64"), tag: cipher.getAuthTag().toString("base64") },
+    payload: payload.toString("base64"),
+  };
+}
+
+function requirePlainObject(value, code, label) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new BridgeError(code, `${label} должен быть объектом`);
+  }
+  return value;
+}
+
+/**
+ * Parse and fully verify one bundle (`Buffer|string`).
+ * @param {Buffer|string} raw
+ * @param {{key?:Buffer|null, limits?:object}} options
+ */
+export function parseBundle(raw, options = {}) {
+  const limits = { ...DEFAULT_LIMITS, ...(options.limits ?? {}) };
+  const text = Buffer.isBuffer(raw) ? raw.toString("utf8") : String(raw ?? "");
+  if (Buffer.byteLength(text, "utf8") > limits.maxBundleBytes) {
+    throw new BridgeError("bundle/too-large", "пакет больше лимита");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new BridgeError("bundle/bad-json", "пакет не является корректным JSON");
+  }
+  const top = requirePlainObject(parsed, "bundle/bad", "пакет");
+  if (top.format !== FORMAT) throw new BridgeError("bundle/bad-format", "неизвестный формат пакета");
+  if (top.version !== VERSION) throw new BridgeError("bundle/bad-version", `неподдерживаемая версия пакета: ${String(top.version)}`);
+  if (typeof top.machineId !== "string" || top.machineId.length === 0 || top.machineId.length > 100) {
+    throw new BridgeError("bundle/bad-machine", "некорректный machineId в пакете");
+  }
+  if (typeof top.createdAt !== "string" || Number.isNaN(Date.parse(top.createdAt))) {
+    throw new BridgeError("bundle/bad-date", "некорректная дата создания пакета");
+  }
+  if (!Number.isInteger(top.revision) || top.revision < 0) throw new BridgeError("bundle/bad-revision", "некорректная ревизия пакета");
+  if (typeof top.contentHash !== "string" || !SHA256_HEX.test(top.contentHash)) {
+    throw new BridgeError("bundle/bad-hash", "некорректный contentHash пакета");
+  }
+
+  let payload;
+  if (top.encrypted === true) {
+    const key = options.key;
+    if (!(key instanceof Buffer) || key.length !== 32) {
+      throw new BridgeError("crypto/key-required", "пакет зашифрован, а ключ не настроен или неверен");
+    }
+    if (top.kdf?.alg !== "raw") throw new BridgeError("crypto/bad-kdf", "неподдерживаемый способ шифрования пакета");
+    if (top.cipher?.alg !== "aes-256-gcm") throw new BridgeError("crypto/bad-cipher", "неподдерживаемый шифр пакета");
+    if (typeof top.cipher.iv !== "string" || typeof top.cipher.tag !== "string" || typeof top.payload !== "string") {
+      throw new BridgeError("bundle/bad-crypto", "повреждён зашифрованный пакет");
+    }
+    let decipher;
+    try {
+      decipher = crypto.createDecipheriv("aes-256-gcm", key, Buffer.from(top.cipher.iv, "base64"));
+      decipher.setAAD(bundleAad(top));
+      decipher.setAuthTag(Buffer.from(top.cipher.tag, "base64"));
+      const decrypted = Buffer.concat([decipher.update(Buffer.from(top.payload, "base64")), decipher.final()]);
+      payload = JSON.parse(decrypted.toString("utf8"));
+    } catch {
+      throw new BridgeError("crypto/decrypt-failed", "не удалось расшифровать пакет: неверный ключ или повреждённые данные");
+    }
+  } else {
+    payload = { project: top.project, files: top.files, content: top.content };
+  }
+
+  const body = requirePlainObject(payload, "bundle/bad", "содержимое пакета");
+  const project = requirePlainObject(body.project, "bundle/bad-project", "описание проекта");
+  if (typeof project.key !== "string" || !PROJECT_KEY.test(project.key)) {
+    throw new BridgeError("bundle/bad-project", "некорректный ключ проекта в пакете");
+  }
+  if (typeof project.fingerprint !== "string" || project.fingerprint.length === 0 || project.fingerprint.length > 500) {
+    throw new BridgeError("bundle/bad-project", "некорректный fingerprint проекта в пакете");
+  }
+  if (project.originHome !== undefined && typeof project.originHome !== "string") {
+    throw new BridgeError("bundle/bad-project", "некорректный originHome в пакете");
+  }
+  if (!Array.isArray(body.files)) throw new BridgeError("bundle/bad-files", "в пакете нет списка файлов");
+  if (body.files.length > limits.maxFiles) throw new BridgeError("bundle/too-many-files", "слишком много файлов в пакете");
+  const contentObject = requirePlainObject(body.content, "bundle/bad-content", "содержимое пакета");
+  const content = new Map();
+  const files = [];
+  const seen = new Set();
+  let totalBytes = 0;
+  for (const rawEntry of body.files) {
+    const entry = requirePlainObject(rawEntry, "bundle/bad-files", "элемент списка файлов");
+    const relativePath = safeRelPath(entry.path, limits);
+    if (!isAllowedSyncPath(relativePath)) throw new BridgeError("bundle/bad-path", `файл не входит в память проекта: ${relativePath}`);
+    if (seen.has(relativePath)) throw new BridgeError("bundle/duplicate-path", `дубликат файла в пакете: ${relativePath}`);
+    seen.add(relativePath);
+    if (typeof entry.sha256 !== "string" || !SHA256_HEX.test(entry.sha256)) {
+      throw new BridgeError("bundle/bad-hash", `некорректный хэш файла ${relativePath}`);
+    }
+    if (entry.base !== undefined && entry.base !== null && (typeof entry.base !== "string" || !SHA256_HEX.test(entry.base))) {
+      throw new BridgeError("bundle/bad-base", `некорректный base-хэш файла ${relativePath}`);
+    }
+    if (!Number.isInteger(entry.bytes) || entry.bytes < 0) throw new BridgeError("bundle/bad-size", `некорректный размер файла ${relativePath}`);
+    if (entry.bytes > limits.maxFileBytes) throw new BridgeError("bundle/file-too-large", `файл ${relativePath} больше лимита`);
+    if (!Object.prototype.hasOwnProperty.call(contentObject, relativePath)) {
+      throw new BridgeError("bundle/missing-content", `в пакете нет содержимого файла ${relativePath}`);
+    }
+    const fileText = contentObject[relativePath];
+    if (typeof fileText !== "string") throw new BridgeError("bundle/bad-content", `содержимое ${relativePath} должно быть строкой`);
+    const actual = sha256(fileText);
+    if (actual !== entry.sha256) throw new BridgeError("bundle/hash-mismatch", `хэш файла ${relativePath} не совпадает`);
+    totalBytes += Buffer.byteLength(fileText, "utf8");
+    if (totalBytes > limits.maxBundleBytes) throw new BridgeError("bundle/too-large", "распакованный пакет больше лимита");
+    content.set(relativePath, fileText);
+    files.push({ path: relativePath, sha256: actual, bytes: Buffer.byteLength(fileText, "utf8"), base: entry.base ?? null });
+  }
+  const extra = Object.keys(contentObject).filter((key) => !seen.has(key));
+  if (extra.length > 0) throw new BridgeError("bundle/unknown-content", `в пакете лишние файлы: ${extra.slice(0, 3).join(", ")}`);
+  if (hashContentMap(content) !== top.contentHash) throw new BridgeError("bundle/content-hash", "contentHash пакета не совпадает с содержимым");
+
+  return {
+    header: {
+      format: top.format,
+      version: top.version,
+      encrypted: top.encrypted === true,
+      machineId: top.machineId,
+      createdAt: top.createdAt,
+      revision: top.revision,
+      contentHash: top.contentHash,
+      keyId: typeof top.keyId === "string" ? top.keyId : null,
+    },
+    project,
+    files,
+    content,
+  };
+}