diff --git a/docs/guides/native/windows-shortcut.md b/docs/guides/native/windows-shortcut.md index dd4fbd94d3..584c95569f 100644 --- a/docs/guides/native/windows-shortcut.md +++ b/docs/guides/native/windows-shortcut.md @@ -60,6 +60,10 @@ birth-droid GUIDs. Version-1 UUID MAC and timestamp values are labelled keep their folder identifiers. `ConsoleFEDataBlock` keeps the code page. `PropertyStoreDataBlock` and unrecognized signatures stay raw with SHA-256. Unknown signatures are listed and are not dropped. +When `HasExpString`, `HasDarwinID`, `HasExpIcon`, or `RunWithShimLayer` +declares a block, the terminal record lets REA report a missing block and mark +coverage partial. If parsing stops before the terminal, an unseen block remains +unknown. `observations` are derived only from those documented fields: whether arguments are present, argument character length, target extension, whether diff --git a/src/native/windows/WindowsShortcutParser.ts b/src/native/windows/WindowsShortcutParser.ts index abe05e9ad9..3e755f29f0 100644 --- a/src/native/windows/WindowsShortcutParser.ts +++ b/src/native/windows/WindowsShortcutParser.ts @@ -42,7 +42,14 @@ const isoFromUnsigned100ns = (ticks: bigint, epoch: bigint): string | null => { : new Date(Number(unixMs)).toISOString(); }; -const LINK_FLAG_NAMES: ReadonlyArray = [ +// MS-SHLLINK ยง2.1.1 identifies the ExtraData blocks declared by LinkFlags. +const LINK_FLAGS: ReadonlyArray< + readonly [ + bit: number, + name: string, + requiredExtraSignature?: keyof typeof EXTRA_SIGNATURE_NAMES, + ] +> = [ [0x00000001, "HasLinkTargetIDList"], [0x00000002, "HasLinkInfo"], [0x00000004, "HasName"], @@ -52,13 +59,13 @@ const LINK_FLAG_NAMES: ReadonlyArray = [ [0x00000040, "HasIconLocation"], [0x00000080, "IsUnicode"], [0x00000100, "ForceNoLinkInfo"], - [0x00000200, "HasExpString"], + [0x00000200, "HasExpString", 0xa0000001], [0x00000400, "RunInSeparateProcess"], - [0x00001000, "HasDarwinID"], + [0x00001000, "HasDarwinID", 0xa0000006], [0x00002000, "RunAsUser"], - [0x00004000, "HasExpIcon"], + [0x00004000, "HasExpIcon", 0xa0000007], [0x00008000, "NoPidlAlias"], - [0x00020000, "RunWithShimLayer"], + [0x00020000, "RunWithShimLayer", 0xa0000008], [0x00040000, "ForceNoLinkTrack"], [0x00080000, "EnableTargetMetadata"], [0x00100000, "DisableLinkPathTracking"], @@ -69,6 +76,7 @@ const LINK_FLAG_NAMES: ReadonlyArray = [ [0x02000000, "PreferEnvironmentPath"], [0x04000000, "KeepLocalIDListForUNCTarget"], ]; +const LINK_FLAG_NAMES = LINK_FLAGS.map(([bit, name]) => [bit, name] as const); const FILE_ATTRIBUTE_NAMES: ReadonlyArray = [ [0x00000001, "READONLY"], @@ -96,7 +104,7 @@ const DRIVE_TYPES = [ "ramdisk", ] as const; -const EXTRA_SIGNATURE_NAMES: Readonly> = { +const EXTRA_SIGNATURE_NAMES = { 0xa0000001: "EnvironmentVariableDataBlock", 0xa0000002: "ConsoleDataBlock", 0xa0000003: "TrackerDataBlock", @@ -108,6 +116,12 @@ const EXTRA_SIGNATURE_NAMES: Readonly> = { 0xa0000009: "PropertyStoreDataBlock", 0xa000000b: "KnownFolderDataBlock", 0xa000000c: "VistaAndAboveIDListDataBlock", +} as const; + +const extraSignatureName = (signature: number): string | null => { + const names: Readonly>> = + EXTRA_SIGNATURE_NAMES; + return names[signature] ?? null; }; const VIRTUAL_KEYS: Readonly> = { @@ -1201,21 +1215,6 @@ const parseIdList = async ( }; }; -const EXPECTED_EXTRA_DATA_BLOCKS = [ - { - flag: 0x00000200, - flagName: "HasExpString", - signature: 0xa0000001, - blockName: "EnvironmentVariableDataBlock", - }, - { - flag: 0x00004000, - flagName: "HasExpIcon", - signature: 0xa0000007, - blockName: "IconEnvironmentDataBlock", - }, -] as const; - const parseExtraData = async ( bytes: Buffer, walk: Walk, @@ -1277,7 +1276,7 @@ const parseExtraData = async ( offset: walk.offset, size, signature, - signature_name: EXTRA_SIGNATURE_NAMES[signature] ?? null, + signature_name: extraSignatureName(signature), decoded: decodeExtra(signature, payload, walk, walk.offset), }); walk.offset += size; @@ -1389,12 +1388,14 @@ export const parseWindowsShortcut = async ( `${String(bytes.length - walk.offset)} byte(s) follow the ExtraData TerminalBlock and are not part of the Shell Link`, ); const signatures = new Set(extraData.blocks.map((block) => block.signature)); - const unseenBlocks = EXPECTED_EXTRA_DATA_BLOCKS.filter( - ({ flag, signature }) => (flags & flag) !== 0 && !signatures.has(signature), + const unseenBlocks = LINK_FLAGS.flatMap(([bit, flagName, signature]) => + signature !== undefined && (flags & bit) !== 0 && !signatures.has(signature) + ? [{ flagName, blockName: EXTRA_SIGNATURE_NAMES[signature] }] + : [], ); // Only a TerminalBlock proves the whole section was read. Without one an // unseen block is unknown, not absent. - if (extraData.terminal_offset !== null) + if (extraData.terminal_offset !== null) { for (const { flagName, blockName } of unseenBlocks) note( walk, @@ -1402,7 +1403,7 @@ export const parseWindowsShortcut = async ( extraData.terminal_offset, `${flagName} is set and ${blockName} is absent`, ); - else if (unseenBlocks.length > 0 && walk.issues.length === 0) + } else if (unseenBlocks.length > 0 && walk.issues.length === 0) note(walk, "truncated", walk.offset, "ExtraData TerminalBlock is absent"); const reportBase = { artifact, diff --git a/tests/boundary/filesystem/windowsShortcut.test.ts b/tests/boundary/filesystem/windowsShortcut.test.ts index 03b2c4795a..b1440e326c 100644 --- a/tests/boundary/filesystem/windowsShortcut.test.ts +++ b/tests/boundary/filesystem/windowsShortcut.test.ts @@ -254,6 +254,74 @@ it.each([false, true])( }, ); +it.each([ + { + flags: 0x00001000, + flagName: "HasDarwinID", + blockName: "DarwinDataBlock", + signature: 0xa0000006, + size: 0x314, + }, + { + flags: 0x00020000, + flagName: "RunWithShimLayer", + blockName: "ShimDataBlock", + signature: 0xa0000008, + size: 0x88, + }, +])( + "uses the ExtraData terminal to establish whether $blockName is absent", + async ({ flags, flagName, blockName, signature, size }) => { + const root = await createTestTempDirectory("rea-shortcut-extra-data-"); + const service = createWindowsShortcutService(); + const bytes = windowsShortcutBytes({ + flags, + idList: null, + linkInfo: null, + extraData: [], + }); + const terminalOffset = bytes.length - 4; + const inspect = async (name: string, fixture: Buffer) => { + const path = join(root, name); + await writeFile(path, fixture); + const result = await service.inspect({ path }); + if (!result.ok) throw result.error; + return result.value.normalized_result; + }; + + expect( + await inspect("incomplete.lnk", bytes.subarray(0, terminalOffset + 1)), + ).toMatchObject({ + extra_data: { blocks: [], terminal_offset: null }, + coverage: { status: "partial", failing_offset: terminalOffset }, + issues: [{ code: "truncated", offset: terminalOffset }], + }); + expect(await inspect("terminated.lnk", bytes)).toMatchObject({ + extra_data: { blocks: [], terminal_offset: terminalOffset }, + coverage: { status: "partial", failing_offset: terminalOffset }, + header: { link_flags: { decoded: [flagName] } }, + issues: [{ code: "missing_extra_data_block", offset: terminalOffset }], + }); + + const payload = Buffer.alloc(size - 8); + payload.write("Fixture", 0, signature === 0xa0000006 ? "ascii" : "utf16le"); + const present = windowsShortcutBytes({ + flags, + idList: null, + linkInfo: null, + extraData: [{ kind: "unknown", signature, payload }], + }); + expect(await inspect("present.lnk", present)).toMatchObject({ + extra_data: { + blocks: [{ signature, signature_name: blockName, size }], + terminal_offset: present.length - 4, + }, + coverage: { status: "complete" }, + issues: [], + }); + }, +); + describe("Windows shortcut parent directory links", () => { it.skipIf(process.platform === "win32")( "rejects a parent directory link before reading through it",