Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

43.2 KB
Raw Blame
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import {
  chmod,
  mkdir,
  readFile,
  readdir,
  stat,
  symlink,
  writeFile,
} from "node:fs/promises";
import * as filesystem from "node:fs/promises";
import * as os from "node:os";
import { dirname, join, relative, sep } from "node:path";
import { afterEach, describe, expect, mock, spyOn, test } from "bun:test";
import { strToU8, zipSync } from "fflate";
import { ConfigurationError } from "../src/errors.js";
import {
  prepareKnowledgeBase,
  readKnowledgeBaseSnapshot,
} from "../src/knowledge-base.js";
import { expandHome } from "../src/runtime.js";
import { createApiTestFixtures } from "./support/temporary-directories.js";

const { temporaryDirectory, cleanup, temporaryDirectories } =
  createApiTestFixtures("codex-security-knowledge-test-");
const testPosix = process.platform === "win32" ? test.skip : test;

afterEach(cleanup);

async function extractedDocuments(path: string): Promise<string[]> {
  return await Promise.all(
    (await readdir(path)).map((name) => readFile(join(path, name), "utf8")),
  );
}

function docx(
  text: string,
  secondLine?: string,
  breakElement = "<w:br/>",
): Uint8Array {
  return docxBody(
    `<w:p><w:r><w:t>${text}</w:t>${secondLine === undefined ? "" : `${breakElement}<w:t>${secondLine}</w:t>`}</w:r></w:p>`,
  );
}

function docxBody(body: string): Uint8Array {
  return zipSync({
    "word/document.xml": strToU8(
      `<?xml version="1.0"?><w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"><w:body>${body}</w:body></w:document>`,
    ),
  });
}

function pdf(text: string): Uint8Array {
  return pdfContent(`(${text.replace(/[\\()]/gu, "\\$&")}) Tj`);
}

function pdfContent(operators: string, form?: string): Uint8Array {
  const stream = `BT /F1 12 Tf 72 720 Td ${operators} ET`;
  const font = "/Font << /F1 4 0 R >>";
  const forms = form ? " /XObject << /Word 6 0 R >>" : "";
  const objects = [
    "<< /Type /Catalog /Pages 2 0 R >>",
    "<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
    `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources << ${font}${forms} >> /Contents 5 0 R >>`,
    "<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
    `<< /Length ${Buffer.byteLength(stream)} >>\nstream\n${stream}\nendstream`,
  ];
  if (form) {
    objects.push(
      `<< /Type /XObject /Subtype /Form /BBox [0 0 300 100] /Resources << ${font} >> /Length ${Buffer.byteLength(form)} >>\nstream\n${form}\nendstream`,
    );
  }
  let output = "%PDF-1.4\n";
  const offsets = [0];
  for (const [index, object] of objects.entries()) {
    offsets.push(Buffer.byteLength(output));
    output += `${index + 1} 0 obj\n${object}\nendobj\n`;
  }
  const xref = Buffer.byteLength(output);
  output += `xref\n0 ${offsets.length}\n0000000000 65535 f \n`;
  for (const offset of offsets.slice(1)) {
    output += `${String(offset).padStart(10, "0")} 00000 n \n`;
  }
  output += `trailer\n<< /Size ${offsets.length} /Root 1 0 R >>\nstartxref\n${xref}\n%%EOF\n`;
  return new TextEncoder().encode(output);
}

describe("scan knowledge bases", () => {
  test.each(["win32", "darwin", "linux"])(
    "matches case-variant Git metadata using %s platform and filesystem rules",
    async (platform) => {
      const root = await temporaryDirectory();
      await mkdir(join(root, ".GIT"));
      await writeFile(join(root, ".GIT", "config"), "Synthetic metadata");
      await writeFile(join(root, "guide.md"), "Synthetic guide");
      const aliasesGit = await filesystem.lstat(join(root, ".git")).then(
        () => true,
        () => false,
      );
      const result = spawnSync(
        process.execPath,
        [
          "-e",
          `
      Object.defineProperty(process, "platform", { value: process.argv[1] });
      const { prepareKnowledgeBase } = await import(process.argv[2]);
      const { readdir, readFile } = await import("node:fs/promises");
      const { join } = await import("node:path");
      const prepared = await prepareKnowledgeBase([process.argv[3]]);
      try {
        console.log(JSON.stringify(await Promise.all((await readdir(prepared.path)).map(name => readFile(join(prepared.path, name), "utf8")))));
      } finally { await prepared.cleanup(); }
    `,
          platform,
          fileURLToPath(new URL("../src/knowledge-base.ts", import.meta.url)),
          root,
        ],
        { encoding: "utf8" },
      );
      expect(result.status, result.stderr).toBe(0);
      expect(JSON.parse(result.stdout).sort()).toEqual(
        platform === "win32" || aliasesGit
          ? ["Synthetic guide"]
          : ["Synthetic guide", "Synthetic metadata"],
      );
    },
  );

  test.each([
    [".git", "directory"],
    [".GIT", "directory"],
    [".GIT", "directory link"],
    [".GIT", "Git file"],
  ] as const)(
    "directory knowledge bases handle %s metadata with %s while direct files remain explicit",
    async (metadataName, metadataKind) => {
      const linked = metadataKind === "directory link";
      const gitFile = metadataKind === "Git file";
      const root = await temporaryDirectory();
      if (gitFile) {
        const template = await temporaryDirectory();
        const initialized = spawnSync(
          "git",
          [
            "init",
            "--quiet",
            `--template=${template}`,
            "--initial-branch=synthetic",
            root,
          ],
          { encoding: "utf8" },
        );
        expect(initialized.status, initialized.stderr).toBe(0);
        await filesystem.rename(join(root, ".git"), join(root, ".GIT"));
        const aliasesGit = await filesystem.lstat(join(root, ".git")).then(
          () => true,
          () => false,
        );
        // Case-insensitive filesystems cannot represent this separate Git file.
        if (!aliasesGit) await writeFile(join(root, ".git"), "gitdir: .GIT\n");
        const recognized = spawnSync(
          "git",
          ["-C", root, "rev-parse", "--absolute-git-dir"],
          { encoding: "utf8" },
        );
        expect(recognized.status, recognized.stderr).toBe(0);
        expect(await filesystem.realpath(recognized.stdout.trim())).toBe(
          await filesystem.realpath(join(root, ".GIT")),
        );
      } else {
        await mkdir(join(root, metadataName));
      }
      const metadata = join(root, metadataName, "config");
      await writeFile(
        metadata,
        (gitFile ? await readFile(metadata, "utf8") : "") +
          "[http]\nextraheader = synthetic-authorization\n",
      );
      await writeFile(
        join(root, "guide.md"),
        "Documented application behavior.",
      );
      const aliasesGit = await filesystem.lstat(join(root, ".git")).then(
        () => true,
        () => false,
      );
      if (metadataName !== ".git" && !aliasesGit) {
        if (linked) {
          await symlink(
            join(root, metadataName),
            join(root, ".git"),
            process.platform === "win32" ? "junction" : "dir",
          );
        } else {
          await mkdir(join(root, ".git"));
          await writeFile(
            join(root, ".git", "config"),
            "Separate Git metadata.",
          );
        }
      }
      const directory = await prepareKnowledgeBase([root]);
      temporaryDirectories.track(directory.path);
      expect((await extractedDocuments(directory.path)).sort()).toEqual(
        [
          "Documented application behavior.",
          ...(process.platform !== "win32" && !aliasesGit && !linked
            ? [await readFile(metadata, "utf8")]
            : []),
        ].sort(),
      );
      const explicit = await prepareKnowledgeBase([metadata]);
      temporaryDirectories.track(explicit.path);
      expect(await extractedDocuments(explicit.path)).toEqual([
        await readFile(metadata, "utf8"),
      ]);
    },
  );

  testPosix(
    "omits case-variant metadata aliases on a case-insensitive filesystem",
    async () => {
      const root = await temporaryDirectory();
      const preservedGit = join(root, ".GIT");
      await mkdir(preservedGit);
      const metadata = join(preservedGit, "config");
      await writeFile(
        metadata,
        "[http]\nextraheader = synthetic-authorization\n",
      );
      await writeFile(
        join(root, "guide.md"),
        "Documented application behavior.",
      );
      const originalStat = filesystem.stat;
      const aliasSpy = spyOn(filesystem, "stat").mockImplementation(
        async (path, options?) =>
          Reflect.apply(originalStat, filesystem, [
            path === join(root, ".git") ? preservedGit : path,
            options,
          ]),
      );
      try {
        const directory = await prepareKnowledgeBase([root]);
        temporaryDirectories.track(directory.path);
        expect(await extractedDocuments(directory.path)).toEqual([
          "Documented application behavior.",
        ]);
        const explicit = await prepareKnowledgeBase([metadata]);
        temporaryDirectories.track(explicit.path);
        expect(await extractedDocuments(explicit.path)).toEqual([
          await readFile(metadata, "utf8"),
        ]);
      } finally {
        aliasSpy.mockRestore();
      }
    },
  );

  test("prepares nested supported documents and retains requested source roots", async () => {
    const root = await temporaryDirectory();
    const nested = join(root, "architecture", "threats");
    const scope = join(root, "scope.md");
    await mkdir(nested, { recursive: true });
    await writeFile(scope, "Ignore local debug endpoints.");
    await writeFile(join(nested, "deployment.MARKDOWN"), "Public API gateway.");
    await writeFile(join(nested, "notes.txt"), "Prioritize SSRF.");
    await mkdir(join(root, ".git"));
    await writeFile(join(root, ".git", "config"), "Repository metadata.");
    await writeFile(join(nested, ".git"), "gitdir: /synthetic/metadata");
    await writeFile(join(root, "ignored.bin"), new Uint8Array([0, 1, 2]));
    await writeFile(join(root, "invalid-utf8.bin"), new Uint8Array([0xff]));

    const knowledgeBase = await prepareKnowledgeBase([scope, root, scope]);
    temporaryDirectories.track(knowledgeBase.path);

    expect(knowledgeBase.sources).toEqual([scope, root]);
    expect((await readdir(knowledgeBase.path)).sort()).toEqual([
      "0-scope.md.txt",
      "1-deployment.MARKDOWN.txt",
      "2-notes.txt.txt",
    ]);
    const documents = await extractedDocuments(knowledgeBase.path);
    expect(documents).toContain("Ignore local debug endpoints.");
    expect(documents).toContain("Public API gateway.");
    expect(documents).toContain("Prioritize SSRF.");
    expect(knowledgeBase.path.startsWith(root)).toBe(false);
    if (process.platform !== "win32") {
      expect((await stat(knowledgeBase.path)).mode & 0o777).toBe(0o700);
      for (const name of await readdir(knowledgeBase.path)) {
        expect((await stat(join(knowledgeBase.path, name))).mode & 0o777).toBe(
          0o600,
        );
      }
    }
  });

  test.each([
    ["context.json", '{"service":"Public API"}'],
    ["results.sarif", '{"version":"2.1.0","runs":[]}'],
    ["deployment.yaml", "service: public-api\n"],
    ["context.custom", "Boundary: café → gateway\n"],
    ["CONTEXT", "Public API gateway.\n"],
  ])("accepts %s directly and in nested directories", async (name, text) => {
    const root = await temporaryDirectory();
    const nested = join(root, "nested");
    await mkdir(nested);
    const source = join(nested, name);
    await writeFile(source, text);

    for (const paths of [[source], [root], [root, source]]) {
      const knowledgeBase = await prepareKnowledgeBase(paths);
      temporaryDirectories.track(knowledgeBase.path);
      expect(await extractedDocuments(knowledgeBase.path)).toEqual([text]);
      expect(knowledgeBase.sources).toEqual(paths);
    }
  });

  test.each([
    ["ASCII at the staging boundary", `${"a".repeat(246)}.md`],
    ["ASCII beyond the staging boundary", `${"a".repeat(247)}.md`],
    ["ASCII at the source boundary", `${"a".repeat(252)}.md`],
    ["multibyte UTF-8", `${"文".repeat(83)}.md`],
  ])("stages long filenames: %s", async (_description, name) => {
    const root = await temporaryDirectory();
    const paths: string[] = [];
    const contents: string[] = [];
    for (let index = 0; index < 11; index++) {
      const directory = join(root, String(index));
      await mkdir(directory);
      const source = join(directory, name);
      const text = `Document ${index}.`;
      await writeFile(source, text);
      paths.push(source);
      contents.push(text);
    }
    const scope = join(root, "scope.md");
    await writeFile(scope, "Review application boundaries.");
    paths.push(scope);
    contents.push("Review application boundaries.");

    const knowledgeBase = await prepareKnowledgeBase(paths);
    temporaryDirectories.track(knowledgeBase.path);

    expect(knowledgeBase.sources).toEqual(paths);
    expect((await extractedDocuments(knowledgeBase.path)).sort()).toEqual(
      [...contents].sort(),
    );
    expect(
      await readFile(join(knowledgeBase.path, "11-scope.md.txt"), "utf8"),
    ).toBe("Review application boundaries.");
    await knowledgeBase.cleanup();
    await expect(stat(knowledgeBase.path)).rejects.toMatchObject({
      code: "ENOENT",
    });
    expect(
      await Promise.all(paths.map((path) => readFile(path, "utf8"))),
    ).toEqual(contents);
  });

  test("cancels recursive discovery before staging knowledge-base documents", async () => {
    const root = await temporaryDirectory();
    const nested = join(root, "nested", "deeper");
    await mkdir(nested, { recursive: true });
    await writeFile(join(nested, "scope.md"), "Review application boundaries.");

    const controller = new AbortController();
    const reason = new Error("Knowledge-base discovery canceled.");
    let checks = 0;
    const signalSpy = spyOn(controller.signal, "throwIfAborted");
    signalSpy.mockImplementation(() => {
      if (++checks === 8) controller.abort(reason);
      if (controller.signal.aborted) throw controller.signal.reason;
    });
    const temporarySpy = spyOn(os, "tmpdir");

    try {
      const prepared = prepareKnowledgeBase([root], controller.signal).then(
        (knowledgeBase) => {
          temporaryDirectories.track(knowledgeBase.path);
          return knowledgeBase;
        },
      );
      await expect(prepared).rejects.toBe(reason);
      expect(temporarySpy).not.toHaveBeenCalled();
    } finally {
      signalSpy.mockRestore();
      temporarySpy.mockRestore();
    }
  });

  test("handles large nested document listings without argument overflow", async () => {
    const root = await temporaryDirectory();
    const nested = join(root, "nested");
    await mkdir(nested);
    await writeFile(join(nested, "scope.md"), "Review application boundaries.");
    const originalReaddir = filesystem.readdir;
    const listingSpy = spyOn(filesystem, "readdir").mockImplementation(
      async (...args) => {
        const entries = await Reflect.apply(originalReaddir, filesystem, args);
        return args[0] === nested ? Array(700_000).fill(entries[0]) : entries;
      },
    );

    let knowledgeBase;
    try {
      knowledgeBase = await prepareKnowledgeBase([root]);
      temporaryDirectories.track(knowledgeBase.path);
    } finally {
      listingSpy.mockRestore();
    }

    expect(await extractedDocuments(knowledgeBase.path)).toEqual([
      "Review application boundaries.",
    ]);
  });

  test("removes staged documents when knowledge-base preparation is canceled", async () => {
    const root = await temporaryDirectory();
    const staging = join(root, "staging");
    await mkdir(staging);
    const first = join(root, "first.md");
    const second = join(root, "second.md");
    await writeFile(first, "First document.");
    await writeFile(second, "Second document.");

    const controller = new AbortController();
    const reason = new Error("Knowledge-base preparation canceled.");
    const originalWriteFile = filesystem.writeFile;
    let staged = false;
    const writeSpy = spyOn(filesystem, "writeFile").mockImplementation(
      async (...args) => {
        await Reflect.apply(originalWriteFile, filesystem, args);
        staged = true;
        controller.abort(reason);
      },
    );

    try {
      await expect(
        prepareKnowledgeBase([first, second], controller.signal, staging),
      ).rejects.toBe(reason);
      expect(staged).toBe(true);
      expect(await readdir(staging)).toEqual([]);
    } finally {
      writeSpy.mockRestore();
    }
  });

  test("expands ~ in requested paths and leaves absolute and ~user paths alone", async () => {
    const home = await temporaryDirectory();
    const documents = join(home, "docs");
    await mkdir(documents, { recursive: true });
    await writeFile(join(documents, "scope.md"), "Review the payment service.");
    const previousHome = process.env["HOME"];
    const previousUserProfile = process.env["USERPROFILE"];
    process.env["HOME"] = home;
    process.env["USERPROFILE"] = home;
    try {
      const expanded = await prepareKnowledgeBase(["~/docs"]);
      temporaryDirectories.track(expanded.path);
      expect(expanded.sources).toEqual([documents]);

      const bare = await prepareKnowledgeBase(["~"]);
      temporaryDirectories.track(bare.path);
      expect(bare.sources).toEqual([home]);

      const absolute = await prepareKnowledgeBase([documents]);
      temporaryDirectories.track(absolute.path);
      expect(absolute.sources).toEqual([documents]);

      expect(expandHome("~other/docs")).toBe("~other/docs");
    } finally {
      if (previousHome === undefined) delete process.env["HOME"];
      else process.env["HOME"] = previousHome;
      if (previousUserProfile === undefined) delete process.env["USERPROFILE"];
      else process.env["USERPROFILE"] = previousUserProfile;
    }
  });

  test("extracts searchable text from PDFs and DOCX documents", async () => {
    const root = await temporaryDirectory();
    await writeFile(
      join(root, "architecture.pdf"),
      pdfContent(
        "(Policy ) Tj /F1 14 Tf (guide) Tj /F1 12 Tf 0 -14 Td (Require) Tj ET q 1 0 0 1 117.348 706 cm /Word Do Q BT",
        "BT /F1 12 Tf (authentication) Tj ET",
      ),
    );
    await writeFile(
      join(root, "threat-model.docx"),
      docx("SSRF &amp; IDOR", "Review authentication"),
    );
    await writeFile(
      join(root, "paired-break.docx"),
      docx("Authorization", "Review permissions", "<w:br></w:br>"),
    );
    await writeFile(
      join(root, "carriage-return.docx"),
      docx("Authentication", "Review sessions", "<w:cr/>"),
    );
    await writeFile(
      join(root, "paired-tab.docx"),
      docx("Role", "Capability", "<w:tab></w:tab>"),
    );
    await writeFile(
      join(root, "self-closing-tab.docx"),
      docxBody(
        '<w:p><w:pPr><w:tabs><w:tab w:val="left" w:pos="1701"/></w:tabs></w:pPr>' +
          "<w:r><w:t>User</w:t><w:tab/><w:t>Permission</w:t></w:r></w:p>",
      ),
    );
    await writeFile(
      join(root, "non-breaking-hyphen.docx"),
      docx("X", "Frame-Options", "<w:noBreakHyphen/>"),
    );
    await writeFile(
      join(root, "tracked-change.docx"),
      docxBody(
        '<w:p><w:r><w:t xml:space="preserve">Admin API is </w:t></w:r>' +
          '<w:del w:id="1" w:author="Example Author"><w:r><w:delText>public</w:delText></w:r></w:del>' +
          "<w:r><w:t>internal only</w:t></w:r></w:p>",
      ),
    );
    await writeFile(
      join(root, "tracked-move.docx"),
      docxBody(
        '<w:p><w:r><w:t xml:space="preserve">Rotate keys. </w:t></w:r>' +
          '<w:moveFrom w:id="2" w:author="Example Author"><w:r><w:t>Audit weekly.</w:t></w:r></w:moveFrom></w:p>' +
          '<w:p><w:moveTo w:id="3" w:author="Example Author"><w:r><w:t>Audit weekly.</w:t></w:r></w:moveTo></w:p>',
      ),
    );
    await writeFile(
      join(root, "content-controls.docx"),
      docxBody(
        '<w:p><w:r><w:t xml:space="preserve">Owner: </w:t></w:r>' +
          "<w:sdt><w:sdtPr><w:showingPlcHdr/></w:sdtPr><w:sdtContent>" +
          "<w:r><w:t>Click here to enter text.</w:t></w:r></w:sdtContent></w:sdt></w:p>" +
          '<w:p><w:r><w:t xml:space="preserve">Data: </w:t></w:r>' +
          '<w:sdt><w:sdtPr><w:showingPlcHdr w:val="0"/></w:sdtPr><w:sdtContent>' +
          "<w:r><w:t>Confidential</w:t></w:r>" +
          "</w:sdtContent></w:sdt></w:p>",
      ),
    );
    await writeFile(
      join(root, "field-code.docx"),
      docxBody(
        '<w:p><w:r><w:t xml:space="preserve">See </w:t><w:fldChar w:fldCharType="begin"/></w:r>' +
          '<w:r><w:instrText xml:space="preserve"> HYPERLINK "https://example.com/runbook" </w:instrText></w:r>' +
          '<w:r><w:fldChar w:fldCharType="separate"/><w:t>the runbook</w:t><w:fldChar w:fldCharType="end"/></w:r></w:p>',
      ),
    );

    const knowledgeBase = await prepareKnowledgeBase([root]);
    temporaryDirectories.track(knowledgeBase.path);
    const documents = await extractedDocuments(knowledgeBase.path);

    expect(documents).toContain("Policy guide\nRequire authentication");
    expect(documents).toContain("SSRF & IDOR\nReview authentication\n");
    expect(documents).toContain("Authorization\nReview permissions\n");
    expect(documents).toContain("Authentication\nReview sessions\n");
    expect(documents).toContain("Role\tCapability\n");
    expect(documents).toContain("User\tPermission\n");
    expect(documents).toContain("X-Frame-Options\n");
    expect(documents).toContain("Admin API is internal only\n");
    expect(documents).toContain("Rotate keys. \nAudit weekly.\n");
    expect(documents).toContain("See the runbook\n");
    expect(documents).toContain("Owner: \nData: Confidential\n");
  });

  test.each([
    [
      "an unclosed text-box field inside a main-story field result",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>HYPERLINK "https://example.com"</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>Main-before </w:t></w:r>' +
        '<w:r><w:pict xmlns:v="urn:schemas-microsoft-com:vml"><v:rect id="TextBox1" style="width:180pt;height:72pt"><v:textbox><w:txbxContent>' +
        '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>AUTHOR</w:instrText><w:t>Text-box guidance.</w:t></w:r></w:p>' +
        "</w:txbxContent></v:textbox></v:rect></w:pict></w:r>" +
        '<w:r><w:fldChar w:fldCharType="end"/><w:instrText>Main-after</w:instrText></w:r></w:p>',
      "Main-before Text-box guidance.\nMain-after\n",
    ],
    [
      "independent fields in sibling text boxes",
      "<w:p><w:r><w:t>Main-before </w:t></w:r>" +
        '<w:r><w:pict xmlns:v="urn:schemas-microsoft-com:vml"><v:rect id="TextBox1" style="width:180pt;height:72pt"><v:textbox><w:txbxContent>' +
        '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>AUTHOR</w:instrText><w:t>First text-box guidance.</w:t></w:r></w:p>' +
        "</w:txbxContent></v:textbox></v:rect></w:pict></w:r>" +
        '<w:r><w:pict xmlns:v="urn:schemas-microsoft-com:vml"><v:rect id="TextBox2" style="width:180pt;height:72pt"><v:textbox><w:txbxContent>' +
        '<w:p><w:r><w:t>Second text-box guidance.</w:t><w:fldChar w:fldCharType="end"/></w:r></w:p>' +
        "</w:txbxContent></v:textbox></v:rect></w:pict></w:r>" +
        "<w:r><w:t>Main-after</w:t></w:r></w:p>",
      "Main-before First text-box guidance.\nSecond text-box guidance.\nMain-after\n",
    ],
    [
      "ordinary runs after an unclosed field",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>AUTHOR</w:instrText></w:r></w:p>' +
        "<w:p><w:r><w:t>Require authorization</w:t></w:r></w:p>",
      "\nRequire authorization\n",
    ],
    [
      "nested field results inside an unclosed field",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>IF </w:instrText>' +
        '<w:fldChar w:fldCharType="begin"/><w:instrText>AUTHOR</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>Example Author</w:t><w:fldChar w:fldCharType="end"/>' +
        "<w:t> requires authorization</w:t></w:r></w:p>",
      "Example Author requires authorization\n",
    ],
    [
      "literal markup in standalone instruction text",
      "<w:p><w:r><w:instrText><![CDATA[Require <authorization> &amp; audit]]></w:instrText></w:r></w:p>",
      "Require <authorization> &amp; audit\n",
    ],
    [
      "field markup in XML comments",
      '<w:p><w:r><w:t>Require<!-- <w:fldChar w:fldCharType="begin"/> --></w:t>' +
        "<w:instrText> authorization</w:instrText></w:r></w:p>",
      "Require authorization\n",
    ],
    [
      "CDATA instructions and character references in field attributes",
      '<w:p><w:r><w:fldChar w:fldCharType="beg&#105;n"/>' +
        '<w:instrText><![CDATA[HYPERLINK "https://example.com/runbook"]]></w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>Read &amp; audit</w:t>' +
        '<w:fldChar w:fldCharType="end"/></w:r></w:p>',
      "Read & audit\n",
    ],
    [
      "standalone instruction text",
      "<w:p><w:r><w:t>Require </w:t><w:instrText>authorization</w:instrText><w:t> before access</w:t></w:r></w:p>",
      "Require authorization before access\n",
    ],
    [
      "instruction text used as a field result",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>AUTHOR</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:instrText>Example Author</w:instrText>' +
        '<w:fldChar w:fldCharType="end"/></w:r></w:p>',
      "Example Author\n",
    ],
    [
      "nested fields within outer instructions",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>IF </w:instrText>' +
        '<w:fldChar w:fldCharType="begin"/><w:instrText>AUTHOR</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>Example Author</w:t><w:fldChar w:fldCharType="end"/>' +
        '<w:instrText> = "Example Author" "internal" "public"</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>internal</w:t><w:fldChar w:fldCharType="end"/></w:r></w:p>',
      "internal\n",
    ],
    [
      "nested fields within an outer result",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>IF 1 = 1</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>See </w:t>' +
        '<w:fldChar w:fldCharType="begin"/><w:instrText>HYPERLINK "https://example.com/runbook"</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>the runbook</w:t><w:fldChar w:fldCharType="end"/>' +
        '<w:instrText> before access</w:instrText><w:fldChar w:fldCharType="end"/></w:r></w:p>',
      "See the runbook before access\n",
    ],
    [
      "field results spanning paragraphs",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>TOC</w:instrText>' +
        '<w:fldChar w:fldCharType="separate"/><w:t>First result paragraph</w:t></w:r></w:p>' +
        '<w:p><w:r><w:instrText>Second result paragraph</w:instrText><w:fldChar w:fldCharType="end"/></w:r></w:p>',
      "First result paragraph\nSecond result paragraph\n",
    ],
    [
      "a field without a result followed by standalone instruction text",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>XE "authorization"</w:instrText>' +
        '<w:fldChar w:fldCharType="end"/><w:instrText>Visible scope</w:instrText></w:r></w:p>',
      "Visible scope\n",
    ],
    [
      "deleted field separators and instructions",
      '<w:p><w:r><w:fldChar w:fldCharType="begin"/><w:instrText>IF </w:instrText></w:r>' +
        '<w:del w:id="2" w:author="Example Author"><w:r><w:fldChar w:fldCharType="separate"/>' +
        "<w:delInstrText>old instruction</w:delInstrText></w:r></w:del>" +
        '<w:r><w:instrText>1 = 1 "internal" "public"</w:instrText><w:fldChar w:fldCharType="separate"/>' +
        '<w:t>internal</w:t><w:fldChar w:fldCharType="end"/></w:r></w:p>',
      "internal\n",
    ],
    [
      "deleted field beginnings before standalone instruction text",
      '<w:p><w:del w:id="3" w:author="Example Author"><w:r><w:fldChar w:fldCharType="begin"/>' +
        "<w:delInstrText>removed field</w:delInstrText></w:r></w:del>" +
        "<w:r><w:instrText>Visible scope</w:instrText></w:r></w:p>",
      "Visible scope\n",
    ],
    [
      "drawing placement and relative dimensions around visible text",
      '<w:p xmlns:d="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"><w:r><w:t>Before </w:t>' +
        '<mc:AlternateContent xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006" xmlns:wps="http://schemas.microsoft.com/office/word/2010/wordprocessingShape">' +
        '<mc:Choice Requires="wps"><w:drawing><d:anchor><d:positionH relativeFrom="column"><d:align>center</d:align></d:positionH>' +
        '<d:positionV relativeFrom="paragraph"><d:posOffset><![CDATA[12700]]></d:posOffset></d:positionV>' +
        "<wps:txbx><w:txbxContent><w:p><w:r><w:t>Rule 12700.</w:t></w:r></w:p></w:txbxContent></wps:txbx>" +
        '<sizeRelH xmlns="http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing"><pctWidth>75000</pctWidth></sizeRelH>' +
        '</d:anchor></w:drawing></mc:Choice><mc:Fallback><w:pict><v:textbox xmlns:v="urn:schemas-microsoft-com:vml">' +
        '<div xmlns:d="urn:example:format">Rule <d:align>12700.</d:align></div></v:textbox></w:pict></mc:Fallback></mc:AlternateContent>' +
        "<w:drawing><d:anchor><d:positionH><d:posOffset>25400</d:posOffset></d:positionH></d:anchor></w:drawing>" +
        "<w:t> After.</w:t></w:r></w:p>",
      "Before Rule 12700.\nRule 12700. After.\n",
    ],
  ])("preserves DOCX text with %s", async (_description, body, expected) => {
    const root = await temporaryDirectory();
    const source = join(root, "field-context.docx");
    await writeFile(source, docxBody(body));

    const snapshot = await readKnowledgeBaseSnapshot([source]);

    expect(Object.values(snapshot.documents)).toEqual([expected]);
  });

  test.each([
    [
      "CDATA between text nodes",
      "Require <![CDATA[authorization]]> before access",
      "Require authorization before access",
    ],
    [
      "comments containing markup",
      "Require<!-- x > hidden <w:tab/> --> authorization",
      "Require authorization",
    ],
    [
      "processing instructions",
      "Require<?note x > hidden?> authorization",
      "Require authorization",
    ],
  ])("preserves DOCX text with %s", async (_name, xml, expected) => {
    const root = await temporaryDirectory();
    const source = join(root, "guide.docx");
    await writeFile(source, docx(xml));

    const prepared = await prepareKnowledgeBase([source]);
    temporaryDirectories.track(prepared.path);
    expect(await extractedDocuments(prepared.path)).toEqual([`${expected}\n`]);
  });

  test("keeps quoted XML attributes out of DOCX text", async () => {
    const root = await temporaryDirectory();
    const source = join(root, "guide.docx");
    await writeFile(
      source,
      docx("Authorization", "Review permissions", '<w:br note="x > y"/>'),
    );

    const prepared = await prepareKnowledgeBase([source]);
    temporaryDirectories.track(prepared.path);
    expect(await extractedDocuments(prepared.path)).toEqual([
      "Authorization\nReview permissions\n",
    ]);
  });

  test.each([
    ["preparation", prepareKnowledgeBase],
    ["snapshot extraction", readKnowledgeBaseSnapshot],
  ] as const)(
    "preserves the local origin and cause of document parser failures during %s",
    async (_name, prepare) => {
      const root = await temporaryDirectory();
      const source = join(root, "network-security.pdf");
      await writeFile(source, pdf("Network design"));
      const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
      const cause = new Error("Synthetic parser failure.");
      const parser = spyOn(pdfjs, "getDocument").mockImplementation(() => {
        throw cause;
      });

      try {
        const prepared = prepare([source]);
        await expect(prepared).rejects.toBeInstanceOf(ConfigurationError);
        await expect(prepared).rejects.toMatchObject({
          message: `Cannot extract text from knowledge base PDF: ${source}`,
          cause: { cause },
        });
      } finally {
        parser.mockRestore();
      }
    },
  );

  test("cancels PDF extraction when the scan is aborted", async () => {
    const root = await temporaryDirectory();
    const source = join(root, "large.pdf");
    await writeFile(source, pdf("Cancellable content"));
    const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
    const controller = new AbortController();
    const reason = new Error("Synthetic cancellation.");
    let pagesRead = 0;
    const destroy = mock(async () => {});
    const parser = spyOn(pdfjs, "getDocument").mockImplementation(
      () =>
        ({
          promise: Promise.resolve({
            numPages: 3,
            getPage: async () => {
              pagesRead += 1;
              return {
                getTextContent: async () => {
                  controller.abort(reason);
                  return { items: [{ str: "page" }] };
                },
              };
            },
          }),
          destroy,
        }) as never,
    );

    try {
      const prepared = prepareKnowledgeBase([source], controller.signal);
      await expect(prepared).rejects.toBe(reason);
      expect(pagesRead).toBe(1);
      expect(destroy).toHaveBeenCalledTimes(1);
    } finally {
      parser.mockRestore();
    }
  });

  test("preserves the local origin and cause when snapshot staging fails", async () => {
    const root = await temporaryDirectory();
    const parent = join(root, "not-a-directory");
    await writeFile(parent, "synthetic occupied path");
    const prepared = prepareKnowledgeBase(
      {
        sources: [],
        protectedRoots: [],
        documents: { "0.txt": "Synthetic knowledge" },
      },
      undefined,
      parent,
    );
    await expect(prepared).rejects.toBeInstanceOf(ConfigurationError);
    await expect(prepared).rejects.toMatchObject({ cause: expect.any(Error) });
    expect(await readFile(parent, "utf8")).toBe("synthetic occupied path");
  });

  test.each([
    ["&#x110000;", "&#x110000;"],
    ["&#1114112;", "&#1114112;"],
    ["&#99999999999999;", "&#99999999999999;"],
    ["&#xD800;", "&#xD800;"],
    ["&#xDFFF;", "&#xDFFF;"],
    ["&#55296;", "&#55296;"],
    ["&#xD7FF;", "\uD7FF"],
    ["&#xE000;", "\uE000"],
    ["&#65;", "A"],
    ["&#128512;", "\u{1F600}"],
    ["&#x10FFFF;", "\u{10FFFF}"],
    ["&#0;", "\0"],
    ["&#x1;", "\x01"],
  ])(
    "decodes DOCX Unicode scalar references and preserves unusable ones: %s",
    async (reference, expected) => {
      const root = await temporaryDirectory();
      await writeFile(join(root, "reference.docx"), docx(`Text ${reference}.`));
      const knowledgeBase = await prepareKnowledgeBase([root]);
      temporaryDirectories.track(knowledgeBase.path);
      const documents = await extractedDocuments(knowledgeBase.path);
      expect(documents).toEqual([`Text ${expected}.\n`]);
    },
  );

  test("keeps one unusable reference from failing the other knowledge-base documents", async () => {
    const root = await temporaryDirectory();
    await writeFile(join(root, "notes.md"), "Authentication boundary notes");
    await writeFile(
      join(root, "threat-model.docx"),
      docx("Boundary &#x110000; case."),
    );

    const knowledgeBase = await prepareKnowledgeBase([root]);
    temporaryDirectories.track(knowledgeBase.path);
    const documents = await extractedDocuments(knowledgeBase.path);

    expect(documents).toHaveLength(2);
    expect(documents).toContain("Authentication boundary notes");
    expect(documents).toContain("Boundary &#x110000; case.\n");
  });

  test("skips Office owner files and LibreOffice lock files during discovery", async () => {
    const root = await temporaryDirectory();
    await writeFile(join(root, "policy.docx"), docx("Access policy."));
    await writeFile(join(root, "~$policy.docx"), new Uint8Array(162).fill(1));
    await writeFile(
      join(root, ".~lock.policy.docx#"),
      ",Example User,example-host,01.01.2026 09:00,file:///home/example/.config/libreoffice/4;",
    );
    await writeFile(join(root, ".~lock.#"), "Named document");

    const knowledgeBase = await prepareKnowledgeBase([root]);
    temporaryDirectories.track(knowledgeBase.path);

    expect((await extractedDocuments(knowledgeBase.path)).sort()).toEqual([
      "Access policy.\n",
      "Named document",
    ]);
  });

  test.each(["relative", "linked parent"])(
    "stages knowledge in the worker-readable temporary directory: %s",
    async (spelling) => {
      const root = await temporaryDirectory();
      const source = join(root, "policy.md");
      await writeFile(source, "Synthetic policy.");
      const staging = join(root, "staging");
      await mkdir(staging);
      let temporary = relative(process.cwd(), staging);
      if (spelling === "linked parent") {
        const child = join(staging, "child");
        const link = join(root, "alias");
        await mkdir(child);
        await symlink(
          child,
          link,
          process.platform === "win32" ? "junction" : "dir",
        );
        temporary = link + sep + "..";
      }
      const expected = await filesystem.realpath(temporary);
      using _temporary = spyOn(os, "tmpdir").mockReturnValue(temporary);
      const prepared = await prepareKnowledgeBase([source]);
      expect(dirname(prepared.path)).toBe(expected);
      expect(await extractedDocuments(prepared.path)).toEqual([
        "Synthetic policy.",
      ]);
    },
  );

  test("skips macOS metadata files copied next to documents", async () => {
    const root = await temporaryDirectory();
    await writeFile(join(root, "guide.md"), "Rotate admin keys monthly.");
    await writeFile(join(root, "policy.pdf"), pdf("Access policy."));
    await writeFile(join(root, "._policy.md"), "Keep audit records.");
    const appleDouble = Buffer.alloc(82);
    appleDouble.write("\x00\x05\x16\x07\x00\x02\x00\x00Mac OS X", "latin1");
    await writeFile(join(root, "._guide.md"), appleDouble);
    await writeFile(join(root, "._policy.pdf"), appleDouble);

    const knowledgeBase = await prepareKnowledgeBase([root]);
    temporaryDirectories.track(knowledgeBase.path);

    expect((await extractedDocuments(knowledgeBase.path)).sort()).toEqual([
      "Access policy.",
      "Keep audit records.",
      "Rotate admin keys monthly.",
    ]);
  });

  test("cleans up documents and rediscovers directory contents on later runs", async () => {
    const root = await temporaryDirectory();
    const source = join(root, "scope.md");
    await writeFile(source, "Initial scope");
    const first = await prepareKnowledgeBase([root]);
    await first.cleanup();
    await expect(stat(first.path)).rejects.toMatchObject({ code: "ENOENT" });
    expect(await readFile(source, "utf8")).toBe("Initial scope");

    await writeFile(source, "Updated scope");
    await writeFile(join(root, "priorities.txt"), "New attack priorities");
    const second = await prepareKnowledgeBase(first.sources);
    temporaryDirectories.track(second.path);
    const documents = await extractedDocuments(second.path);

    expect(documents.sort()).toEqual([
      "New attack priorities",
      "Updated scope",
    ]);
  });

  test("rejects missing paths, explicit binary files, and binary-only directories", async () => {
    const root = await temporaryDirectory();
    const unsupported = join(root, "scope.doc");
    await writeFile(unsupported, new Uint8Array([0, 1, 2]));

    await expect(prepareKnowledgeBase([""])).rejects.toThrow("cannot be empty");
    await expect(
      prepareKnowledgeBase([join(root, "missing.md")]),
    ).rejects.toThrow();
    await expect(prepareKnowledgeBase([unsupported])).rejects.toThrow(
      "contains binary data",
    );
    await expect(prepareKnowledgeBase([root])).rejects.toThrow(
      "contains no supported documents",
    );
  });

  test("rejects invalid UTF-8, malformed PDFs, and malformed DOCX files", async () => {
    const root = await temporaryDirectory();
    const invalidText = join(root, "invalid.md");
    const invalidPdf = join(root, "invalid.pdf");
    const invalidDocx = join(root, "invalid.docx");
    const invalidXml = join(root, "invalid-xml.docx");
    await writeFile(invalidText, new Uint8Array([0xc3, 0x28]));
    await writeFile(invalidPdf, "not a PDF");
    await writeFile(invalidDocx, zipSync({ "README.md": strToU8("not DOCX") }));
    await writeFile(
      invalidXml,
      zipSync({ "word/document.xml": strToU8("not XML") }),
    );

    await expect(prepareKnowledgeBase([invalidText])).rejects.toThrow(
      "not valid UTF-8",
    );
    await expect(prepareKnowledgeBase([invalidPdf])).rejects.toThrow(
      "Cannot extract text from knowledge base PDF",
    );
    await expect(prepareKnowledgeBase([invalidDocx])).rejects.toThrow(
      "Cannot extract text from knowledge base DOCX",
    );
    await expect(prepareKnowledgeBase([invalidXml])).rejects.toThrow(
      "Cannot extract text from knowledge base DOCX",
    );
  });

  testPosix(
    "a directory link before a parent traversal cannot select outside documents",
    async () => {
      const repository = await temporaryDirectory();
      const outside = await temporaryDirectory();
      await mkdir(join(outside, "child"));
      await symlink(join(outside, "child"), join(repository, "context"));
      await writeFile(join(outside, "guide.md"), "External data");
      const requested = `${repository}/context/../guide.md`;
      await expect(prepareKnowledgeBase([requested])).rejects.toThrow();
      await writeFile(join(repository, "guide.md"), "Repository guide");
      const prepared = await prepareKnowledgeBase([requested]);
      temporaryDirectories.track(prepared.path);
      expect(await extractedDocuments(prepared.path)).toEqual([
        "Repository guide",
      ]);
    },
  );

  testPosix("does not follow symbolic links", async () => {
    const root = await temporaryDirectory();
    const source = join(root, "scope.md");
    const linked = join(root, "linked.md");
    await writeFile(source, "External APIs");
    await symlink(source, linked);

    const knowledgeBase = await prepareKnowledgeBase([root]);
    temporaryDirectories.track(knowledgeBase.path);
    expect(await extractedDocuments(knowledgeBase.path)).toEqual([
      "External APIs",
    ]);
    await expect(prepareKnowledgeBase([linked])).rejects.toThrow(
      "cannot be symbolic links",
    );
  });

  test("checks each directory link on the way to an external document", async () => {
    const repository = await temporaryDirectory();
    const external = await temporaryDirectory();
    await writeFile(join(external, "guide.md"), "External policy.");
    const escape = join(repository, "outside");
    const viaRepository = join(external, "via-repository");
    const operatorAlias = join(external, "current");
    await symlink(external, escape, "junction");
    await symlink(escape, viaRepository, "junction");
    await symlink(external, operatorAlias, "junction");
    const read = (directory: string, checkout: string) =>
      readKnowledgeBaseSnapshot(
        [join(directory, "guide.md")],
        undefined,
        checkout,
      );
    await expect(read(viaRepository, repository)).rejects.toThrow(
      "repository directory links",
    );
    for (const checkout of [repository, external]) {
      expect(
        Object.values((await read(operatorAlias, checkout)).documents),
      ).toEqual(["External policy."]);
    }
  });

  testPosix("rejects unreadable source documents", async () => {
    const root = await temporaryDirectory();
    const source = join(root, "scope.md");
    await writeFile(source, "External APIs");
    await chmod(source, 0o000);

    try {
      await expect(prepareKnowledgeBase([source])).rejects.toThrow();
    } finally {
      await chmod(source, 0o600);
    }
  });
});