webstore-lint 1.0.25 → 1.0.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webstore-lint",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Check an unpacked Chrome extension against the Chrome Web Store program policies before you submit it. Every finding cites Google's own notification ID and verbatim policy text. Covers the 1 August 2026 policy updates.",
   "keywords": [
     "chrome-extension",

package/src/rules.mjs

@@ -18,7 +18,7 @@
 // is worth less than none. When in doubt a rule warns and says what a human
 // must check.
 
-import { grep, grepAcross, grepLarge, largeWindows, isCode, isMarkup, codeView, excerptAround } from "./scan.mjs";
+import { grep, grepAcross, grepLarge, largeWindows, isCode, isMarkup, codeView, excerptAround, htmlCommentRanges, insideHtmlComment, offsetOf } from "./scan.mjs";
 import {
   MANIFEST_EVIDENCE, PERMISSION_API, NO_NAMESPACE_PERMISSIONS,
   namespaceUsed, looksMinified, looksMinifiedLarge, bareImports,
@@ -441,7 +441,45 @@ export const RULES = [
           evidence: website,
         }));
       }
-      split(remoteScript, (shipped, tests) => shipped.length
+      // COMMENTED-OUT TAGS ARE THEIR OWN ANSWER, NOT A FAILURE AND NOT SILENCE.
+      // A <script src> inside <!-- --> does not load and cannot be rejected for,
+      // so failing on it is the wrong-fail case that gets a linter muted. We did
+      // exactly that to google/archat, whose options/options.html carries a
+      // commented-out Google Analytics block - the single most visible repo in
+      // our corpus, reported at the highest severity the tool has.
+      //
+      // IT GETS ITS OWN LABEL RATHER THAN JOINING THE WEBSITE OR TEST WARNS
+      // (T-0620). Those two sentences say "this file probably does not ship";
+      // this one says "this file ships and the tag is one edit from live". Three
+      // different facts, three different words. Overloading one of the existing
+      // ones would tell a developer to check their build output for a file that
+      // is already in it.
+      //
+      // Measured before it was written: 14 of 703 remote <script src> sites
+      // across 6,351 HTML files in the corpus cache are inside a comment, in six
+      // distinct repos.
+      const commentCache = new Map();
+      const inComment = (h) => {
+        const f = files.find((x) => x.path === h.file);
+        if (!f) return false; // cannot tell -> resolve toward FAIL, as elsewhere in this rule
+        if (!commentCache.has(f.path)) commentCache.set(f.path, htmlCommentRanges(f.text));
+        return insideHtmlComment(commentCache.get(f.path), offsetOf(f, h.line, h.col));
+      };
+      const commentedOut = remoteScript.filter(inComment);
+      const remoteScriptLive = remoteScript.filter((h) => !inComment(h));
+      if (commentedOut.length) {
+        out.push(finding({
+          severity: "warn",
+          title: `A <script> tag loading remote code is commented out (${commentedOut.length} site(s))`,
+          detail:
+            "Every site below sits inside an HTML comment, so it does not load and Google cannot reject you for it "
+            + "as it stands. It is reported because it ships in the package and is one edit from live: if you "
+            + "uncomment it before submitting, it becomes the first trigger Google names for this category. Delete "
+            + "it, or vendor the file into the package before you re-enable it.",
+          evidence: commentedOut,
+        }));
+      }
+      split(remoteScriptLive, (shipped, tests) => shipped.length
         ? finding({
             severity: "fail",
             title: "A <script> tag loads code from outside the extension package",
@@ -665,7 +703,72 @@ export const RULES = [
         // separately so a 4 MB content script produces the same FAIL as a 4 KB
         // one; the size of the file is the tool's problem, not the developer's.
         .concat(grepLarge(oversized, EVAL_RE, { filter: isCode, code: true, accept: executesAString }));
-      split(evals, (shipped, tests) => shipped.length
+      // A DECLARED SANDBOX PAGE IS WHERE CHROME TELLS YOU TO PUT eval, and until
+      // s147 this rule FAILed the developers who followed that advice. Found by
+      // running the corpus against the new code-search index: vladlavrik/netify
+      // declares `"sandbox": {"pages": ["sandbox.html"]}` with a sandbox CSP of
+      // `... 'unsafe-inline' 'unsafe-eval'`, and its one eval site is
+      // `services/sandbox/executor/SandboxExecutor.ts` - the executor that RUNS
+      // in that page. That is the documented, sanctioned escape hatch, and we
+      // were reporting it at the top severity.
+      //
+      // This is the worst direction for a linter to be wrong in, and it is worse
+      // than the usual wrong FAIL: it fires hardest on the developer who read
+      // the policy and did the compliant thing, which is precisely the developer
+      // whose trust the tool needs.
+      //
+      // A SANDBOX DOES NOT LAUNDER THE WHOLE PACKAGE, so this is a partition and
+      // not an exemption. The manifest itself names the files that can never be
+      // sandboxed - the service worker and every declared content script - and
+      // eval in one of those is a violation whatever else the package declares.
+      // Those keep FAILing. Everything else becomes a warn that says plainly
+      // that the tool cannot tell which side of the boundary the call sits on,
+      // because from the file alone it genuinely cannot.
+      //
+      // AN EMPTY `sandbox.pages` IS NOT A SANDBOX, and a custom sandbox CSP that
+      // REMOVES 'unsafe-eval' is not one either - Chrome's default sandbox CSP
+      // grants it, so absence of a custom CSP means granted, but an explicit one
+      // that drops the token means the page cannot eval and the finding stands.
+      const sandboxPages = (manifest?.sandbox?.pages || []).filter(Boolean);
+      const sandboxCsp = manifest?.content_security_policy?.sandbox;
+      const sandboxAllowsEval = sandboxPages.length > 0
+        && (typeof sandboxCsp !== "string" || /'unsafe-eval'/.test(sandboxCsp));
+
+      // Named by the manifest, so this is not a guess about the file's role.
+      const norm = (p) => String(p).replace(/^\.?\//, "").toLowerCase();
+      const neverSandboxable = new Set();
+      if (manifest?.background?.service_worker) neverSandboxable.add(norm(manifest.background.service_worker));
+      for (const s of manifest?.background?.scripts || []) neverSandboxable.add(norm(s));
+      for (const cs of manifest?.content_scripts || []) {
+        for (const j of cs?.js || []) neverSandboxable.add(norm(j));
+      }
+
+      let evalsForSplit = evals;
+      if (sandboxAllowsEval) {
+        const hard = evals.filter((h) => neverSandboxable.has(norm(h.file)));
+        const soft = evals.filter((h) => !neverSandboxable.has(norm(h.file)));
+        evalsForSplit = hard;
+        // Emitted whenever there are any, never gated on the FAIL being absent -
+        // the same reasoning as the website partition above. A package with one
+        // service-worker eval and four sandbox-plausible ones must report all
+        // five, or the partition has quietly become a deletion.
+        if (soft.length) {
+          out.push(finding({
+            severity: "warn",
+            title: `eval() or new Function(), in a package that declares a sandboxed page (${soft.length} site(s))`,
+            detail:
+              "Your manifest declares sandbox.pages, and Chrome permits eval inside a sandboxed page - it is the "
+              + "documented way to execute a string in an extension. None of these sites is in your service worker "
+              + "or in a declared content script, so this tool cannot tell from the file alone whether they run "
+              + "inside the sandbox. If they do, they are allowed and you can ignore this. If any of them is "
+              + "reached from an ordinary extension page instead, it is still the violation Google names."
+              + ` Sandboxed page(s) declared: ${sandboxPages.join(", ")}.`,
+            evidence: soft,
+          }));
+        }
+      }
+
+      split(evalsForSplit, (shipped, tests) => shipped.length
         ? finding({
             severity: "fail",
             title: "eval() or new Function() executes a string as code",

package/src/scan.mjs

@@ -396,6 +396,52 @@ export function grepAcross(files, re, filter = () => true) {
 export const isCode = (f) => [".js", ".mjs", ".cjs", ".ts", ".jsx", ".tsx"].includes(f.ext);
 export const isMarkup = (f) => [".html", ".htm"].includes(f.ext);
 
+// Where a grepAcross hit sits in the file, from the line and column it reports.
+//
+// grepAcross deliberately returns line+col rather than the raw offset, because
+// that is what evidence carries and an extra field on a hit ends up in the
+// published report. A caller that needs the offset back can ask for it here
+// instead of every caller re-deriving it slightly differently.
+export function offsetOf(file, line, col) {
+  let at = 0;
+  for (let i = 0; i < line - 1; i++) at += (file.lines[i]?.length ?? 0) + 1; // +1 for the newline
+  return at + col;
+}
+
+// The byte ranges of every HTML comment in a document.
+//
+// WHY A LINTER NEEDS THIS AT ALL. A commented-out <script src="https://..."> is
+// not remote code. It does not load, it does not run, and Google cannot reject
+// an extension for it. Reporting one at FAIL - the highest severity this tool
+// has - is the wrong-fail case that gets a linter muted, and it happened on the
+// most visible repo in our own corpus: google/archat carries a commented-out
+// Google Analytics block in options/options.html and we called it a policy
+// violation. Measured across 6,351 HTML files in the 1,079-repo clone cache,
+// 14 of 703 remote <script src> sites (2.0%) are inside a comment.
+//
+// AN UNTERMINATED `<!--` IS TREATED AS NOT-A-COMMENT, which is deliberate and is
+// the one place this disagrees with a browser (an unclosed comment really does
+// swallow the rest of the document). The rule that uses this resolves every
+// ambiguity toward FAIL, the same convention the off-package test in rules.mjs
+// already follows, because a missed real violation is recoverable and a
+// confident wrong one is not believed twice. An unterminated comment is also
+// vanishingly rare next to the case this exists for.
+export function htmlCommentRanges(text) {
+  const ranges = [];
+  let i = 0;
+  for (;;) {
+    const open = text.indexOf("<!--", i);
+    if (open === -1) break;
+    const close = text.indexOf("-->", open + 4);
+    if (close === -1) break; // unterminated: see above, NOT a comment
+    ranges.push([open, close + 3]);
+    i = close + 3;
+  }
+  return ranges;
+}
+
+export const insideHtmlComment = (ranges, at) => ranges.some(([s, e]) => at >= s && at < e);
+
 // Blank out comments, keeping every other byte where it was.
 //
 // WHY THIS LIVES HERE rather than in the one rule that first needed it: a