fix: add opaque whiteout support and consistent cross-platform basename handling

- Handle .wh..wh..opq opaque whiteouts per OCI image spec: files in
  opaque-whiteout directories from older layers are now properly excluded
- Replace path.basename with a custom getBasename helper that handles
  both / and \ separators regardless of platform, keeping isWhitedOutFile
  and isOpaqueWhiteout consistent with removeWhiteoutPrefix
- Add tests for isOpaqueWhiteout

Author: parker-snyk

lib/extractor/index.ts

@@ -232,13 +232,19 @@ function layersWithLatestFileModifications(
 ): ExtractedLayers {
   const extractedLayers: ExtractedLayers = {};
   const removedFilesToIgnore: Set<string> = new Set();
+  const opaqueWhiteoutDirs: Set<string> = new Set();
 
   // TODO: This removes the information about the layer name, maybe we would need it in the future?
   for (const layer of layers) {
     // go over extracted files products found in this layer
     for (const filename of Object.keys(layer)) {
       // if finding a deleted file - trimming to its original file name for excluding it from extractedLayers
       // + not adding this file
+      if (isOpaqueWhiteout(filename)) {
+        // Opaque whiteout: all files in this directory from older layers should be ignored
+        opaqueWhiteoutDirs.add(path.dirname(filename));
+        continue;
+      }
       if (isWhitedOutFile(filename)) {
         removedFilesToIgnore.add(removeWhiteoutPrefix(filename));
         continue;
@@ -251,6 +257,10 @@ function layersWithLatestFileModifications(
       if (isFileInARemovedFolder(filename, removedFilesToIgnore)) {
         continue;
       }
+      // not adding files in directories covered by an opaque whiteout from a newer layer
+      if (isFileInOpaqueDir(filename, opaqueWhiteoutDirs)) {
+        continue;
+      }
       // file not already in extractedLayers
       if (!Reflect.has(extractedLayers, filename)) {
         extractedLayers[filename] = layer[filename];
@@ -267,7 +277,38 @@ function layersWithLatestFileModifications(
  * https://github.com/opencontainers/image-spec/blob/main/layer.md#whiteouts
  */
 export function isWhitedOutFile(filename: string): boolean {
-  return path.basename(filename).startsWith(".wh.");
+  return getBasename(filename).startsWith(".wh.");
+}
+
+/**
+ * Check if a file is an opaque whiteout (.wh..wh..opq).
+ * Opaque whiteouts mean "delete everything in this directory from lower layers."
+ * https://github.com/opencontainers/image-spec/blob/main/layer.md#opaque-whiteout
+ */
+export function isOpaqueWhiteout(filename: string): boolean {
+  return getBasename(filename) === ".wh..wh..opq";
+}
+
+/**
+ * Extract the basename from a path, handling both Unix and Windows separators
+ * regardless of the current platform.
+ */
+function getBasename(filename: string): string {
+  const lastSlash = Math.max(filename.lastIndexOf("/"), filename.lastIndexOf("\\"));
+  return lastSlash === -1 ? filename : filename.substring(lastSlash + 1);
+}
+
+function isFileInOpaqueDir(
+  filename: string,
+  opaqueWhiteoutDirs: Set<string>,
+): boolean {
+  const dir = path.dirname(filename);
+  for (const opaqueDir of opaqueWhiteoutDirs) {
+    if (dir === opaqueDir || dir.startsWith(opaqueDir + path.sep)) {
+      return true;
+    }
+  }
+  return false;
 }
 
 /**

lib/extractor/layer.ts

@@ -2,7 +2,7 @@ import * as Debug from "debug";
 import * as path from "path";
 import { Readable } from "stream";
 import { extract, Extract } from "tar-stream";
-import { isWhitedOutFile } from ".";
+import { isOpaqueWhiteout, isWhitedOutFile } from ".";
 import { applyCallbacks, isResultEmpty } from "./callbacks";
 import { decompressMaybe } from "./decompress-maybe";
 import { ExtractAction, ExtractedLayers } from "./types";
@@ -32,7 +32,10 @@ export async function extractImageLayer(
         const matchedActions = extractActions.filter((action) =>
           action.filePathMatches(absoluteFileName),
         );
-        if (matchedActions.length > 0) {
+        if (isOpaqueWhiteout(absoluteFileName)) {
+          // Opaque whiteout: record it so layersWithLatestFileModifications can process it
+          result[absoluteFileName] = {};
+        } else if (matchedActions.length > 0) {
           try {
             const callbackResult = await applyCallbacks(
               matchedActions,

test/lib/extractor/index.spec.ts

@@ -1,5 +1,6 @@
 import {
   getContentAsString,
+  isOpaqueWhiteout,
   isWhitedOutFile,
   removeWhiteoutPrefix,
 } from "../../../lib/extractor";
@@ -60,6 +61,32 @@ describe("isWhitedOutFile", () => {
   });
 });
 
+describe("isOpaqueWhiteout", () => {
+  test("should return true for opaque whiteout files", () => {
+    expect(isOpaqueWhiteout("/etc/.wh..wh..opq")).toBe(true);
+    expect(isOpaqueWhiteout("/.wh..wh..opq")).toBe(true);
+    expect(isOpaqueWhiteout(".wh..wh..opq")).toBe(true);
+    expect(isOpaqueWhiteout("/deeply/nested/path/.wh..wh..opq")).toBe(true);
+  });
+
+  test("should return false for regular whiteout files", () => {
+    expect(isOpaqueWhiteout("/etc/.wh.hosts")).toBe(false);
+    expect(isOpaqueWhiteout("/.wh.config")).toBe(false);
+  });
+
+  test("should return false for non-whiteout files", () => {
+    expect(isOpaqueWhiteout("/etc/hosts")).toBe(false);
+    expect(isOpaqueWhiteout("")).toBe(false);
+    expect(isOpaqueWhiteout("/")).toBe(false);
+  });
+
+  test("should return false for similar but incorrect patterns", () => {
+    expect(isOpaqueWhiteout("/etc/.wh..wh..opq.extra")).toBe(false);
+    expect(isOpaqueWhiteout("/etc/.wh..opq")).toBe(false);
+    expect(isOpaqueWhiteout("/etc/.WH..WH..OPQ")).toBe(false);
+  });
+});
+
 describe("removeWhiteoutPrefix", () => {
   test("should remove .wh. prefix from filenames without slashes", () => {
     expect(removeWhiteoutPrefix(".wh.hosts")).toBe("hosts");