BIMI Record Auditor
Pricing
Pay per usage
Audit a public domain's BIMI brand-logo record and DMARC enforcement prerequisite in one API call. Optionally validates the HTTPS SVG logo. Returns score and recommendations.
Pricing
Pay per usage
Rating
0.0
(0)
Developer
Sanskar Jaiswal
Maintained by CommunityActor stats
0
Bookmarked
2
Total users
1
Monthly active users
a month ago
Last modified
Categories
Security
Limited permissionsShare
FROM apify/actor-node:22
COPY package*.json ./RUN npm --quiet set progress=false \ && npm install --omit=dev --omit=optional
COPY . ./
CMD npm start --silent{ "name": "bimi-record-auditor", "version": "0.1.0", "description": "Apify Actor that audits a domain's BIMI (Brand Indicators for Message Identification) record: selector._bimi TXT parse, v/a/l tag validation, DMARC enforcement prerequisite, optional HTTPS SVG logo fetch validation, score, grade, and recommendations.", "type": "module", "private": true, "main": "src/main.js", "scripts": { "start": "node src/main.js", "test": "node --test test/*.test.js", "lint": "node --check src/main.js" }, "dependencies": { "apify": "^3.4.5" }, "devDependencies": {}}{ "actorSpecification": 1, "name": "bimi-record-auditor", "title": "BIMI Record Auditor", "description": "Audit a public domain's BIMI email-branding record in one API call: parses selector._bimi TXT tags, verifies the DMARC enforcement prerequisite, optionally validates the HTTPS SVG logo, and returns a score and recommendations.", "version": "0.1", "buildTag": "latest", "meta": { "templateId": "js-start" }, "input": "./input_schema.json", "output": "./output_schema.json", "storages": { "dataset": "./dataset_schema.json" }, "dockerfile": "./Dockerfile", "defaultRunOptions": { "build": "latest", "timeoutSecs": 60, "memoryMbytes": 512 }}{ "actorSpecification": 1, "fields": { "type": "object", "properties": { "url": { "type": "string", "description": "The URL or domain provided as input" }, "domain": { "type": "string", "description": "Extracted domain name used for the lookups" }, "selector": { "type": "string", "description": "BIMI selector used" }, "checkedAt": { "type": "string", "format": "date-time", "description": "ISO timestamp" }, "bimiFound": { "type": "boolean", "description": "Whether a BIMI record exists" }, "recordCount": { "type": "integer", "description": "Number of BIMI TXT records found" }, "version": { "type": ["string", "null"], "description": "v= tag value (e.g. BIMI2)" }, "logoUrl": { "type": ["string", "null"], "description": "l= tag logo URL" }, "authorityUrl": { "type": ["string", "null"], "description": "a= tag authority evidence (VMC/CMC) URL" }, "dmarcPolicy": { "type": ["string", "null"], "description": "DMARC p= policy value" }, "dmarcEnforced": { "type": ["boolean", "null"], "description": "Whether DMARC is at enforcement" }, "score": { "type": "integer", "description": "BIMI readiness score from 0 to 100" }, "grade": { "type": "string", "description": "Letter grade from A to F" }, "issues": { "type": "array", "description": "Human-readable issues found" }, "recommendations": { "type": "array", "description": "Recommended fixes" } } }, "views": { "overview": { "title": "Overview", "transformation": { "fields": ["domain", "selector", "checkedAt", "bimiFound", "dmarcEnforced", "score", "grade", "issues", "recommendations"] }, "display": { "component": "table", "properties": { "domain": { "label": "Domain", "format": "text" }, "selector": { "label": "Selector", "format": "text" }, "checkedAt": { "label": "Checked", "format": "date" }, "bimiFound": { "label": "BIMI found", "format": "text" }, "dmarcEnforced": { "label": "DMARC enforced", "format": "text" }, "score": { "label": "Score", "format": "number" }, "grade": { "label": "Grade", "format": "text" }, "issues": { "label": "Issues", "format": "array" }, "recommendations": { "label": "Recommendations", "format": "array" } } } } }}{ "title": "BIMI Record Auditor", "type": "object", "schemaVersion": 1, "description": "Audit one public domain's BIMI record: parse selector._bimi TXT (v/a/l tags), verify the DMARC enforcement prerequisite, and optionally validate the HTTPS SVG logo. Returns a score, grade, and recommendations.", "properties": { "startUrl": { "title": "Domain or website URL", "type": "string", "description": "Public domain or URL to audit. The actor queries selector._bimi.<domain> and _dmarc.<domain> TXT records via a public DoH resolver. Private IP ranges are blocked.", "editor": "textfield", "prefill": "https://example.com" }, "selector": { "title": "BIMI selector", "type": "string", "description": "BIMI selector label (default: 'default'). The record is read from <selector>._bimi.<domain>.", "default": "default", "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$", "editor": "textfield" }, "checkLogo": { "title": "Validate the logo URL", "type": "boolean", "description": "Fetch the l= logo URL (HTTPS only) and validate it serves a BIMI-appropriate SVG. Disable for DNS-only audits.", "default": true, "editor": "checkbox" }, "logoMaxBytes": { "title": "Logo size limit (bytes)", "type": "integer", "description": "Maximum logo response size in bytes (default 2097152). Larger responses are rejected without reading.", "minimum": 1024, "maximum": 8388608, "default": 2097152, "editor": "number" }, "timeoutSeconds": { "title": "Network timeout (seconds)", "type": "integer", "description": "Timeout for DoH lookups and the logo fetch.", "minimum": 3, "maximum": 30, "default": 10, "unit": "seconds", "editor": "number" } }, "required": ["startUrl"]}{ "actorOutputSchemaVersion": 1, "title": "Output schema of BIMI Record Auditor", "description": "Audit results are stored in the default dataset.", "properties": { "results": { "type": "string", "title": "Audit results", "template": "{{links.apiDefaultDatasetUrl}}/items" } }}1import { Actor } from 'apify';2import dns from 'node:dns/promises';3import net from 'node:net';4import { fileURLToPath } from 'node:url';5
6const DEFAULT_TIMEOUT_SECONDS = 10;7const DEFAULT_DOH_URL = 'https://cloudflare-dns.com/dns-query';8const DEFAULT_LOGO_MAX_BYTES = 2 * 1024 * 1024;9const DEFAULT_SELECTOR = 'default';10const USER_AGENT = 'BimiRecordAuditor/0.1 (+https://console.apify.com/actors)';11const MAX_REDIRECTS = 3;12
13/* ---------------------------------------------------------------------------14 * SSRF protection — shared pattern used across URL-fetching factory actors.15 * DNS lookups resolve through node:dns and are checked against private16 * ranges; HTTP fetches revalidate every redirect target the same way.17 * ------------------------------------------------------------------------- */18
19function isPrivateIPv4(ip) {20 const parts = ip.split('.').map(Number);21 if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return false;22 const [a, b] = parts;23 return a === 1024 || (a === 172 && b >= 16 && b <= 31)25 || (a === 192 && b === 168)26 || a === 12727 || a === 028 || (a === 169 && b === 254);29}30
31function isPrivateIPv6(ip) {32 const normalized = ip.toLowerCase();33 return normalized === '::1'34 || normalized.startsWith('fc')35 || normalized.startsWith('fd')36 || normalized.startsWith('fe80:');37}38
39export async function normalizeAndValidateUrl(rawUrl, { requireHttps = false } = {}) {40 if (!rawUrl || typeof rawUrl !== 'string') throw new Error('startUrl is required');41 if (/^[a-z][a-z0-9+.-]*:/i.test(rawUrl) && !/^https?:\/\//i.test(rawUrl)) {42 throw new Error('Only HTTP and HTTPS URLs are supported');43 }44 const withScheme = /^https?:\/\//i.test(rawUrl) ? rawUrl : `https://${rawUrl}`;45 const url = new URL(withScheme);46 if (!['http:', 'https:'].includes(url.protocol)) throw new Error('Only HTTP and HTTPS URLs are supported');47 if (requireHttps && url.protocol !== 'https:') throw new Error('BIMI logo URLs must use HTTPS');48 if (!url.hostname || url.username || url.password) throw new Error('URL must be public and must not include credentials');49
50 // WHATWG URLs keep brackets in hostname for IPv6 literals; strip them for51 // the net.isIP literal checks or bracketed private IPv6 slips through.52 const bareHostname = url.hostname.startsWith('[') && url.hostname.endsWith(']')53 ? url.hostname.slice(1, -1)54 : url.hostname;55 const literalType = net.isIP(bareHostname);56 if (literalType === 4 && isPrivateIPv4(bareHostname)) throw new Error('Private IPv4 targets are blocked');57 if (literalType === 6 && isPrivateIPv6(bareHostname)) throw new Error('Private IPv6 targets are blocked');58
59 const records = literalType60 ? [{ address: url.hostname, family: literalType }]61 : await dns.lookup(url.hostname, { all: true });62 for (const record of records) {63 if (record.family === 4 && isPrivateIPv4(record.address)) throw new Error('DNS resolves to a private IPv4 address; blocked for SSRF safety');64 if (record.family === 6 && isPrivateIPv6(record.address)) throw new Error('DNS resolves to a private IPv6 address; blocked for SSRF safety');65 }66 return url;67}68
69function clampInteger(value, fallback, min, max) {70 const parsed = Number(value);71 if (!Number.isFinite(parsed)) return fallback;72 return Math.min(Math.max(Math.trunc(parsed), min), max);73}74
75/* ---------------------------------------------------------------------------76 * DoH TXT lookup (public resolver JSON API, no auth)77 * Cloudflare returns TXT data with surrounding quotes; strip them.78 * ------------------------------------------------------------------------- */79
80async function dohTxt(name, timeoutSeconds, dohUrl) {81 const controller = new AbortController();82 const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);83 try {84 const url = `${dohUrl}?name=${encodeURIComponent(name)}&type=TXT`;85 const res = await fetch(url, {86 headers: { accept: 'application/dns-json' },87 signal: controller.signal,88 });89 if (!res.ok) throw new Error(`DoH resolver returned HTTP ${res.status}`);90 const body = await res.json();91 if (!body || body.Status === undefined) throw new Error('DoH resolver returned an invalid response');92 const answers = Array.isArray(body.Answer) ? body.Answer : [];93 return answers94 .filter((a) => a && a.type === 16)95 .map((a) => {96 let data = typeof a.data === 'string' ? a.data : '';97 if (data.length >= 2 && data.startsWith('"') && data.endsWith('"')) data = data.slice(1, -1);98 return data;99 });100 } finally {101 clearTimeout(timer);102 }103}104
105/* ---------------------------------------------------------------------------106 * HTTP fetch with manual redirect revalidation (SSRF-safe), used only for107 * the BIMI logo URL when the user opts in. Never fetches arbitrary inputs.108 * ------------------------------------------------------------------------- */109
110async function fetchLogo(initialUrl, timeoutSeconds, maxBytes, redirectsRemaining = MAX_REDIRECTS) {111 const url = await normalizeAndValidateUrl(initialUrl.href, { requireHttps: true });112 const controller = new AbortController();113 const timer = setTimeout(() => controller.abort(), timeoutSeconds * 1000);114 try {115 const response = await fetch(url, {116 redirect: 'manual',117 signal: controller.signal,118 headers: {119 'user-agent': USER_AGENT,120 accept: 'image/svg+xml,image/*;q=0.8,*/*;q=0.1',121 },122 });123
124 if ([301, 302, 303, 307, 308].includes(response.status)) {125 if (redirectsRemaining <= 0) throw new Error('Too many redirects');126 const location = response.headers.get('location');127 if (!location) throw new Error('Redirect without Location header');128 const nextUrl = new URL(location, url.href);129 try { await response.arrayBuffer(); } catch { /* drain */ }130 return fetchLogo(nextUrl, timeoutSeconds, maxBytes, redirectsRemaining - 1);131 }132
133 const contentType = (response.headers.get('content-type') || '').split(';')[0].trim().toLowerCase() || null;134 const contentLengthHeader = response.headers.get('content-length');135 const declaredLength = contentLengthHeader !== null ? Number(contentLengthHeader) : null;136 if (declaredLength !== null && Number.isFinite(declaredLength) && declaredLength > maxBytes) {137 try { await response.arrayBuffer(); } catch { /* drain */ }138 throw new Error(`Logo response exceeds the ${maxBytes}-byte limit (Content-Length: ${declaredLength})`);139 }140
141 let buffer = Buffer.alloc(0);142 try {143 const arrayBuffer = await response.arrayBuffer();144 buffer = Buffer.from(arrayBuffer);145 } catch (error) {146 if (error && error.name === 'AbortError') throw error;147 throw new Error(`Logo fetch failed: ${error.message}`);148 }149 if (buffer.length > maxBytes) {150 throw new Error(`Logo body exceeds the ${maxBytes}-byte limit (${buffer.length} bytes)`);151 }152 return {153 status: response.status,154 contentType,155 contentLength: buffer.length,156 buffer,157 };158 } finally {159 clearTimeout(timer);160 }161}162
163/* ---------------------------------------------------------------------------164 * BIMI record parsing (BIMI Core spec)165 * Record lives at selector._bimi.<domain>. Required tag: l. Optional: v, a.166 * v = version; a = authority evidence location; l = logo location.167 * For legacy-marked records (v=BIMI1), an authority evidence location (a) is168 * REQUIRED; for BIMI2/other versions it is optional (VMC check delegated).169 * ------------------------------------------------------------------------- */170
171const SELECTOR_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;172const KNOWN_VERSIONS = ['bimi1', 'bimi2', 'bimi3'];173
174export function parseBimiTagValue(data) {175 if (typeof data !== 'string' || data.trim().length === 0) return null;176 const m = data.trim().match(/^([a-z0-9]+)\s*=\s*(.*)$/i);177 if (!m) return null;178 return { tag: m[1].toLowerCase(), value: m[2] };179}180
181export function parseBimiRecord(recordText, expectedSelector) {182 const result = {183 selector: expectedSelector || null,184 raw: typeof recordText === 'string' ? recordText : '',185 tags: {},186 tagIssues: [],187 version: null,188 logoUrl: null,189 authorityUrl: null,190 parseError: null,191 };192 if (typeof recordText !== 'string' || recordText.trim().length === 0) {193 result.parseError = 'record is empty';194 return result;195 }196 // BIMI records separate tag=value pairs with ';' (and optionally spaces):197 // e.g. "v=BIMI1;l=https://example.com/logo.svg". Split on both; trailing198 // semicolons yield empty segments which are skipped.199 const parts = recordText.trim().split(/[;\s]+/).filter((p) => p.length > 0);200 for (const part of parts) {201 const parsed = parseBimiTagValue(part);202 if (!parsed) {203 result.tagIssues.push(`unparseable segment '${part}' (expected tag=value pairs)`);204 continue;205 }206 if (result.tags[parsed.tag] !== undefined) {207 result.tagIssues.push(`duplicate tag '${parsed.tag}'`);208 continue;209 }210 result.tags[parsed.tag] = parsed.value;211 }212 result.version = result.tags.v !== undefined ? result.tags.v.toLowerCase() : null;213 result.logoUrl = result.tags.l !== undefined ? result.tags.l : null;214 result.authorityUrl = result.tags.a !== undefined ? result.tags.a : null;215 return result;216}217
218export function analyzeBimiRecord(record, dmarcEnforced) {219 const issues = [];220 const rec = { ...record, issues };221
222 // Required tag: l (logo location).223 if (rec.logoUrl === null) {224 issues.push('missing required l= tag (logo location URL)');225 } else {226 try {227 const url = new URL(rec.logoUrl);228 if (url.protocol !== 'https:') {229 issues.push(`logo URL '${rec.logoUrl}' must use HTTPS (BIMI requires https)`);230 }231 if (url.username || url.password) issues.push('logo URL contains credentials');232 if (net.isIP(url.hostname) === 4 && isPrivateIPv4(url.hostname)) issues.push('logo URL targets a private IPv4 address');233 if (net.isIP(url.hostname) === 6 && isPrivateIPv6(url.hostname)) issues.push('logo URL targets a private IPv6 address');234 } catch {235 issues.push(`logo URL '${rec.logoUrl}' is not an absolute URL`);236 }237 }238
239 // Version tag.240 if (rec.version === null) {241 issues.push('missing v= version tag; BIMI2+ receivers may reject the record');242 } else if (!KNOWN_VERSIONS.includes(rec.version)) {243 issues.push(`unknown version '${rec.version}' (known versions: ${KNOWN_VERSIONS.join(', ')})`);244 }245
246 // Authority evidence location.247 if (rec.authorityUrl === null) {248 if (rec.version === 'bimi1') {249 issues.push('BIMI1 records require an a= authority evidence location (VMC/CMC certificate)');250 } else {251 issues.push('no a= authority evidence location; large receivers (Gmail, Apple Mail) require a Verified Mark Certificate for logo display');252 }253 } else {254 try {255 const url = new URL(rec.authorityUrl);256 if (url.protocol !== 'https:') {257 issues.push(`authority evidence URL '${rec.authorityUrl}' must use HTTPS`);258 }259 if (url.username || url.password) issues.push('authority evidence URL contains credentials');260 if (net.isIP(url.hostname) === 4 && isPrivateIPv4(url.hostname)) issues.push('authority evidence URL targets a private IPv4 address');261 if (net.isIP(url.hostname) === 6 && isPrivateIPv6(url.hostname)) issues.push('authority evidence URL targets a private IPv6 address');262 } catch {263 issues.push(`authority evidence URL '${rec.authorityUrl}' is not an absolute URL`);264 }265 }266
267 // Legacy BIMI1 without authority evidence is explicitly not logo-displayable.268 if (rec.version === 'bimi1' && rec.authorityUrl === null) {269 issues.push('legacy BIMI1 record without a= is not displayable — upgrade to v=BIMI2 with an a= VMC/CMC URL');270 }271
272 // Record syntax issues.273 if (rec.tagIssues.length > 0) issues.push(...rec.tagIssues);274
275 // DMARC prerequisite.276 if (dmarcEnforced === false) {277 issues.push('DMARC is not at enforcement (p=quarantine/reject) — receivers MUST NOT display the BIMI logo per spec');278 } else if (dmarcEnforced === null) {279 issues.push('DMARC policy could not be determined — verify the _dmarc TXT record');280 }281
282 // Unknown tags.283 for (const tag of Object.keys(rec.tags)) {284 if (!['v', 'a', 'l'].includes(tag)) {285 issues.push(`unknown BIMI tag '${tag}'`);286 }287 }288 return rec;289}290
291/* ---------------------------------------------------------------------------292 * DMARC prerequisite check (RFC 7489 / BIMI spec: p must be quarantine or293 * reject). TXT lookup at _dmarc.<domain>.294 * ------------------------------------------------------------------------- */295
296export function parseDmarcPolicy(txtStrings) {297 if (!Array.isArray(txtStrings) || txtStrings.length === 0) return null;298 // Prefer the record that starts with v=DMARC1299 const dmarc = txtStrings.find((s) => /^v\s*=\s*DMARC1/i.test(s.trim()));300 if (!dmarc) return null;301 const policyMatch = dmarc.match(/\bp\s*=\s*([a-z]+)/i);302 if (!policyMatch) return null;303 return policyMatch[1].toLowerCase();304}305
306export function isDmarcEnforced(policy) {307 return policy === 'quarantine' || policy === 'reject';308}309
310/* ---------------------------------------------------------------------------311 * Logo validation312 * ------------------------------------------------------------------------- */313
314export async function validateLogo(logoUrl, options = {}) {315 const timeoutSeconds = clampInteger(options.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS, 3, 30);316 const maxBytes = clampInteger(options.maxLogoBytes, DEFAULT_LOGO_MAX_BYTES, 1024, 8 * 1024 * 1024);317
318 const validation = {319 checked: true,320 url: logoUrl,321 status: null,322 contentType: null,323 contentLength: null,324 format: null,325 formatIssues: [],326 issues: [],327 };328
329 let fetchResult = null;330 try {331 fetchResult = await fetchLogo(logoUrl, timeoutSeconds, maxBytes);332 validation.status = fetchResult.status;333 validation.contentType = fetchResult.contentType;334 validation.contentLength = fetchResult.contentLength;335 } catch (error) {336 validation.issues.push(`logo fetch failed: ${error.message}`);337 return validation;338 }339
340 const buffer = fetchResult.buffer;341 const svgText = buffer.subarray(0, 256).toString('utf8');342 const isSvgText = /<svg[\s>]/i.test(svgText) || /^\s*(<\?xml[^>]*\?>\s*)?<svg[\s>]/i.test(svgText);343
344 if (fetchResult.contentType === 'image/svg+xml') {345 validation.format = 'svg';346 // BIMI SVG requirements (subset most flagged):347 // - Base profile: <svg> root, square viewBox required348 // - No scripts, no external references349 const text = buffer.toString('utf8');350 if (/\sonload\s*=|<script/i.test(text)) validation.formatIssues.push('SVG contains script code — BIMI SVG must not include scripts');351 if (/<image[\s>]|xlink:href|href\s*=\s*["']https?:/i.test(text)) {352 validation.formatIssues.push('SVG references external resources (image/href) — BIMI SVG must be self-contained');353 }354 const viewBoxMatch = text.match(/<svg[^>]*\sviewBox\s*=\s*["']([^"']+)["']/i);355 if (!viewBoxMatch) {356 validation.formatIssues.push('SVG missing viewBox attribute — BIMI requires a square viewBox');357 } else {358 const viewBox = viewBoxMatch[1].trim();359 const components = viewBox.split(/[\s,]+/).map(Number);360 if (components.length === 4 && components.every((n) => Number.isFinite(n))) {361 if (components[2] !== components[3]) {362 validation.formatIssues.push(`viewBox '${viewBox}' is not square (width ≠ height) — BIMI requires a square viewBox`);363 }364 } else {365 validation.formatIssues.push(`viewBox '${viewBox}' is malformed — expected four numbers`);366 }367 }368 } else if (isSvgText) {369 validation.format = 'svg';370 validation.formatIssues.push('SVG content detected but Content-Type is not image/svg+xml — receivers may reject it');371 const text = buffer.toString('utf8');372 if (/\sonload\s*=|<script/i.test(text)) validation.formatIssues.push('SVG contains script code — BIMI SVG must not include scripts');373 } else if (fetchResult.contentType && fetchResult.contentType.startsWith('image/')) {374 validation.format = 'raster';375 validation.formatIssues.push(`raster image format '${fetchResult.contentType}' is not SVG — BIMI requires SVG Tiny Portable/Secure Static profile per spec`);376 } else if (isSvgText === false && !fetchResult.contentType?.startsWith('image/')) {377 validation.format = 'unknown';378 validation.formatIssues.push(`unexpected logo content type '${fetchResult.contentType}' — BIMI requires an SVG image served over HTTPS`);379 }380
381 return validation;382}383
384/* ---------------------------------------------------------------------------385 * Scoring386 * ------------------------------------------------------------------------- */387
388export function scoreBimiAudit(result) {389 const issues = [];390 let score = 100;391 let recommendations = [];392
393 if (!result.bimiFound) {394 return {395 score: 0,396 grade: 'F',397 issues: ['no BIMI record found at selector._bimi.<domain>'],398 recommendations: [399 'Publish a BIMI record at selector._bimi.<domain> (e.g. default._bimi.example.com) with v=BIMI2, an a= VMC/CMC certificate URL, and an l= HTTPS SVG logo URL',400 'Ensure DMARC is at enforcement (p=quarantine or p=reject) first — BIMI is only honored after DMARC enforcement',401 ],402 };403 }404
405 if (result.dmarcEnforced === false) {406 issues.push('DMARC is not at enforcement — BIMI logos will not display');407 score -= 40;408 recommendations.push('Move DMARC to p=quarantine or p=reject before investing in BIMI; receivers ignore BIMI without DMARC enforcement');409 } else if (result.dmarcEnforced === null) {410 issues.push('DMARC policy could not be determined');411 score -= 20;412 recommendations.push('Publish a DMARC record at _dmarc.<domain> with p=quarantine or p=reject');413 }414
415 if (!result.hasRequiredLogoTag) {416 issues.push('record missing required l= logo URL tag');417 score -= 25;418 recommendations.push('Add an l= tag pointing to an HTTPS SVG logo URL');419 } else if (result.logo?.issues?.length > 0) {420 issues.push(...result.logo.issues.map((i) => `logo: ${i}`));421 score -= 10;422 recommendations.push('Fix the logo URL so it serves a valid BIMI SVG over HTTPS');423 }424
425 if (result.version === null) {426 issues.push('record missing v= version tag');427 score -= 10;428 recommendations.push('Add v=BIMI2 (or BIMI3) to future-proof the record');429 } else if (!KNOWN_VERSIONS.includes(result.version)) {430 issues.push(`unknown version '${result.version}'`);431 score -= 5;432 recommendations.push(`use v=BIMI2 or newer (${KNOWN_VERSIONS.join(', ')})`);433 } else if (result.version === 'bimi1') {434 issues.push('record uses legacy v=BIMI1 — upgrade');435 score -= 5;436 recommendations.push('Upgrade to v=BIMI2 and add an a= authority evidence URL');437 }438
439 if (result.authorityUrl === null) {440 issues.push('no a= authority evidence (VMC/CMC) URL — Gmail and Apple Mail require a Verified Mark Certificate');441 score -= 10;442 recommendations.push('Obtain a VMC/CMC from a Mark Verifier (Digicert, Entrust) and add the a= tag with its HTTPS URL');443 } else if (result.authority?.issues?.length > 0) {444 issues.push(...result.authority.issues.map((i) => `authority: ${i}`));445 score -= 5;446 recommendations.push('Fix the authority evidence URL so it is a valid HTTPS URL');447 }448
449 if (result.logo?.formatIssues?.length > 0) issues.push(...result.logo.formatIssues.map((i) => `logo format: ${i}`));450
451 if (result.recordIssues.length > 0) {452 issues.push(...result.recordIssues);453 score -= Math.min(15, result.recordIssues.length * 5);454 }455
456 score = Math.max(0, Math.min(100, score));457 const grade = score >= 90 ? 'A' : score >= 80 ? 'B' : score >= 70 ? 'C' : score >= 60 ? 'D' : 'F';458 recommendations = dedupe(recommendations);459 return { score, grade, issues, recommendations };460}461
462function dedupe(list) {463 return [...new Set(list)];464}465
466/* ---------------------------------------------------------------------------467 * Orchestration468 * ------------------------------------------------------------------------- */469
470export async function auditBimi(rawUrl, options = {}) {471 const timeoutSeconds = clampInteger(options.timeoutSeconds, DEFAULT_TIMEOUT_SECONDS, 3, 30);472 const dohUrl = options.dohUrl || DEFAULT_DOH_URL;473 const selector = (options.selector && String(options.selector).trim()) || DEFAULT_SELECTOR;474 if (!SELECTOR_RE.test(selector)) {475 throw new Error(`invalid selector '${selector}' (must be letters, digits, hyphens)`);476 }477 const checkLogo = options.checkLogo === undefined ? true : Boolean(options.checkLogo);478 const logoMaxBytes = clampInteger(options.logoMaxBytes, DEFAULT_LOGO_MAX_BYTES, 1024, 8 * 1024 * 1024);479
480 const url = await normalizeAndValidateUrl(rawUrl);481 const domain = url.hostname.toLowerCase();482 const bimiName = `${selector}._bimi.${domain}`;483
484 // 1. BIMI record TXT lookup.485 let bimiRecords = [];486 let dohError = null;487 try {488 bimiRecords = await dohTxt(bimiName, timeoutSeconds, dohUrl);489 } catch (error) {490 dohError = error.message;491 }492
493 // 2. DMARC prerequisite lookup.494 let dmarcTxt = [];495 let dmarcPolicy = null;496 try {497 dmarcTxt = await dohTxt(`_dmarc.${domain}`, timeoutSeconds, dohUrl);498 dmarcPolicy = parseDmarcPolicy(dmarcTxt);499 } catch {500 dmarcPolicy = null;501 }502 const dmarcEnforced = dmarcPolicy === null ? null : isDmarcEnforced(dmarcPolicy);503
504 const bimiFound = bimiRecords.length > 0;505 const primary = bimiFound ? parseBimiRecord(bimiRecords[0], selector) : null;506 const parsedRecords = bimiRecords.map((r) => parseBimiRecord(r, selector));507 const hasRequiredLogoTag = primary !== null && primary.logoUrl !== null;508 const recordIssues = bimiFound ? parsedRecords.flatMap((r) => r.tagIssues) : [];509
510 let logoAnalysis = null;511 let authorityAnalysis = null;512 if (bimiFound && hasRequiredLogoTag && primary.logoUrl && checkLogo) {513 try {514 const logoUrl = new URL(primary.logoUrl);515 if (logoUrl.protocol !== 'https:') throw new Error('logo URL must use HTTPS');516 logoAnalysis = await validateLogo(logoUrl, { timeoutSeconds, maxLogoBytes: logoMaxBytes });517 } catch (error) {518 logoAnalysis = { checked: true, url: primary.logoUrl, status: null, contentType: null, contentLength: null, format: null, formatIssues: [], issues: [`logo fetch failed: ${error.message}`] };519 }520 }521 if (bimiFound && primary?.authorityUrl) {522 try {523 const authorityUrl = new URL(primary.authorityUrl);524 if (authorityUrl.protocol !== 'https:') throw new Error('authority evidence URL must use HTTPS');525 authorityAnalysis = { url: primary.authorityUrl, valid: true, issues: [] };526 } catch (error) {527 authorityAnalysis = { url: primary.authorityUrl, valid: false, issues: [error.message] };528 }529 }530
531 const summary = {532 url: url.href,533 domain,534 selector,535 bimiName,536 bimiFound,537 recordCount: bimiRecords.length,538 recordText: bimiFound ? bimiRecords[0] : null,539 version: primary ? primary.version : null,540 logoUrl: primary ? primary.logoUrl : null,541 authorityUrl: primary ? primary.authorityUrl : null,542 hasRequiredLogoTag,543 dmarcPolicy,544 dmarcEnforced,545 logo: logoAnalysis,546 authority: authorityAnalysis,547 recordIssues,548 dohError,549 checkedAt: new Date().toISOString(),550 };551 const { score, grade, issues, recommendations } = scoreBimiAudit(summary);552 return { ...summary, score, grade, issues, recommendations };553}554
555const isExecutedDirectly = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];556
557if (process.env.NODE_ENV !== 'test' && isExecutedDirectly) {558 await Actor.init();559 try {560 const input = await Actor.getInput();561 if (!input || !input.startUrl) {562 throw new Error('startUrl is required');563 }564 const audit = await auditBimi(input.startUrl, {565 timeoutSeconds: input.timeoutSeconds,566 selector: input.selector,567 checkLogo: input.checkLogo,568 logoMaxBytes: input.logoMaxBytes,569 dohUrl: process.env.BIMI_DOH_URL,570 });571 await Actor.pushData([audit]);572 console.log(`BIMI audit complete: ${audit.domain} selector=${audit.selector} — score ${audit.score} (${audit.grade})`);573 } catch (error) {574 console.error(`BIMI audit failed: ${error.message}`);575 throw error;576 } finally {577 await Actor.exit();578 }579}1import { test } from 'node:test';2import assert from 'node:assert/strict';3import {4 parseBimiTagValue,5 parseBimiRecord,6 analyzeBimiRecord,7 parseDmarcPolicy,8 isDmarcEnforced,9 scoreBimiAudit,10 normalizeAndValidateUrl,11 auditBimi,12} from '../src/main.js';13
14process.env.NODE_ENV = 'test';15
16/* ---------------------------------------------------------------------------17 * BIMI tag parsing18 * ------------------------------------------------------------------------- */19
20test('parseBimiTagValue parses tag=value', () => {21 assert.deepEqual(parseBimiTagValue('v=BIMI2'), { tag: 'v', value: 'BIMI2' });22 assert.deepEqual(parseBimiTagValue('l=https://img.example.com/logo.svg'), {23 tag: 'l',24 value: 'https://img.example.com/logo.svg',25 });26});27
28test('parseBimiTagValue rejects garbage', () => {29 assert.equal(parseBimiTagValue('nonsense'), null);30 assert.equal(parseBimiTagValue(''), null);31 assert.equal(parseBimiTagValue(null), null);32});33
34test('parseBimiRecord extracts v/a/l tags', () => {35 const record = parseBimiRecord('v=BIMI2 a=https://vmc.example.com/cert.pem l=https://img.example.com/logo.svg', 'default');36 assert.equal(record.selector, 'default');37 assert.equal(record.version, 'bimi2');38 assert.equal(record.logoUrl, 'https://img.example.com/logo.svg');39 assert.equal(record.authorityUrl, 'https://vmc.example.com/cert.pem');40 assert.deepEqual(record.tagIssues, []);41});42
43test('parseBimiRecord handles semicolon-separated records (real-world format)', () => {44 const record = parseBimiRecord('v=BIMI1;l=https://www.dhl.com/dhl-email-logo/dhl-bimi.svg;a=https://www.dhl.com/dhl-email-logo/dhl-vmc.pem', 'default');45 assert.equal(record.version, 'bimi1');46 assert.equal(record.logoUrl, 'https://www.dhl.com/dhl-email-logo/dhl-bimi.svg');47 assert.equal(record.authorityUrl, 'https://www.dhl.com/dhl-email-logo/dhl-vmc.pem');48 assert.deepEqual(record.tagIssues, []);49});50
51test('parseBimiRecord flags duplicate tags', () => {52 const record = parseBimiRecord('v=BIMI2 v=BIMI3', 'default');53 assert.ok(record.tagIssues.some((i) => i.includes("duplicate tag 'v'")));54});55
56test('parseBimiRecord flags unparseable segments', () => {57 const record = parseBimiRecord('v=BIMI2 garbage', 'default');58 assert.ok(record.tagIssues.some((i) => i.includes('unparseable segment')));59});60
61test('parseBimiRecord handles empty record', () => {62 const record = parseBimiRecord('', 'default');63 assert.equal(record.parseError, 'record is empty');64 assert.equal(record.logoUrl, null);65});66
67/* ---------------------------------------------------------------------------68 * Record analysis69 * ------------------------------------------------------------------------- */70
71test('analyzeBimiRecord flags missing l= tag', () => {72 const rec = analyzeBimiRecord(parseBimiRecord('v=BIMI2', 'default'), true);73 assert.ok(rec.issues.some((i) => i.includes('missing required l=')));74});75
76test('analyzeBimiRecord flags http logo URL', () => {77 const rec = analyzeBimiRecord(parseBimiRecord('l=http://img.example.com/logo.svg', 'default'), true);78 assert.ok(rec.issues.some((i) => i.includes('must use HTTPS')));79});80
81test('analyzeBimiRecord flags BIMI1 without a=', () => {82 const rec = analyzeBimiRecord(parseBimiRecord('v=BIMI1 l=https://img.example.com/logo.svg', 'default'), true);83 assert.ok(rec.issues.some((i) => i.includes('BIMI1 records require an a= authority evidence location')));84});85
86test('analyzeBimiRecord flags unknown version', () => {87 const rec = analyzeBimiRecord(parseBimiRecord('v=BIMI9 l=https://img.example.com/logo.svg', 'default'), true);88 assert.ok(rec.issues.some((i) => i.includes("unknown version 'bimi9'")));89});90
91test('analyzeBimiRecord flags missing version', () => {92 const rec = analyzeBimiRecord(parseBimiRecord('l=https://img.example.com/logo.svg', 'default'), true);93 assert.ok(rec.issues.some((i) => i.includes('missing v=')));94});95
96test('analyzeBimiRecord flags DMARC not enforced', () => {97 const rec = analyzeBimiRecord(parseBimiRecord('v=BIMI2 l=https://img.example.com/logo.svg', 'default'), false);98 assert.ok(rec.issues.some((i) => i.includes('DMARC is not at enforcement')));99});100
101test('analyzeBimiRecord flags unknown tags', () => {102 const rec = analyzeBimiRecord(parseBimiRecord('v=BIMI2 l=https://img.example.com/logo.svg x=foo', 'default'), true);103 assert.ok(rec.issues.some((i) => i.includes("unknown BIMI tag 'x'")));104});105
106test('analyzeBimiRecord passes a clean record', () => {107 const rec = analyzeBimiRecord(108 parseBimiRecord('v=BIMI2 a=https://vmc.example.com/cert.pem l=https://img.example.com/logo.svg', 'default'),109 true,110 );111 assert.deepEqual(rec.issues, []);112});113
114test('analyzeBimiRecord flags authority URL with credentials', () => {115 const rec = analyzeBimiRecord(116 parseBimiRecord('v=BIMI2 a=https://user:pass@vmc.example.com/cert.pem l=https://img.example.com/logo.svg', 'default'),117 true,118 );119 assert.ok(rec.issues.some((i) => i.includes('authority evidence URL contains credentials')));120});121
122/* ---------------------------------------------------------------------------123 * DMARC parsing124 * ------------------------------------------------------------------------- */125
126test('parseDmarcPolicy extracts p= from DMARC1 record', () => {127 assert.equal(parseDmarcPolicy(['v=DMARC1; p=reject; rua=mailto:d@example.com']), 'reject');128 assert.equal(parseDmarcPolicy(['v=DMARC1; p=quarantine']), 'quarantine');129 assert.equal(parseDmarcPolicy(['v=DMARC1; p=none']), 'none');130});131
132test('parseDmarcPolicy handles no record', () => {133 assert.equal(parseDmarcPolicy([]), null);134 assert.equal(parseDmarcPolicy(['some other txt']), null);135 assert.equal(parseDmarcPolicy(['v=DMARC1; no policy here']), null);136});137
138test('isDmarcEnforced classifies policies', () => {139 assert.equal(isDmarcEnforced('quarantine'), true);140 assert.equal(isDmarcEnforced('reject'), true);141 assert.equal(isDmarcEnforced('none'), false);142 assert.equal(isDmarcEnforced(null), false);143});144
145/* ---------------------------------------------------------------------------146 * Scoring147 * ------------------------------------------------------------------------- */148
149test('scoreBimiAudit returns F with guidance when no record found', () => {150 const s = scoreBimiAudit({ bimiFound: false });151 assert.equal(s.score, 0);152 assert.equal(s.grade, 'F');153 assert.ok(s.recommendations.some((r) => r.includes('selector._bimi')));154});155
156test('scoreBimiAudit penalizes DMARC not enforced', () => {157 const s = scoreBimiAudit({ bimiFound: true, dmarcEnforced: false, version: 'bimi2', hasRequiredLogoTag: true, logo: null, authority: null, recordIssues: [], authorityUrl: 'https://vmc.example.com/cert.pem' });158 assert.ok(s.score < 100);159 assert.ok(s.issues.some((i) => i.includes('DMARC is not at enforcement')));160});161
162test('scoreBimiAudit penalizes missing l= tag', () => {163 const s = scoreBimiAudit({ bimiFound: true, dmarcEnforced: true, version: 'bimi2', hasRequiredLogoTag: false, logo: null, authority: null, recordIssues: [], authorityUrl: 'https://vmc.example.com/cert.pem' });164 assert.ok(s.issues.some((i) => i.includes('missing required l=')));165 assert.ok(s.score <= 75);166});167
168test('scoreBimiAudit penalizes BIMI1 without a=', () => {169 const s = scoreBimiAudit({ bimiFound: true, dmarcEnforced: true, version: 'bimi1', hasRequiredLogoTag: true, logo: null, authority: null, authorityUrl: null, recordIssues: [] });170 assert.ok(s.issues.some((i) => i.includes('legacy v=BIMI1')));171 assert.ok(s.issues.some((i) => i.includes('no a= authority evidence')));172});173
174test('scoreBimiAudit grades a clean record high', () => {175 const s = scoreBimiAudit({ bimiFound: true, dmarcEnforced: true, version: 'bimi2', hasRequiredLogoTag: true, logo: { issues: [] }, authority: { issues: [] }, authorityUrl: 'https://vmc.example.com/cert.pem', recordIssues: [] });176 assert.ok(s.score >= 95, `expected >= 95, got ${s.score}`);177 assert.equal(s.grade, 'A');178});179
180/* ---------------------------------------------------------------------------181 * SSRF protection182 * ------------------------------------------------------------------------- */183
184test('normalizeAndValidateUrl rejects private IPv4 literal', async () => {185 await assert.rejects(() => normalizeAndValidateUrl('http://192.168.1.1/logo.svg'), /Private IPv4/);186});187
188test('normalizeAndValidateUrl rejects private IPv6 literal', async () => {189 await assert.rejects(() => normalizeAndValidateUrl('http://[::1]/logo.svg'), /Private IPv6/);190});191
192test('normalizeAndValidateUrl rejects credentials', async () => {193 await assert.rejects(() => normalizeAndValidateUrl('https://user:pass@example.com/logo.svg'), /credentials/);194});195
196test('normalizeAndValidateUrl rejects non-HTTP schemes', async () => {197 await assert.rejects(() => normalizeAndValidateUrl('ftp://example.com/logo.svg'), /HTTP and HTTPS/);198});199
200test('normalizeAndValidateUrl accepts a public HTTPS URL', async () => {201 const url = await normalizeAndValidateUrl('https://example.com/logo.svg');202 assert.equal(url.hostname, 'example.com');203});204
205test('normalizeAndValidateUrl rejects metadata service IP', async () => {206 await assert.rejects(() => normalizeAndValidateUrl('https://169.254.169.254/logo.svg'), /Private IPv4/);207});208
209/* ---------------------------------------------------------------------------210 * Orchestration (mocked DoH)211 * ------------------------------------------------------------------------- */212
213// Mock doh behavior by pointing the DoH URL at a local http server we spin up.214// The DoH fetch itself is to cloudflare-dns.com (public); we test orchestration215// through a stub DoH URL served by an in-process http server on 127.0.0.1 —216// acceptable here because it is our own test fixture, not SSRF surface.217import http from 'node:http';218
219async function withMockDoh(handler, fn) {220 const server = http.createServer((req, res) => {221 const u = new URL(req.url, 'http://127.0.0.1');222 const name = u.searchParams.get('name') || '';223 res.setHeader('content-type', 'application/dns-json');224 res.end(JSON.stringify(handler(name)));225 });226 await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));227 const port = server.address().port;228 try {229 return await fn(`http://127.0.0.1:${port}/dns-query`);230 } finally {231 await new Promise((resolve) => server.close(resolve));232 }233}234
235test('auditBimi returns full diagnostics for a record with BIMI', async () => {236 await withMockDoh((name) => {237 if (name === 'default._bimi.example.com') {238 return { Status: 0, Answer: [{ type: 16, data: '"v=BIMI2 a=https://vmc.example.com/cert.pem l=https://img.example.com/logo.svg"' }] };239 }240 if (name === '_dmarc.example.com') {241 return { Status: 0, Answer: [{ type: 16, data: '"v=DMARC1; p=reject; rua=mailto:d@example.com"' }] };242 }243 return { Status: 0, Answer: [] };244 }, async (dohUrl) => {245 const result = await auditBimi('https://example.com', { dohUrl, checkLogo: false });246 assert.equal(result.bimiFound, true);247 assert.equal(result.version, 'bimi2');248 assert.equal(result.dmarcPolicy, 'reject');249 assert.equal(result.dmarcEnforced, true);250 assert.equal(result.hasRequiredLogoTag, true);251 assert.ok(result.score >= 80, `expected >= 80, got ${result.score}`);252 assert.ok(['A', 'B'].includes(result.grade));253 });254});255
256test('auditBimi reports missing record with DMARC guidance', async () => {257 await withMockDoh(() => ({ Status: 0, Answer: [] }), async (dohUrl) => {258 const result = await auditBimi('example.com', { dohUrl, checkLogo: false });259 assert.equal(result.bimiFound, false);260 assert.equal(result.score, 0);261 assert.equal(result.grade, 'F');262 assert.ok(result.recommendations.some((r) => r.includes('DMARC')));263 });264});265
266test('auditBimi flags DMARC-at-none as not enforced', async () => {267 await withMockDoh((name) => {268 if (name === 'default._bimi.example.com') {269 return { Status: 0, Answer: [{ type: 16, data: '"v=BIMI2 a=https://vmc.example.com/cert.pem l=https://img.example.com/logo.svg"' }] };270 }271 if (name === '_dmarc.example.com') {272 return { Status: 0, Answer: [{ type: 16, data: '"v=DMARC1; p=none"' }] };273 }274 return { Status: 0, Answer: [] };275 }, async (dohUrl) => {276 const result = await auditBimi('https://example.com', { dohUrl, checkLogo: false });277 assert.equal(result.dmarcPolicy, 'none');278 assert.equal(result.dmarcEnforced, false);279 assert.ok(result.issues.some((i) => i.includes('DMARC is not at enforcement')));280 });281});282
283test('auditBimi rejects invalid selector', async () => {284 await assert.rejects(() => auditBimi('https://example.com', { selector: 'bad selector!' }), /invalid selector/);285});286
287test('auditBimi rejects private IP input', async () => {288 await assert.rejects(() => auditBimi('https://192.168.0.1', { checkLogo: false }), /Private IPv4/);289});290
291/* Live smoke test — real public DoH. Skipped when offline. */292
293test('live smoke: audit a real domain via public DoH', { timeout: 20000 }, async () => {294 let result;295 try {296 result = await auditBimi('example.com', { checkLogo: false });297 } catch (error) {298 console.log(`live smoke skipped (${error.message})`);299 return;300 }301 // example.com has no BIMI record; we just assert the run completes and scores.302 assert.equal(result.domain, 'example.com');303 assert.ok(typeof result.score === 'number');304 assert.equal(result.bimiFound, false);305 assert.equal(result.score, 0);306 assert.equal(result.grade, 'F');307});