@slicedearth/whoisleuth-cli 2.3.0 → 2.4.0

package/lib/page-fingerprints.mjs

@@ -3,10 +3,11 @@
 // those intermediate representations exist only long enough to derive a digest.
 import { createHash } from 'node:crypto';
 import { analyzeStaticHtml } from "./static-html-analysis.mjs";
-const PAGE_FINGERPRINT_VERSION = 1;
-const MAX_FINGERPRINT_SOURCE_BYTES = 300000;
+import { PAGE_FINGERPRINT_VERSION, PAGE_FINGERPRINT_PARSERS, PAGE_FINGERPRINT_TOKEN_LIMITS, } from "../packages/contracts/page-fingerprints.mjs";
+import { MAX_HOMEPAGE_BYTES } from "./outbound-request-bounds.mjs";
+const MAX_FINGERPRINT_SOURCE_BYTES = MAX_HOMEPAGE_BYTES;
 const MAX_FINGERPRINT_TAG_LENGTH = 4096;
-const MAX_FINGERPRINT_TOKENS = 4096;
+const MAX_FINGERPRINT_TOKENS = PAGE_FINGERPRINT_TOKEN_LIMITS[PAGE_FINGERPRINT_VERSION];
 const MAX_FINGERPRINT_ATTRIBUTES = 64;
 const MAX_VISIBLE_TEXT_TOKENS = 8192;
 const MAX_FORM_FINGERPRINTS = 50;
@@ -15,11 +16,6 @@ const MAX_RESOURCE_HOSTS = 30;
 const MAX_IDENTIFIER_VALUES = 30;
 const CONTROL_RE = /[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/gu;
 const HAS_CONTROL_RE = /[\u0000-\u001f\u007f-\u009f]|\p{Default_Ignorable_Code_Point}/u;
-const COMMENT_RE = /<!--[\s\S]*?(?:-->|$)/g;
-const RAW_BODY_RE = /<(script|style|noscript|textarea|template)\b([^>]*)>[\s\S]*?(?:<\/\1\s*>|$)/gi;
-const MARKUP_TOKEN_RE = /<\/?[A-Za-z][A-Za-z0-9:-]*\b[^>]*>|[^<]+/g;
-const TAG_NAME_RE = /^<\s*(\/?)\s*([A-Za-z][A-Za-z0-9:-]*)/;
-const ATTRIBUTE_RE = /([^\s"'<>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
 const WORD_RE = /[\p{L}\p{N}]+/gu;
 const URL_ATTRIBUTE_NAMES = new Set(['action', 'cite', 'data', 'formaction', 'href', 'poster', 'src']);
 const OMITTED_ATTRIBUTE_NAMES = new Set(['integrity', 'nonce', 'srcdoc', 'style', 'value']);
@@ -28,16 +24,12 @@ function sha256(value) {
     return createHash('sha256').update(value).digest('hex');
 }
 function boundedSource(html) {
-    const original = Buffer.from(typeof html === 'string' ? html : String(html || ''), 'utf8');
-    const truncated = original.length > MAX_FINGERPRINT_SOURCE_BYTES;
-    const bytes = truncated ? original.subarray(0, MAX_FINGERPRINT_SOURCE_BYTES) : original;
+    const supplied = typeof html === 'string' ? html : '';
+    const prefix = Buffer.from(supplied.slice(0, MAX_FINGERPRINT_SOURCE_BYTES), 'utf8');
+    const truncated = supplied.length > MAX_FINGERPRINT_SOURCE_BYTES || prefix.length > MAX_FINGERPRINT_SOURCE_BYTES;
+    const bytes = prefix.subarray(0, MAX_FINGERPRINT_SOURCE_BYTES);
     return { bytes, text: bytes.toString('utf8'), truncated };
 }
-function staticMarkup(html) {
-    return html
-        .replace(COMMENT_RE, ' ')
-        .replace(RAW_BODY_RE, '<$1$2></$1>');
-}
 function normalizedExactBodyHash(value) {
     if (!value || typeof value !== 'object')
         return null;
@@ -56,39 +48,6 @@ function normalizedExactBodyHash(value) {
         source: 'captured-response-bytes',
     };
 }
-function parseAttributes(tag) {
-    const start = tag.search(/\s/);
-    if (start === -1)
-        return { values: new Map(), truncated: false };
-    const values = new Map();
-    let truncated = false;
-    let match;
-    ATTRIBUTE_RE.lastIndex = 0;
-    while ((match = ATTRIBUTE_RE.exec(tag.slice(start)))) {
-        const name = match[1]?.toLowerCase();
-        if (!name)
-            continue;
-        if (values.has(name))
-            continue;
-        if (values.size >= MAX_FINGERPRINT_ATTRIBUTES) {
-            truncated = true;
-            break;
-        }
-        values.set(name, match[2] ?? match[3] ?? match[4] ?? '');
-    }
-    return { values, truncated };
-}
-function decodeStableEntities(text) {
-    const named = { amp: '&', apos: "'", gt: '>', lt: '<', nbsp: ' ', quot: '"' };
-    return text.replace(/&(?:#(\d{1,7})|#x([a-f0-9]{1,6})|([a-z]{2,8}));/gi, (whole, decimal, hex, name) => {
-        if (name)
-            return named[name.toLowerCase()] ?? whole.toLowerCase();
-        const point = Number.parseInt(decimal || hex, decimal ? 10 : 16);
-        if (!Number.isInteger(point) || point <= 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff))
-            return ' ';
-        return String.fromCodePoint(point);
-    });
-}
 function looksRandom(value) {
     if (typeof value !== 'string')
         return false;
@@ -108,7 +67,7 @@ function reduceDynamicValues(value) {
         .replace(/\b(?=[a-z0-9_-]{20,}\b)(?=[a-z0-9_-]*[a-z])(?=[a-z0-9_-]*\d)[a-z0-9_-]+\b/gi, '<id>');
 }
 function normalizeText(value, maxLength = 512) {
-    const normalized = reduceDynamicValues(decodeStableEntities(String(value || '')))
+    const normalized = reduceDynamicValues(String(value || ''))
         .normalize('NFKC')
         .replace(CONTROL_RE, ' ')
         .replace(/\s+/g, ' ')
@@ -150,49 +109,33 @@ function normalizeAttribute(name, value, baseUrl) {
         return name;
     return normalized ? `${name}=${normalized}` : name;
 }
-function normalizedMarkupAndStructure(html, baseUrl) {
-    const markup = staticMarkup(html);
+function normalizedMarkupAndStructure(analysis, baseUrl) {
     const normalizedTokens = [];
-    const structureTokens = [];
+    const structureTokens = analysis.structureTokens;
     const visibleSegments = [];
-    let normalizedTruncated = false;
-    let structureTruncated = false;
+    let normalizedTruncated = analysis.structureLimitReached;
+    const structureTruncated = analysis.structureLimitReached;
     let attributesTruncated = false;
-    let oversizedTag = false;
-    let match;
-    MARKUP_TOKEN_RE.lastIndex = 0;
-    while ((match = MARKUP_TOKEN_RE.exec(markup))) {
-        const token = match[0];
-        if (token.startsWith('<')) {
-            if (token.length > MAX_FINGERPRINT_TAG_LENGTH) {
-                oversizedTag = true;
-                continue;
-            }
-            const nameMatch = token.match(TAG_NAME_RE);
-            const name = nameMatch?.[2]?.toLowerCase();
-            if (!nameMatch || !name)
-                continue;
-            const closing = Boolean(nameMatch[1]);
-            const selfClosing = !closing && (VOID_TAGS.has(name) || /\/\s*>$/.test(token));
-            const structure = closing ? `/${name}` : selfClosing ? `${name}/` : name;
-            if (structureTokens.length < MAX_FINGERPRINT_TOKENS)
-                structureTokens.push(structure);
-            else
-                structureTruncated = true;
+    const oversizedTag = analysis.elements.some((element) => element.attributesTruncated);
+    for (const token of analysis.tokens) {
+        if (token.kind !== 'text') {
             if (normalizedTokens.length >= MAX_FINGERPRINT_TOKENS) {
                 normalizedTruncated = true;
                 continue;
             }
-            if (closing) {
-                normalizedTokens.push(`</${name}>`);
+            if (token.kind === 'end') {
+                normalizedTokens.push(`</${token.name}>`);
                 continue;
             }
-            const parsed = parseAttributes(token);
-            if (parsed.truncated)
+            const element = token.element;
+            const name = element.name;
+            const selfClosing = element.html && VOID_TAGS.has(name);
+            if (element.attributesTruncated || element.attributes.length > MAX_FINGERPRINT_ATTRIBUTES)
                 attributesTruncated = true;
-            const attributes = [...parsed.values.entries()]
+            const values = new Map(element.attributes.slice(0, MAX_FINGERPRINT_ATTRIBUTES).map(({ name, value }) => [name, value]));
+            const attributes = [...values.entries()]
                 .map(([attributeName, value]) => {
-                const metaKey = name === 'meta' ? String(parsed.values.get('name') || parsed.values.get('property') || '') : '';
+                const metaKey = name === 'meta' ? String(values.get('name') || values.get('property') || '') : '';
                 if (attributeName === 'content' && /(?:csrf|nonce|session|token)/i.test(metaKey))
                     return null;
                 return normalizeAttribute(attributeName, value, baseUrl);
@@ -202,7 +145,7 @@ function normalizedMarkupAndStructure(html, baseUrl) {
             normalizedTokens.push(`<${name}${attributes.length ? ` ${attributes.join(' ')}` : ''}${selfClosing ? '/' : ''}>`);
             continue;
         }
-        const text = normalizeText(token, MAX_FINGERPRINT_SOURCE_BYTES);
+        const text = normalizeText(token.value, MAX_FINGERPRINT_SOURCE_BYTES);
         if (!text)
             continue;
         visibleSegments.push(text);
@@ -270,66 +213,55 @@ function formActionClass(value, baseUrl) {
         return 'external-insecure';
     return 'external';
 }
-function formStructureFingerprint(markup, baseUrl) {
-    const forms = [];
-    let current = null;
+function formStructureFingerprint(analysis, baseUrl) {
+    const formByElement = new Map();
+    const firstElementById = new Map();
     let formLimitReached = false;
     let controlLimitReached = false;
     let controls = 0;
-    let match;
-    MARKUP_TOKEN_RE.lastIndex = 0;
-    while ((match = MARKUP_TOKEN_RE.exec(markup))) {
-        const token = match[0];
-        if (!token.startsWith('<') || token.length > MAX_FINGERPRINT_TAG_LENGTH)
-            continue;
-        const nameMatch = token.match(TAG_NAME_RE);
-        const name = nameMatch?.[2]?.toLowerCase();
-        if (!nameMatch || !name)
-            continue;
-        const closing = Boolean(nameMatch[1]);
-        if (name === 'form') {
-            if (closing) {
-                if (current)
-                    forms.push(current);
-                current = null;
-                continue;
-            }
-            if (current)
-                forms.push(current);
-            if (forms.length >= MAX_FORM_FINGERPRINTS) {
+    for (const [index, element] of analysis.elements.entries()) {
+        const attributes = new Map(element.attributes.map(({ name, value }) => [name, value]));
+        const id = attributes.get('id');
+        if (id && !firstElementById.has(id))
+            firstElementById.set(id, index);
+        if (element.html && element.name === 'form') {
+            if (formByElement.size >= MAX_FORM_FINGERPRINTS) {
                 formLimitReached = true;
-                current = null;
                 continue;
             }
-            const attributes = parseAttributes(token).values;
             const rawMethod = normalizeText(attributes.get('method') || 'get', 20);
-            current = {
+            formByElement.set(index, {
                 method: /^[a-z]{1,20}$/.test(rawMethod) ? rawMethod : 'other',
                 action: formActionClass(attributes.get('action'), baseUrl),
                 controls: {},
-            };
+            });
+        }
+    }
+    for (const element of analysis.elements) {
+        const name = element.name;
+        if (!element.html || !['button', 'input', 'select', 'textarea'].includes(name))
             continue;
+        const attributes = new Map(element.attributes.map(({ name, value }) => [name, value]));
+        let owner = attributes.has('form') ? firstElementById.get(attributes.get('form')) ?? null : element.parent;
+        if (!attributes.has('form')) {
+            while (owner !== null && !formByElement.has(owner))
+                owner = analysis.elements[owner]?.parent ?? null;
         }
-        if (!current || closing || !['button', 'input', 'select', 'textarea'].includes(name))
+        const current = owner === null ? undefined : formByElement.get(owner);
+        if (!current)
             continue;
         if (controls >= MAX_FORM_CONTROLS) {
             controlLimitReached = true;
             continue;
         }
         controls += 1;
-        const attributes = parseAttributes(token).values;
         const rawType = name === 'input' || name === 'button'
             ? normalizeText(attributes.get('type') || (name === 'input' ? 'text' : 'submit'), 30)
             : name;
         const type = /^[a-z0-9-]{1,30}$/.test(rawType) ? `${name}:${rawType}` : `${name}:other`;
         current.controls[type] = (current.controls[type] || 0) + 1;
     }
-    if (current)
-        forms.push(current);
-    if (forms.length > MAX_FORM_FINGERPRINTS) {
-        forms.length = MAX_FORM_FINGERPRINTS;
-        formLimitReached = true;
-    }
+    const forms = [...formByElement.values()];
     for (const form of forms)
         form.controls = Object.fromEntries(Object.entries(form.controls).sort(([left], [right]) => left.localeCompare(right)));
     return forms.length ? {
@@ -337,7 +269,7 @@ function formStructureFingerprint(markup, baseUrl) {
         value: sha256(JSON.stringify(forms)),
         formCount: forms.length,
         controlCount: controls,
-        truncated: formLimitReached || controlLimitReached,
+        truncated: formLimitReached || controlLimitReached || analysis.tagLimitReached || analysis.inputLimitReached,
     } : null;
 }
 function normalizedResourceHosts(resources) {
@@ -418,21 +350,25 @@ function createPageFingerprints(html, options = {}) {
     };
     if (options.sourceTruncated === true && exact.scope === 'complete-body')
         exact = { ...exact, scope: 'captured-prefix' };
-    const normalized = normalizedMarkupAndStructure(source.text, baseUrl);
-    const parsedStructure = analyzeStaticHtml(source.text, { baseUrl });
+    const parsedStructure = !source.truncated && options.htmlAnalysis
+        ? options.htmlAnalysis : analyzeStaticHtml(source.text, { baseUrl, includeVisibleText: true });
+    const documentIncomplete = options.sourceTruncated === true || source.truncated
+        || parsedStructure.inputLimitReached || parsedStructure.tagLimitReached;
+    const treeIncomplete = documentIncomplete || parsedStructure.structureLimitReached;
+    const resolutionBase = parsedStructure.effectiveBaseUrl ?? baseUrl;
+    const normalized = normalizedMarkupAndStructure(parsedStructure, resolutionBase);
     const text = visibleTextFingerprint(normalized.visibleText);
     const structureSimilarity = simHash64(parsedStructure.structureTokens);
-    const forms = formStructureFingerprint(staticMarkup(source.text), baseUrl);
+    const forms = formStructureFingerprint(parsedStructure, resolutionBase);
     const resourceHosts = normalizedResourceHosts(options.resources);
     const identifiers = normalizedIdentifiers(options.trackingIdentifiers, options.identifiersTruncated === true);
-    const truncated = options.sourceTruncated === true || source.truncated || normalized.normalizedTruncated
-        || normalized.structureTruncated || parsedStructure.inputLimitReached || parsedStructure.tagLimitReached
-        || parsedStructure.structureLimitReached || text?.truncated === true || forms?.truncated === true
+    const truncated = treeIncomplete || normalized.normalizedTruncated
+        || normalized.structureTruncated || text?.truncated === true || forms?.truncated === true
         || resourceHosts.truncated || identifiers.truncated;
     const limitations = [
         'Fingerprints summarise capped static HTML and are comparison aids, not cryptographic proof of page authorship or intent.',
         'Visible-text SimHash is a fuzzy similarity fingerprint and must not be treated as a cryptographic digest.',
-        'DOM-structure SimHash is derived from a standards-compliant static token stream and is a review aid, not proof that two pages share an author or template.',
+        'DOM-structure and form fingerprints describe parsed ancestry and explicit form references, not every browser form-owner repair, executed behaviour or proof of a shared author.',
     ];
     if (source.truncated)
         limitations.push(`Fingerprint input was capped at ${MAX_FINGERPRINT_SOURCE_BYTES} UTF-8 bytes.`);
@@ -453,24 +389,24 @@ function createPageFingerprints(html, options = {}) {
             algorithm: 'sha256',
             value: sha256(normalized.normalizedTokens.join('\n')),
             tokenCount: normalized.normalizedTokens.length,
-            truncated: normalized.normalizedTruncated,
+            truncated: treeIncomplete || normalized.normalizedTruncated,
         },
-        visibleText: text,
+        visibleText: text ? { ...text, truncated: treeIncomplete || text.truncated } : null,
         domStructure: {
             algorithm: 'sha256',
             value: sha256(normalized.structureTokens.join('\n')),
             nodeCount: normalized.structureTokens.length,
-            parser: 'static-tag-sequence-v1',
-            truncated: normalized.structureTruncated,
+            parser: PAGE_FINGERPRINT_PARSERS[PAGE_FINGERPRINT_VERSION],
+            truncated: treeIncomplete || normalized.structureTruncated,
             similarity: structureSimilarity ? {
                 algorithm: 'simhash64-v1',
                 value: structureSimilarity.value,
                 tokenCount: parsedStructure.structureTokens.length,
                 featureCount: structureSimilarity.featureCount,
-                truncated: parsedStructure.inputLimitReached || parsedStructure.tagLimitReached || parsedStructure.structureLimitReached,
+                truncated: treeIncomplete,
             } : null,
         },
-        formStructure: forms,
+        formStructure: forms ? { ...forms, truncated: documentIncomplete || forms.truncated } : null,
         resourceHosts,
         identifiers,
         complete: !truncated,

package/lib/page-role-profile.mjs

@@ -24,13 +24,17 @@ function addFinding(findings, role, label, confidence, evidence) {
 }
 function analyzePageRole(input = {}) {
     const htmlAnalysis = input.htmlAnalysis ?? analyzeStaticHtml(input.html);
-    const markup = htmlAnalysis.markup;
+    const elements = htmlAnalysis.elements.filter((element) => element.html && element.name !== 'template');
+    // Reuse native element evidence instead of allocating and scanning a second,
+    // independently capped reconstruction of the same document.
+    const marker = (pattern) => elements.some((element) => pattern.test(element.name)
+        || element.attributes.some(({ name, value }) => pattern.test(name) || pattern.test(value.toLowerCase())));
     const title = boundedLowercase(input.pageTitle, MAX_ROLE_TITLE_CHARS);
     const activityStatus = boundedLowercase(input.activityStatus, 40);
     const forms = htmlAnalysis.forms;
     const findings = [];
     const challengeEvidence = [];
-    if (/(?:captcha|recaptcha|hcaptcha|turnstile|cf-chl|challenge-form|verify-human)/u.test(markup)) {
+    if (marker(/(?:captcha|recaptcha|hcaptcha|turnstile|cf-chl|challenge-form|verify-human)/u)) {
         challengeEvidence.push('Static challenge or human-verification marker observed');
     }
     if (/(?:just a moment|checking your browser|verify you are human|access denied)/u.test(title)) {
@@ -43,19 +47,19 @@ function analyzePageRole(input = {}) {
     if (forms.categories.username > 0 || forms.categories.email > 0) {
         authenticationEvidence.push('Username or email-purpose input observed');
     }
-    if (/(?:login|log-in|signin|sign-in|authentication|current-password|new-password)/u.test(markup)) {
+    if (marker(/(?:login|log-in|signin|sign-in|authentication|current-password|new-password)/u)) {
         authenticationEvidence.push('Static authentication marker observed');
     }
     addFinding(findings, 'authentication', 'Authentication', forms.categories.password > 0 ? 'high' : 'medium', authenticationEvidence);
     const commerceEvidence = [];
     if (forms.categories.payment > 0)
         commerceEvidence.push('Payment-purpose input observed');
-    if (/(?:checkout|shopping-cart|add-to-cart|product-price|woocommerce|shopify-payment)/u.test(markup)) {
+    if (marker(/(?:checkout|shopping-cart|add-to-cart|product-price|woocommerce|shopify-payment)/u)) {
         commerceEvidence.push('Static commerce or checkout marker observed');
     }
     addFinding(findings, 'commerce', 'Commerce', forms.categories.payment > 0 ? 'high' : 'medium', commerceEvidence);
     const supportEvidence = [];
-    if (/(?:contact|support|helpdesk|customer-service)/u.test(markup)) {
+    if (marker(/(?:contact|support|helpdesk|customer-service)/u)) {
         supportEvidence.push('Static support or contact marker observed');
     }
     if (forms.formsObserved > 0 && forms.categories.password === 0 && forms.categories.payment === 0) {
@@ -65,14 +69,14 @@ function analyzePageRole(input = {}) {
     const parkedEvidence = [];
     if (activityStatus === 'parked')
         parkedEvidence.push('Existing activity analysis classified the page as parked');
-    if (/(?:domain-for-sale|buy-this-domain|parking-page|sedoparking)/u.test(markup)) {
+    if (marker(/(?:domain-for-sale|buy-this-domain|parking-page|sedoparking)/u)) {
         parkedEvidence.push('Static domain-sale or parking marker observed');
     }
     addFinding(findings, 'parked_sale', 'Parked or for sale', activityStatus === 'parked' ? 'high' : 'medium', parkedEvidence);
     const contentEvidence = [];
-    if (/<(?:article|main)(?:\s|>)/u.test(markup))
+    if (elements.some(({ name }) => name === 'article' || name === 'main'))
         contentEvidence.push('Semantic article or main-content element observed');
-    if (/<(?:h1|h2)(?:\s|>)/u.test(markup))
+    if (elements.some(({ name }) => name === 'h1' || name === 'h2'))
         contentEvidence.push('Static heading structure observed');
     addFinding(findings, 'content', 'Content or publication', contentEvidence.length > 1 ? 'medium' : 'low', contentEvidence);
     if (!findings.length) {

package/lib/perceptual-hash.mjs

@@ -8,7 +8,7 @@
 //
 // Pure JS, no external dependency and no native bindings, so it runs the same
 // on the serverless (Netlify) and self-hosted (Express) paths. That means
-// decoding the image ourselves: Node has no built-in image decoder, only
+// decoding the image ourselves: the runtime has no built-in image decoder, only
 // zlib (used here for PNG inflate). We support the favicon formats that
 // actually occur in practice - PNG, and PNG- or BMP-encoded ICO - and return
 // null for anything else (GIF/JPEG/SVG), which simply falls back to
@@ -23,8 +23,8 @@
 import * as zlib from 'node:zlib';
 import { hammingDistanceHex, isInformativePerceptualHash, } from "./perceptual-hash-comparison.mjs";
 // Bound the decode work on attacker-controlled image bytes. Real favicons top
-// out around 256x256; anything claiming to be larger is refused rather than
-// decoded (it would also never be a legitimate favicon to compare against).
+// out around 256x256; larger inputs above this ceiling remain exact-only
+// evidence rather than causing unbounded pixel allocation.
 const MAX_DIM = 1024;
 const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
 function byteAt(bytes, index) {
@@ -70,14 +70,18 @@ function decodePng(buf) {
         const dataStart = offset + 8;
         const dataEnd = dataStart + length;
         if (dataEnd + 4 > buf.length)
-            break; // truncated chunk
+            return null;
         const data = buf.subarray(dataStart, dataEnd);
         if (type === 'IHDR') {
+            if (length !== 13 || width !== 0 || offset !== 8)
+                return null;
             width = buf.readUInt32BE(dataStart);
             height = buf.readUInt32BE(dataStart + 4);
             bitDepth = byteAt(data, 8);
             colorType = byteAt(data, 9);
             interlace = byteAt(data, 12);
+            if (byteAt(data, 10) !== 0 || byteAt(data, 11) !== 0)
+                return null;
         }
         else if (type === 'PLTE') {
             palette = data;
@@ -100,6 +104,13 @@ function decodePng(buf) {
         return null;
     if (colorType === 3 && !palette)
         return null;
+    if (palette && (palette.length < 3 || palette.length > 768 || palette.length % 3 !== 0))
+        return null;
+    if (transparency && ((colorType === 0 && transparency.length !== 2)
+        || (colorType === 2 && transparency.length !== 6)
+        || (colorType === 3 && (!palette || transparency.length > palette.length / 3))
+        || colorType === 4 || colorType === 6))
+        return null;
     if (idatParts.length === 0)
         return null;
     // A valid non-interlaced 8-bit PNG decompresses to exactly one filter byte
@@ -162,6 +173,8 @@ function decodePng(buf) {
         let alpha = 255;
         if (colorType === 0) {
             r = g = b = byteAt(recon, s);
+            if (transparency && r === transparency.readUInt16BE(0))
+                alpha = 0;
         }
         else if (colorType === 4) {
             r = g = b = byteAt(recon, s);
@@ -171,6 +184,9 @@ function decodePng(buf) {
             r = byteAt(recon, s);
             g = byteAt(recon, s + 1);
             b = byteAt(recon, s + 2);
+            if (transparency && r === transparency.readUInt16BE(0)
+                && g === transparency.readUInt16BE(2) && b === transparency.readUInt16BE(4))
+                alpha = 0;
         }
         else if (colorType === 6) {
             r = byteAt(recon, s);
@@ -200,13 +216,13 @@ function decodePng(buf) {
 // BITMAPINFOHEADER, an optional palette (for <=8-bit depths), then bottom-up
 // pixel rows. Supports the depths favicons actually ship: 1/4/8-bit
 // palettized and 24/32-bit truecolour. The stored height is doubled (it
-// includes the 1-bpp AND transparency mask); we use the real image height
-// and ignore the mask (opaque is fine for a brightness-based hash).
+// includes the 1-bpp AND transparency mask). Non-alpha and legacy all-zero
+// alpha images use that mask; meaningful 32-bit alpha remains authoritative.
 function decodeDib(buf) {
     if (buf.length < 40)
         return null;
     const headerSize = buf.readUInt32LE(0);
-    if (headerSize < 40)
+    if (headerSize < 40 || headerSize > buf.length)
         return null;
     const width = buf.readInt32LE(4);
     const rawHeight = buf.readInt32LE(8);
@@ -216,7 +232,9 @@ function decodeDib(buf) {
         return null; // BI_RGB only
     if (![1, 4, 8, 24, 32].includes(bitCount))
         return null;
-    const height = Math.floor(Math.abs(rawHeight) / 2) || Math.abs(rawHeight);
+    if (rawHeight <= 0 || rawHeight % 2 !== 0 || buf.readUInt16LE(12) !== 1)
+        return null;
+    const height = rawHeight / 2;
     if (width < 1 || height < 1 || width > MAX_DIM || height > MAX_DIM)
         return null;
     // Palette (BGRA quads) for indexed depths, sitting between the header and
@@ -235,6 +253,11 @@ function decodeDib(buf) {
     const rowSize = Math.floor((bitCount * width + 31) / 32) * 4; // padded to 4 bytes
     if (pixelStart + rowSize * height > buf.length)
         return null;
+    const maskStart = pixelStart + rowSize * height;
+    const maskRowSize = Math.ceil(width / 32) * 4;
+    const maskPresent = maskStart + maskRowSize * height <= buf.length;
+    if (bitCount !== 32 && !maskPresent)
+        return null;
     const paletteColor = (index) => {
         if (!palette || index >= palette.count)
             return [0, 0, 0];
@@ -282,11 +305,16 @@ function decodeDib(buf) {
     }
     // Many legacy 32-bit BMP-in-ICO payloads leave the alpha plane all-zero and
     // rely on the separate 1-bit AND mask for transparency. Trusting those alpha
-    // bytes literally would composite the whole icon to white and hash to a
-    // meaningless all-zero value, so treat a fully-zero alpha plane as opaque.
-    if (bitCount === 32 && !sawNonzeroAlpha) {
-        for (let i = 3; i < pixels.length; i += 4)
-            pixels[i] = 255;
+    // bytes literally would composite the whole icon to white. Restore opacity
+    // only where the legacy mask permits it. No mask plus meaningful 32-bit
+    // alpha is valid; an omitted legacy mask retains the opaque fallback.
+    if (bitCount !== 32 || !sawNonzeroAlpha) {
+        for (let y = 0; y < height; y += 1) {
+            for (let x = 0; x < width; x += 1) {
+                const mask = maskPresent ? byteAt(buf, maskStart + (height - 1 - y) * maskRowSize + (x >> 3)) : 0;
+                pixels[(y * width + x) * 4 + 3] = mask & (0x80 >> (x & 7)) ? 0 : 255;
+            }
+        }
     }
     return { width, height, pixels };
 }
@@ -428,4 +456,5 @@ function inspectDecodedImage(buf) {
 // produced by the optional local capture package. Keep the generic name as an
 // alias so the evidence contract does not imply that a screenshot is a favicon.
 const imagePerceptualHash = faviconPerceptualHash;
-export { faviconPerceptualHash, hammingDistanceHex, imagePerceptualHash, inspectDecodedImage };
+// Pixel consumers share the same strict byte/dimension admission as hashing.
+export { faviconPerceptualHash, hammingDistanceHex, imagePerceptualHash, inspectDecodedImage, decodeImage as decodeBoundedImagePixels, dHash as imagePixelsPerceptualHash };