feat(a11y-core): cross-origin iframe ad denylist — Type A frame-enumeration gate (AXE-3735)

build/tasks/esbuild.js

@@ -56,6 +56,15 @@ module.exports = function (grunt) {
             minify: false,
             format: 'esm',
             bundle: true,
+            // [a11y-core]: inline bundled plain-text data assets as raw strings so
+            // the client parses them at scan start with no runtime fetch. This
+            // loader lives here (not only in a11y-engine-core) BY DESIGN:
+            // a11y-engine-core/build/tasks/esbuild.js re-exports this exact task
+            // (require('../../../axe-core/build/tasks/esbuild')), so this is the
+            // loader that actually bundles a11y-engine-core/config/coi-denylist.txt
+            // (imported by lib/commons/coi-denylist.js). Only affects `.txt`
+            // imports; JS bundling is unchanged.
+            loader: { '.txt': 'text' },
             plugins: [fingerprintFallback]
           })
             .then(done)

lib/core/base/audit.js

@@ -180,6 +180,18 @@ export default class Audit {
       }
     }
   }
+  /**
+   * [a11y-core]: Store the cross-origin iframe ad denylist Set (COI denylist).
+   * Built by a11y-engine-core from its bundled list and injected via
+   * axe.configure({ crossOriginDenylist }); consumed at frame enumeration
+   * (pushUniqueFrameSelector) to skip denied ad frames. Stored by reference —
+   * never copied — so every hop points at the same Set.
+   *
+   * @param {Set<string>} crossOriginDenylist
+   */
+  setCrossOriginDenylist(crossOriginDenylist) {
+    this.crossOriginDenylist = crossOriginDenylist;
+  }
   /**
    * Initializes the rules and checks
    */
@@ -195,6 +207,10 @@ export default class Audit {
     this.tagExclude = ['experimental', 'deprecated'];
     this.noHtml = audit.noHtml;
     this.allowedOrigins = audit.allowedOrigins;
+    // [a11y-core]: carry the COI denylist Set across re-init (mirrors
+    // allowedOrigins) so child-frame audits built from the default config
+    // inherit it. Undefined when no cross-origin flag armed it.
+    this.crossOriginDenylist = audit.crossOriginDenylist;
     unpackToObject(audit.rules, this, 'addRule');
     unpackToObject(audit.checks, this, 'addCheck');
     this.data = {};

lib/core/base/context.js

@@ -6,6 +6,7 @@ import {
   getFlattenedTree,
   select,
   isNodeInContext,
+  isDeniedFrameOrigin,
   nodeSorter,
   respondable,
   clone
@@ -80,9 +81,18 @@ export default function Context(spec, flatTree) {
  * @param  {HTMLElement} frame   The frame to push onto Context
  */
 function pushUniqueFrame(context, frame) {
+  // [a11y-critical]: COI ad denylist — this is the tag-based frame-enumeration
+  // path (select('frame, iframe')) used by a full-page axe.run(document), and is
+  // the twin of the selector path gated in parse-selector-array.js. Both push
+  // sites MUST drop denied frames, otherwise a frame skipped by one path is
+  // re-added by the other (findBy dedup only matches frames already pushed). Read
+  // the Set injected via axe.configure; undefined when the Type A cross-origin
+  // flag is off => enumeration is byte-identical to main. See spec §5/§5.1.
+  const crossOriginDenylist = axe._audit && axe._audit.crossOriginDenylist;
   if (
     !isVisibleToScreenReaders(frame) ||
-    findBy(context.frames, 'node', frame)
+    findBy(context.frames, 'node', frame) ||
+    isDeniedFrameOrigin(frame, crossOriginDenylist)
   ) {
     return;
   }

lib/core/base/context/parse-selector-array.js

@@ -1,5 +1,9 @@
 import { createFrameContext } from './create-frame-context';
-import { getNodeFromTree, shadowSelectAll } from '../../utils';
+import {
+  getNodeFromTree,
+  isDeniedFrameOrigin,
+  shadowSelectAll
+} from '../../utils';
 
 /**
  * Finds frames in context, converts selectors to Element references and pushes unique frames
@@ -56,7 +60,30 @@ function pushUniqueFrameSelector(context, type, selectorArray) {
 
   const frameSelector = selectorArray.shift();
   const frames = shadowSelectAll(frameSelector);
+  // [a11y-critical]: read the COI ad denylist once for this selector group.
+  // Undefined unless a11y-engine-core armed Type A cross-origin and injected it
+  // via axe.configure — off => enumeration is byte-identical to main.
+  const crossOriginDenylist = axe._audit && axe._audit.crossOriginDenylist;
   frames.forEach(frame => {
+    // Skip ad iframes on the denylist BEFORE they enter context.frames, so they
+    // are never enumerated or traversed. This is the selector-path chokepoint
+    // (multi-element frame selectors); its twin is pushUniqueFrame in context.js,
+    // which gates the tag-based select('frame, iframe') path. BOTH must gate — a
+    // frame dropped here but not there would be re-added by the other path. The
+    // iframe element and its readable src are still in hand here — the postMessage
+    // layer one level down cannot gate on origin.
+    //
+    // BY DESIGN (spec §5 table + §5.1): Type A drops the denied frame here with a
+    // bare `return`, so it never enters context.frames and produces NO
+    // not-evaluated marker. This is intentionally asymmetric with Type B1/C
+    // (a11y-engine-core), which route denied frames through markFrameNotEvaluated
+    // to preserve the "checked-clean vs could-not-check" distinction. In Type A the
+    // frame is removed at enumeration — before any node/result exists to annotate —
+    // so there is nothing to mark; adding a marker would mean re-introducing the
+    // very frame the denylist exists to drop.
+    if (isDeniedFrameOrigin(frame, crossOriginDenylist)) {
+      return;
+    }
     let frameContext = context.frames.find(result => result.node === frame);
     if (!frameContext) {
       frameContext = createFrameContext(frame, context);

lib/core/public/configure.js

@@ -126,6 +126,14 @@ function configure(spec) {
 
     audit.setAllowedOrigins(spec.allowedOrigins);
   }
+
+  // [a11y-critical]: cross-origin iframe ad denylist (COI denylist). Sibling to
+  // allowedOrigins — a11y-engine-core builds the Set from its bundled list and
+  // passes it here so frame enumeration can skip denied ad frames. The Set is
+  // stored by reference (never serialized cross-frame). Absent/off => unchanged.
+  if (spec.crossOriginDenylist) {
+    audit.setCrossOriginDenylist(spec.crossOriginDenylist);
+  }
 }
 
 export default configure;

lib/core/utils/index.js

@@ -52,6 +52,7 @@ export {
   isLabelledShadowDomSelector,
   isLabelledFramesSelector
 } from './is-context';
+export { default as isDeniedFrameOrigin } from './is-denied-frame-origin'; // [a11y-core]: COI denylist Type A gate
 export { default as isHidden } from './is-hidden';
 export { default as isHtmlElement } from './is-html-element';
 export { default as isNodeInContext } from './is-node-in-context';

lib/core/utils/is-denied-frame-origin.js

@@ -0,0 +1,66 @@
+// [a11y-core]: Cross-Origin Iframe ad denylist (COI denylist) — Type A gate.
+//
+// a11y-engine-core builds the ad-hostname Set from its bundled config/coi-denylist.txt
+// and hands it to the fork via axe.configure({ crossOriginDenylist }) ->
+// audit.setCrossOriginDenylist (mirroring allowedOrigins). This fork is a separate
+// submodule and CANNOT import a11y-engine-core, so it carries its own copy of the
+// tiny suffix matcher here. When the Type A cross-origin flag is off, the Set is
+// never set and this returns false, keeping frame enumeration byte-identical to main.
+//
+// KEEP IN SYNC: the §1 suffix-match rule below is intentionally duplicated from
+// a11y-engine-core/lib/commons/coi-denylist.js (isDeniedHostname) because this fork
+// cannot import that package. Any change to the match semantics MUST be mirrored
+// there (and its test vectors), and vice versa. The two deliberately differ only in
+// input handling: this fork takes an iframe element and resolves/validates its src
+// (http(s)-only, relative→location.href); the core helper takes a pre-resolved
+// origin/URL string.
+
+/**
+ * True when a frame element's src origin hostname is on the ad denylist
+ * (suffix rule: host === entry OR host.endsWith('.' + entry)). Scheme, port and
+ * a trailing root-label dot are stripped before compare. srcless / srcdoc /
+ * relative / about:blank frames
+ * resolve to a same-origin or opaque host that is never on the ad list, so they
+ * are never denied. Any parse error fails open (not denied).
+ *
+ * @param {Element} frame the iframe element (its src is readable even cross-origin)
+ * @param {Set<string>} denylistSet ad-hostname Set, or undefined when the flag is off
+ * @returns {boolean}
+ */
+export default function isDeniedFrameOrigin(frame, denylistSet) {
+  if (
+    !denylistSet ||
+    typeof denylistSet.has !== 'function' ||
+    denylistSet.size === 0
+  ) {
+    return false;
+  }
+  let host;
+  try {
+    const url = new URL(frame.src, window.location.href);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+      return false;
+    }
+    // Strip a trailing root-label dot: new URL('https://doubleclick.net./x')
+    // yields hostname 'doubleclick.net.', which would evade both the exact .has()
+    // and the suffix walk. Normalize it away so a trailing-dot FQDN still matches.
+    host = url.hostname.toLowerCase().replace(/\.$/, '');
+  } catch {
+    return false;
+  }
+  if (!host) {
+    return false;
+  }
+  if (denylistSet.has(host)) {
+    return true;
+  }
+  // Walk parent suffixes: a.b.doubleclick.net -> b.doubleclick.net -> doubleclick.net
+  let idx = host.indexOf('.');
+  while (idx !== -1) {
+    if (denylistSet.has(host.slice(idx + 1))) {
+      return true;
+    }
+    idx = host.indexOf('.', idx + 1);
+  }
+  return false;
+}

test/core/base/context.js

@@ -337,6 +337,50 @@ describe('Context', () => {
     });
   });
 
+  // [a11y-critical]: COI ad denylist — assert denied frames are dropped from
+  // context.frames on the tag-based select('frame, iframe') enumeration path
+  // (the full-page scan path), not just the multi-element selector path.
+  describe('cross-origin iframe ad denylist (COI denylist)', () => {
+    let hadAudit;
+    let priorDenylist;
+    beforeEach(() => {
+      hadAudit = !!axe._audit;
+      axe._audit = axe._audit || {};
+      priorDenylist = axe._audit.crossOriginDenylist;
+    });
+    afterEach(() => {
+      if (hadAudit) {
+        axe._audit.crossOriginDenylist = priorDenylist;
+      } else {
+        axe._audit = undefined;
+      }
+    });
+
+    it('drops a denied ad iframe (keeps a benign one) via the tag-based path', () => {
+      fixture.innerHTML =
+        '<iframe id="ad" width="300" height="150" src="https://ads.doubleclick.net/tag"></iframe>' +
+        '<iframe id="ok" width="300" height="150" src="https://example.com/x"></iframe>';
+      axe._audit.crossOriginDenylist = new Set(['doubleclick.net']);
+
+      const frameNodes = new Context({ include: [['#fixture']] }).frames.map(
+        frame => frame.node
+      );
+      assert.notInclude(frameNodes, $id('ad'));
+      assert.include(frameNodes, $id('ok'));
+    });
+
+    it('enumerates all iframes when the denylist is unset (byte-identical to main)', () => {
+      fixture.innerHTML =
+        '<iframe id="ad" width="300" height="150" src="https://ads.doubleclick.net/tag"></iframe>';
+      axe._audit.crossOriginDenylist = undefined;
+
+      const frameNodes = new Context({ include: [['#fixture']] }).frames.map(
+        frame => frame.node
+      );
+      assert.include(frameNodes, $id('ad'));
+    });
+  });
+
   describe('initiator', () => {
     it('should not be clobbered', () => {
       const result = new Context({

test/core/utils/is-denied-frame-origin.js

@@ -0,0 +1,83 @@
+// [a11y-core]: COI denylist Type A gate — matcher tests (AXE-3735).
+describe('axe.utils.isDeniedFrameOrigin', () => {
+  const { isDeniedFrameOrigin } = axe.utils;
+  const denylist = new Set(['doubleclick.net', 'adnxs.com']);
+
+  it('is false when no denylist Set is provided (flag off => byte-identical)', () => {
+    assert.isFalse(
+      isDeniedFrameOrigin({ src: 'https://ads.doubleclick.net/x' })
+    );
+    assert.isFalse(
+      isDeniedFrameOrigin({ src: 'https://ads.doubleclick.net/x' }, undefined)
+    );
+  });
+
+  it('is false for an empty denylist Set', () => {
+    assert.isFalse(
+      isDeniedFrameOrigin({ src: 'https://ads.doubleclick.net/x' }, new Set())
+    );
+  });
+
+  it('denies an exact-origin frame', () => {
+    assert.isTrue(
+      isDeniedFrameOrigin({ src: 'https://doubleclick.net/tag' }, denylist)
+    );
+  });
+
+  it('denies a subdomain frame (dot-boundary suffix)', () => {
+    assert.isTrue(
+      isDeniedFrameOrigin({ src: 'https://a.b.adnxs.com/px' }, denylist)
+    );
+  });
+
+  it('does NOT deny a non-dot-boundary substring host (no false positive)', () => {
+    assert.isFalse(
+      isDeniedFrameOrigin({ src: 'https://notdoubleclick.net/x' }, denylist)
+    );
+  });
+
+  it('does NOT deny an unrelated origin', () => {
+    assert.isFalse(
+      isDeniedFrameOrigin({ src: 'https://example.com/x' }, denylist)
+    );
+  });
+
+  it('denies despite an explicit port (port is stripped)', () => {
+    assert.isTrue(
+      isDeniedFrameOrigin({ src: 'https://doubleclick.net:8080/x' }, denylist)
+    );
+  });
+
+  it('denies an uppercase host (case-insensitive)', () => {
+    assert.isTrue(
+      isDeniedFrameOrigin({ src: 'https://ADS.DOUBLECLICK.NET/x' }, denylist)
+    );
+  });
+
+  it('denies a trailing-dot FQDN (root-label dot stripped)', () => {
+    assert.isTrue(
+      isDeniedFrameOrigin({ src: 'https://doubleclick.net./x' }, denylist)
+    );
+    assert.isTrue(
+      isDeniedFrameOrigin({ src: 'https://ads.doubleclick.net./x' }, denylist)
+    );
+  });
+
+  it('is false for non-http(s) / srcless / about:blank frames (never denied)', () => {
+    assert.isFalse(isDeniedFrameOrigin({ src: '' }, denylist));
+    assert.isFalse(isDeniedFrameOrigin({ src: 'about:blank' }, denylist));
+    assert.isFalse(
+      isDeniedFrameOrigin({ src: 'data:text/html,<b>x</b>' }, denylist)
+    );
+  });
+
+  it('fails open on an unparseable src', () => {
+    assert.isFalse(isDeniedFrameOrigin({ src: 'http://' }, denylist));
+  });
+
+  it('works on a real iframe element', () => {
+    const iframe = document.createElement('iframe');
+    iframe.src = 'https://ads.doubleclick.net/pagead';
+    assert.isTrue(isDeniedFrameOrigin(iframe, denylist));
+  });
+});