OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
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 & 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> & audit]]></w:instrText></w:r></w:p>",
"Require <authorization> & 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="begin"/>' +
'<w:instrText><![CDATA[HYPERLINK "https://example.com/runbook"]]></w:instrText>' +
'<w:fldChar w:fldCharType="separate"/><w:t>Read & 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([
["�", "�"],
["�", "�"],
["�", "�"],
["�", "�"],
["�", "�"],
["�", "�"],
["퟿", "\uD7FF"],
["", "\uE000"],
["A", "A"],
["😀", "\u{1F600}"],
["", "\u{10FFFF}"],
["�", "\0"],
["", "\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 � 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 � 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);
}
});
});