Carbon.txt Auditor
Pricing
Pay per usage
Discover and audit a public domain's carbon.txt sustainability disclosure file (Green Web Foundation spec v0.5). Checks discovery, TOML validity, disclosures, upstream services, score, and grade.
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:20
COPY package*.json ./RUN npm --quiet set progress=false \ && npm install --omit=dev --omit=optional
COPY . ./
CMD ["npm", "start"]{ "name": "carbon-txt-auditor", "version": "0.1.0", "description": "Apify Actor that discovers and audits a public domain's carbon.txt sustainability disclosure file against the Green Web Foundation carbon.txt v0.5 syntax and returns a 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", "smol-toml": "^1.3.1" }, "devDependencies": {}}1import { Actor } from 'apify';2import dns from 'node:dns/promises';3import net from 'node:net';4import { fileURLToPath } from 'node:url';5import { parse as parseToml } from 'smol-toml';6
7const USER_AGENT = 'CarbonTxtAuditor/0.1 (+https://apify.com)';8const DEFAULT_TIMEOUT_SECONDS = 10;9const MAX_BODY_BYTES = 256 * 1024; // carbon.txt files are small structured text10
11/* ---------------------------------------------------------------------------12 * SSRF protection — shared pattern used across URL-fetching factory actors.13 * Allows only HTTP/HTTPS, rejects URL credentials, rejects localhost/private14 * IP literals, DNS-resolves hostnames, and rejects DNS that resolves to15 * private IP ranges.16 * ------------------------------------------------------------------------- */17
18function isPrivateIPv4(ip) {19 const parts = ip.split('.').map(Number);20 if (parts.length !== 4 || parts.some((n) => Number.isNaN(n))) return false;21 const [a, b] = parts;22 return a === 1023 || (a === 172 && b >= 16 && b <= 31)24 || (a === 192 && b === 168)25 || a === 12726 || a === 027 || (a === 169 && b === 254);28}29
30function isPrivateIPv6(ip) {31 const normalized = ip.toLowerCase();32 return normalized === '::1'33 || normalized.startsWith('fc')34 || normalized.startsWith('fd')35 || normalized.startsWith('fe80:');36}37
38export async function normalizeAndValidateUrl(rawUrl) {39 if (!rawUrl || typeof rawUrl !== 'string') throw new Error('startUrl is required');40 if (/^[a-z][a-z0-9+.-]*:/i.test(rawUrl) && !/^https?:\/\//i.test(rawUrl)) {41 throw new Error('Only HTTP and HTTPS URLs are supported');42 }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 (!url.hostname || url.username || url.password) throw new Error('URL must be public and must not include credentials');48
49 const hostname = url.hostname.replace(/^\[|\]$/g, ''); // WHATWG hostname keeps IPv6 brackets50 const literalType = net.isIP(hostname);51 if (literalType === 4 && isPrivateIPv4(hostname)) throw new Error('Private IPv4 targets are blocked');52 if (literalType === 6 && isPrivateIPv6(hostname)) throw new Error('Private IPv6 targets are blocked');53
54 const records = literalType ? [{ address: hostname, family: literalType }] : await dns.lookup(url.hostname, { all: true });55 for (const record of records) {56 if (record.family === 4 && isPrivateIPv4(record.address)) throw new Error('DNS resolves to a private IPv4 address; blocked for SSRF safety');57 if (record.family === 6 && isPrivateIPv6(record.address)) throw new Error('DNS resolves to a private IPv6 address; blocked for SSRF safety');58 }59 return url;60}61
62/* ---------------------------------------------------------------------------63 * HTTP fetch of a text document with manual redirect revalidation (SSRF-safe)64 * and a bounded body read.65 * ------------------------------------------------------------------------- */66
67async function fetchText(initialUrl, timeoutSeconds, { method = 'GET', redirectsRemaining = 3 } = {}) {68 await normalizeAndValidateUrl(initialUrl.href);69 const controller = new AbortController();70 const timeout = setTimeout(() => controller.abort(), timeoutSeconds * 1000);71 try {72 const response = await fetch(initialUrl, {73 method,74 redirect: 'manual',75 signal: controller.signal,76 headers: {77 'user-agent': USER_AGENT,78 accept: 'text/plain, application/toml, */*;q=0.1',79 },80 });81
82 if ([301, 302, 303, 307, 308].includes(response.status)) {83 if (redirectsRemaining <= 0) throw new Error('Too many redirects');84 const location = response.headers.get('location');85 if (!location) throw new Error('Redirect without Location header');86 const nextUrl = new URL(location, initialUrl.href);87 await normalizeAndValidateUrl(nextUrl.href);88 return fetchText(nextUrl, timeoutSeconds, { method, redirectsRemaining: redirectsRemaining - 1 });89 }90
91 let text = '';92 if (method !== 'HEAD') {93 try {94 const buffer = await response.arrayBuffer();95 text = buffer.byteLength > MAX_BODY_BYTES96 ? new TextDecoder().decode(buffer.slice(0, MAX_BODY_BYTES))97 : new TextDecoder().decode(buffer);98 } catch {99 text = '';100 }101 }102
103 return {104 ok: response.ok,105 status: response.status,106 finalUrl: response.url || initialUrl.href,107 contentType: response.headers.get('content-type') || '',108 carbonTxtLocationHeader: response.headers.get('carbontxt-location') || null,109 https: (response.url || initialUrl.href).startsWith('https://'),110 body: text,111 error: null,112 };113 } catch (error) {114 return {115 ok: false,116 status: null,117 finalUrl: initialUrl.href,118 contentType: '',119 carbonTxtLocationHeader: null,120 https: initialUrl.protocol === 'https:',121 body: '',122 error: error.message,123 };124 } finally {125 clearTimeout(timeout);126 }127}128
129/* ---------------------------------------------------------------------------130 * Discovery (carbon.txt FAQ "How does the carbon.txt validator work?"):131 * 1. DNS TXT record on the domain in the form carbon-txt-location=URL.132 * 2. https://<domain>/carbon.txt (root).133 * 3. https://<domain>/.well-known/carbon.txt.134 * 4. CarbonTxt-Location HTTP response header on the domain root.135 * ------------------------------------------------------------------------- */136
137const DNS_TXT_PATTERN = /^carbon-txt-location=(.+)$/i;138
139export async function lookupDnsTxtLocation(hostname) {140 try {141 const records = await dns.resolveTxt(hostname);142 for (const chunks of records) {143 const joined = chunks.join('');144 const match = DNS_TXT_PATTERN.exec(joined.trim());145 if (match) return match[1].trim();146 }147 } catch {148 // No TXT records, or DNS resolution failed; not an error for discovery purposes.149 }150 return null;151}152
153export async function discoverCarbonTxt(baseUrl, timeoutSeconds) {154 const attempts = [];155
156 const dnsLocation = await lookupDnsTxtLocation(baseUrl.hostname);157 if (dnsLocation) {158 try {159 const target = await normalizeAndValidateUrl(dnsLocation);160 const result = await fetchText(target, timeoutSeconds);161 attempts.push({ method: 'dns-txt', url: target.href, result });162 if (result.ok && result.status === 200) return { method: 'dns-txt', url: target.href, result, attempts };163 } catch (error) {164 attempts.push({ method: 'dns-txt', url: dnsLocation, result: { ok: false, status: null, error: error.message, body: '', https: null, finalUrl: dnsLocation, contentType: '', carbonTxtLocationHeader: null } });165 }166 }167
168 const rootUrl = new URL('/carbon.txt', baseUrl.origin);169 const rootResult = await fetchText(rootUrl, timeoutSeconds);170 attempts.push({ method: 'root', url: rootUrl.href, result: rootResult });171 if (rootResult.ok && rootResult.status === 200) return { method: 'root', url: rootUrl.href, result: rootResult, attempts };172
173 const wellKnownUrl = new URL('/.well-known/carbon.txt', baseUrl.origin);174 const wellKnownResult = await fetchText(wellKnownUrl, timeoutSeconds);175 attempts.push({ method: 'well-known', url: wellKnownUrl.href, result: wellKnownResult });176 if (wellKnownResult.ok && wellKnownResult.status === 200) return { method: 'well-known', url: wellKnownUrl.href, result: wellKnownResult, attempts };177
178 const headerProbeUrl = new URL('/', baseUrl.origin);179 const headerProbeResult = await fetchText(headerProbeUrl, timeoutSeconds, { method: 'HEAD' });180 attempts.push({ method: 'header-probe', url: headerProbeUrl.href, result: headerProbeResult });181 if (headerProbeResult.carbonTxtLocationHeader) {182 try {183 const target = await normalizeAndValidateUrl(headerProbeResult.carbonTxtLocationHeader);184 const result = await fetchText(target, timeoutSeconds);185 attempts.push({ method: 'header', url: target.href, result });186 if (result.ok && result.status === 200) return { method: 'header', url: target.href, result, attempts };187 } catch (error) {188 attempts.push({ method: 'header', url: headerProbeResult.carbonTxtLocationHeader, result: { ok: false, status: null, error: error.message, body: '', https: null, finalUrl: headerProbeResult.carbonTxtLocationHeader, contentType: '', carbonTxtLocationHeader: null } });189 }190 }191
192 return { method: 'none', url: null, result: null, attempts };193}194
195/* ---------------------------------------------------------------------------196 * carbon.txt v0.5 TOML syntax validation (carbontxt.org/syntax).197 * ------------------------------------------------------------------------- */198
199const VALID_DOC_TYPES = ['web-page', 'annual-report', 'sustainability-page', 'certificate', 'csrd-report', 'ai-model-card', 'other'];200
201function isHttpUrlString(value) {202 if (typeof value !== 'string') return false;203 try {204 const u = new URL(value);205 return u.protocol === 'http:' || u.protocol === 'https:';206 } catch {207 return false;208 }209}210
211function validateDisclosure(entry, index) {212 const issues = [];213 if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {214 return { index, docType: null, url: null, validUntil: null, domain: null, title: null, issues: [`disclosures[${index}] must be a table`] };215 }216 const docType = typeof entry.doc_type === 'string' ? entry.doc_type : null;217 if (!docType) issues.push(`disclosures[${index}] is missing required field 'doc_type'`);218 else if (!VALID_DOC_TYPES.includes(docType)) issues.push(`disclosures[${index}].doc_type '${docType}' is not one of: ${VALID_DOC_TYPES.join(', ')}`);219
220 const url = typeof entry.url === 'string' ? entry.url : null;221 if (!url) issues.push(`disclosures[${index}] is missing required field 'url'`);222 else if (!isHttpUrlString(url)) issues.push(`disclosures[${index}].url '${url}' must be an absolute http(s) URL`);223
224 if ('domain' in entry && typeof entry.domain !== 'string') issues.push(`disclosures[${index}].domain must be a string`);225 if ('title' in entry && typeof entry.title !== 'string') issues.push(`disclosures[${index}].title must be a string`);226
227 return {228 index,229 docType,230 url,231 validUntil: entry.valid_until ? String(entry.valid_until) : null,232 domain: entry.domain || null,233 title: entry.title || null,234 issues,235 };236}237
238function validateUpstreamService(entry, index) {239 const issues = [];240 if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {241 return { index, domain: null, serviceType: null, issues: [`services[${index}] must be a table`] };242 }243 const domain = typeof entry.domain === 'string' ? entry.domain : null;244 if (!domain) issues.push(`services[${index}] is missing field 'domain'`);245 else if (/^https?:\/\//i.test(domain)) issues.push(`services[${index}].domain '${domain}' must not include a protocol`);246
247 const serviceType = entry.service_type !== undefined ? entry.service_type : null;248 if (serviceType !== null && typeof serviceType !== 'string' && !(Array.isArray(serviceType) && serviceType.every((s) => typeof s === 'string'))) {249 issues.push(`services[${index}].service_type must be a string or an array of strings`);250 }251
252 return { index, domain, serviceType, issues };253}254
255export function analyzeCarbonTxt(doc) {256 const issues = [];257
258 if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {259 issues.push('carbon.txt document is not a TOML table.');260 return {261 version: null, lastUpdated: null, hasOrgSection: false, disclosures: [], hasUpstreamSection: false, upstreamServices: [], issues,262 };263 }264
265 const version = typeof doc.version === 'string' ? doc.version : null;266 if (!version) issues.push("Missing recommended top-level key 'version' (required from carbon.txt syntax v0.3 onwards).");267
268 const lastUpdated = doc.last_updated !== undefined ? String(doc.last_updated) : null;269
270 const hasOrgSection = typeof doc.org === 'object' && doc.org !== null && !Array.isArray(doc.org);271 let disclosures = [];272 if (!hasOrgSection) {273 issues.push("Missing required '[org]' table.");274 } else if (!Array.isArray(doc.org.disclosures) || doc.org.disclosures.length === 0) {275 issues.push("'[org]' table is missing required non-empty 'disclosures' array.");276 } else {277 disclosures = doc.org.disclosures.map((entry, index) => validateDisclosure(entry, index));278 for (const d of disclosures) issues.push(...d.issues);279 }280
281 const hasUpstreamSection = typeof doc.upstream === 'object' && doc.upstream !== null && !Array.isArray(doc.upstream);282 let upstreamServices = [];283 if (hasUpstreamSection && Array.isArray(doc.upstream.services)) {284 upstreamServices = doc.upstream.services.map((entry, index) => validateUpstreamService(entry, index));285 for (const s of upstreamServices) issues.push(...s.issues);286 }287
288 return { version, lastUpdated, hasOrgSection, disclosures, hasUpstreamSection, upstreamServices, issues };289}290
291/* ---------------------------------------------------------------------------292 * Optional disclosure URL reachability checks (HEAD, falling back to a293 * capped GET). Only runs against the exact URLs declared in the carbon.txt294 * file; never fetches anything else. SSRF-validated like all other fetches.295 * ------------------------------------------------------------------------- */296
297async function checkDisclosureUrl(urlString, timeoutSeconds) {298 try {299 const url = await normalizeAndValidateUrl(urlString);300 let result = await fetchText(url, timeoutSeconds, { method: 'HEAD' });301 if (result.status === 405 || result.status === null) {302 result = await fetchText(url, timeoutSeconds, { method: 'GET' });303 }304 return { url: urlString, reachable: result.ok, status: result.status, https: result.https, error: result.error };305 } catch (error) {306 return { url: urlString, reachable: false, status: null, https: null, error: error.message };307 }308}309
310/* ---------------------------------------------------------------------------311 * Per-check evaluations, scoring, and recommendations.312 * ------------------------------------------------------------------------- */313
314function evalDiscovery({ discovery }) {315 if (discovery.method === 'none') {316 return { status: 'missing', note: 'No carbon.txt file was discoverable via DNS TXT record, /carbon.txt, /.well-known/carbon.txt, or a CarbonTxt-Location header.', recommendation: 'Publish a carbon.txt file at the root of your domain (https://example.com/carbon.txt) or advertise its location via DNS TXT record or CarbonTxt-Location header.' };317 }318 return { status: 'good', note: `carbon.txt discovered via ${discovery.method} at ${discovery.url}.` };319}320
321function evalHttps({ discovery }) {322 if (discovery.method === 'none') return { status: 'info', note: 'No response to evaluate.' };323 if (!discovery.result.https) {324 return { status: 'missing', note: 'carbon.txt was not served over https.', recommendation: 'Serve carbon.txt over https.' };325 }326 return { status: 'good', note: 'carbon.txt served over https.' };327}328
329function evalToml({ tomlValid, parseError }) {330 if (!tomlValid) {331 return { status: 'missing', note: `carbon.txt body is not valid TOML${parseError ? `: ${parseError}` : '.'}`, recommendation: 'Fix the TOML syntax errors in the carbon.txt file (see carbontxt.org/syntax).' };332 }333 return { status: 'good', note: 'carbon.txt body parses as valid TOML.' };334}335
336function evalVersion({ analysis }) {337 if (!analysis.version) {338 return { status: 'warn', note: "No 'version' field declared.", recommendation: "Declare version = \"0.5\" at the top level (required from syntax v0.3 onwards)." };339 }340 return { status: 'good', note: `Declared syntax version '${analysis.version}'.` };341}342
343function evalOrgSection({ analysis }) {344 if (!analysis.hasOrgSection) {345 return { status: 'missing', note: "Missing required '[org]' table.", recommendation: "Add an '[org]' table with a non-empty 'disclosures' array." };346 }347 return { status: 'good', note: "'[org]' table is present." };348}349
350function evalDisclosures({ analysis }) {351 if (!analysis.hasOrgSection) return { status: 'info', note: 'Skipped: no [org] table.' };352 if (analysis.disclosures.length === 0) {353 return { status: 'missing', note: "'[org]' table has no valid 'disclosures' entries.", recommendation: 'Add at least one org.disclosures entry with doc_type and url pointing to a publicly accessible sustainability disclosure document.' };354 }355 const bad = analysis.disclosures.filter((d) => d.issues.length > 0);356 if (bad.length) {357 return { status: 'warn', note: `${bad.length} of ${analysis.disclosures.length} disclosure entries have validation issues.`, recommendation: 'Fix invalid doc_type values and missing/malformed url fields in org.disclosures.' };358 }359 return { status: 'good', note: `${analysis.disclosures.length} valid disclosure entr${analysis.disclosures.length === 1 ? 'y' : 'ies'} found.` };360}361
362function evalUpstream({ analysis }) {363 if (!analysis.hasUpstreamSection) {364 return { status: 'info', note: "No '[upstream]' table (optional; only relevant for services that depend on upstream hosting/CDN providers)." };365 }366 const bad = analysis.upstreamServices.filter((s) => s.issues.length > 0);367 if (bad.length) {368 return { status: 'warn', note: `${bad.length} of ${analysis.upstreamServices.length} upstream.services entries have validation issues.`, recommendation: 'Fix upstream.services entries to use bare domains (no protocol) and valid service_type values.' };369 }370 if (analysis.upstreamServices.length === 0) {371 return { status: 'warn', note: "'[upstream]' table is present but has no 'services' entries.", recommendation: "Add upstream.services entries for hosting, CDN, or other infrastructure providers, or remove the empty '[upstream]' table." };372 }373 return { status: 'good', note: `${analysis.upstreamServices.length} upstream service(s) documented.` };374}375
376function evalDisclosureReachability({ disclosureUrlChecks }) {377 if (disclosureUrlChecks === null) return { status: 'info', note: 'Disclosure URL reachability checks were not requested.' };378 if (disclosureUrlChecks.length === 0) return { status: 'info', note: 'No disclosure URLs to check.' };379 const unreachable = disclosureUrlChecks.filter((c) => !c.reachable);380 if (unreachable.length) {381 return { status: 'warn', note: `${unreachable.length} of ${disclosureUrlChecks.length} disclosure URL(s) did not resolve successfully.`, recommendation: 'Fix or remove disclosure URLs that return errors or non-2xx/3xx status codes.' };382 }383 return { status: 'good', note: `All ${disclosureUrlChecks.length} disclosure URL(s) resolved successfully.` };384}385
386const CHECKS = [387 { name: 'discovery', title: 'carbon.txt discovery', weight: 25, fn: evalDiscovery },388 { name: 'https', title: 'Served over HTTPS', weight: 10, fn: evalHttps },389 { name: 'toml', title: 'TOML validity', weight: 15, fn: evalToml },390 { name: 'version', title: 'Syntax version declared', weight: 5, fn: evalVersion },391 { name: 'org', title: "'[org]' table present", weight: 10, fn: evalOrgSection },392 { name: 'disclosures', title: 'Disclosures valid', weight: 25, fn: evalDisclosures },393 { name: 'upstream', title: 'Upstream services', weight: 5, fn: evalUpstream },394 { name: 'reachability', title: 'Disclosure URL reachability', weight: 5, fn: evalDisclosureReachability },395];396
397export function buildCheckReports(context) {398 const reports = [];399 let earned = 0;400 let possible = 0;401 for (const check of CHECKS) {402 const evaluation = check.fn(context);403 if (evaluation.status !== 'info') possible += check.weight;404 if (evaluation.status === 'good') earned += check.weight;405 else if (evaluation.status === 'warn') earned += Math.round(check.weight * 0.5);406 reports.push({407 name: check.title,408 check: check.name,409 status: evaluation.status,410 note: evaluation.note,411 weight: check.weight,412 recommendation: evaluation.recommendation || null,413 });414 }415 return { reports, earned, possible };416}417
418export function scoreAudit(earned, possible) {419 if (possible === 0) return 0;420 return Math.min(100, Math.max(0, Math.round((earned / possible) * 100)));421}422
423export function gradeFromScore(score) {424 if (score >= 95) return 'A+';425 if (score >= 85) return 'A';426 if (score >= 75) return 'B';427 if (score >= 65) return 'C';428 if (score >= 50) return 'D';429 if (score >= 30) return 'E';430 return 'F';431}432
433export function buildRecommendations(reports) {434 const recs = [];435 for (const r of reports) {436 if (r.recommendation && !recs.includes(r.recommendation)) recs.push(r.recommendation);437 }438 if (recs.length === 0) {439 recs.push('carbon.txt looks spec-conformant. Re-run this audit after updating sustainability disclosures to catch regressions.');440 }441 return recs;442}443
444/* ---------------------------------------------------------------------------445 * Main audit pipeline.446 * ------------------------------------------------------------------------- */447
448export async function auditCarbonTxt(input) {449 const domainRaw = input.startUrl || input.domain;450 const timeoutSeconds = Math.min(Math.max(Number(input.timeoutSeconds || DEFAULT_TIMEOUT_SECONDS), 3), 30);451 const checkDisclosureUrls = Boolean(input.checkDisclosureUrls);452
453 const baseUrl = await normalizeAndValidateUrl(domainRaw);454 const discovery = await discoverCarbonTxt(baseUrl, timeoutSeconds);455
456 let doc = null;457 let tomlValid = false;458 let parseError = null;459 if (discovery.result?.body) {460 try {461 doc = parseToml(discovery.result.body);462 tomlValid = true;463 } catch (err) {464 parseError = err.message;465 }466 }467
468 const analysis = doc469 ? analyzeCarbonTxt(doc)470 : { version: null, lastUpdated: null, hasOrgSection: false, disclosures: [], hasUpstreamSection: false, upstreamServices: [], issues: [] };471
472 let disclosureUrlChecks = null;473 if (checkDisclosureUrls && analysis.disclosures.length > 0) {474 disclosureUrlChecks = [];475 for (const d of analysis.disclosures) {476 if (d.url) disclosureUrlChecks.push(await checkDisclosureUrl(d.url, timeoutSeconds));477 }478 }479
480 const context = { discovery, tomlValid, parseError, analysis, disclosureUrlChecks };481 const { reports, earned, possible } = buildCheckReports(context);482 const score = scoreAudit(earned, possible);483 const grade = gradeFromScore(score);484 const recommendations = buildRecommendations(reports);485
486 const issues = [487 ...analysis.issues,488 ...reports.filter((r) => r.status === 'warn' || r.status === 'missing').map((r) => `${r.name}: ${r.note}`),489 ];490
491 return {492 inputDomain: domainRaw,493 discoveryMethod: discovery.method,494 carbonTxtUrl: discovery.url,495 https: discovery.result?.https ?? null,496 status: discovery.result?.status ?? null,497 fileFound: discovery.method !== 'none',498 tomlValid,499 parseError,500 version: analysis.version,501 lastUpdated: analysis.lastUpdated,502 hasOrgSection: analysis.hasOrgSection,503 disclosureCount: analysis.disclosures.length,504 disclosures: analysis.disclosures,505 hasUpstreamSection: analysis.hasUpstreamSection,506 upstreamServiceCount: analysis.upstreamServices.length,507 upstreamServices: analysis.upstreamServices,508 disclosureUrlChecks,509 checks: reports,510 issues: [...new Set(issues)],511 score,512 grade,513 checkedAt: new Date().toISOString(),514 recommendations,515 error: discovery.result?.error ?? null,516 };517}518
519/* ---------------------------------------------------------------------------520 * Apify runtime entry point.521 * ------------------------------------------------------------------------- */522
523const isExecutedDirectly = process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1];524
525if (process.env.NODE_ENV !== 'test' && isExecutedDirectly) {526 await Actor.init();527 try {528 const input = await Actor.getInput();529 const result = await auditCarbonTxt(input || {});530 await Actor.pushData(result);531 await Actor.setValue('OUTPUT', result);532 Actor.log.info('Carbon.txt audit complete', { carbonTxtUrl: result.carbonTxtUrl, score: result.score, grade: result.grade });533 } finally {534 await Actor.exit();535 }536}1import test from 'node:test';2import assert from 'node:assert/strict';3import { parse as parseToml } from 'smol-toml';4import {5 analyzeCarbonTxt,6 buildCheckReports,7 buildRecommendations,8 gradeFromScore,9 normalizeAndValidateUrl,10 scoreAudit,11} from '../src/main.js';12
13/* ---------------------------------------------------------------------------14 * SSRF / URL validation security tests15 * ------------------------------------------------------------------------- */16
17test('normalizeAndValidateUrl blocks private IPv4 literal', async () => {18 await assert.rejects(() => normalizeAndValidateUrl('http://127.0.0.1/'), /Private IPv4/);19});20
21test('normalizeAndValidateUrl blocks 169.254 link-local', async () => {22 await assert.rejects(() => normalizeAndValidateUrl('http://169.254.169.254/'), /Private IPv4/);23});24
25test('normalizeAndValidateUrl blocks 10.x private range', async () => {26 await assert.rejects(() => normalizeAndValidateUrl('http://10.1.2.3/'), /Private IPv4/);27});28
29test('normalizeAndValidateUrl blocks private IPv6 literal', async () => {30 await assert.rejects(() => normalizeAndValidateUrl('http://[fd12::1]/'), /Private IPv6/);31});32
33test('normalizeAndValidateUrl rejects URL credentials', async () => {34 await assert.rejects(() => normalizeAndValidateUrl('https://user:pass@example.com'), /credentials/);35});36
37test('normalizeAndValidateUrl rejects non-HTTP schemes', async () => {38 await assert.rejects(() => normalizeAndValidateUrl('file:///etc/hosts'), /HTTP and HTTPS/);39});40
41test('normalizeAndValidateUrl rejects ftp scheme', async () => {42 await assert.rejects(() => normalizeAndValidateUrl('ftp://example.com/file'), /HTTP and HTTPS/);43});44
45test('normalizeAndValidateUrl accepts public hostname and defaults to https', async () => {46 const url = await normalizeAndValidateUrl('example.com');47 assert.equal(url.hostname, 'example.com');48 assert.equal(url.protocol, 'https:');49});50
51/* ---------------------------------------------------------------------------52 * carbon.txt TOML analysis (carbontxt.org/syntax v0.5)53 * ------------------------------------------------------------------------- */54
55const GOOD_TOML = `56version = "0.5"57last_updated = 2026-10-0558
59[org]60disclosures = [61 { doc_type = "web-page", url = "https://mycompany.com/sustainability", domain = "mycompany.com" },62 { doc_type = "annual-report", url = "https://mycompany.com/carbon-emissions-2025.pdf", valid_until = 2025-12-31, title = "Emissions Report 2025" },63]64
65[upstream]66services = [67 { domain = "cloud.google.com", service_type = "shared-hosting" },68 { domain = "aws.amazon.com", service_type = "cdn" },69]70`;71
72test('analyzeCarbonTxt accepts a fully valid v0.5 document', () => {73 const doc = parseToml(GOOD_TOML);74 const analysis = analyzeCarbonTxt(doc);75 assert.equal(analysis.version, '0.5');76 assert.equal(analysis.hasOrgSection, true);77 assert.equal(analysis.disclosures.length, 2);78 assert.equal(analysis.disclosures[0].issues.length, 0);79 assert.equal(analysis.disclosures[1].issues.length, 0);80 assert.equal(analysis.hasUpstreamSection, true);81 assert.equal(analysis.upstreamServices.length, 2);82 assert.equal(analysis.upstreamServices[0].issues.length, 0);83 assert.equal(analysis.issues.length, 0);84});85
86test('analyzeCarbonTxt flags missing [org] table', () => {87 const doc = parseToml('version = "0.5"\n');88 const analysis = analyzeCarbonTxt(doc);89 assert.equal(analysis.hasOrgSection, false);90 assert.ok(analysis.issues.some((i) => i.includes("'[org]' table")));91});92
93test('analyzeCarbonTxt flags empty disclosures array', () => {94 const doc = parseToml('version = "0.5"\n[org]\ndisclosures = []\n');95 const analysis = analyzeCarbonTxt(doc);96 assert.equal(analysis.hasOrgSection, true);97 assert.equal(analysis.disclosures.length, 0);98 assert.ok(analysis.issues.some((i) => i.includes('non-empty')));99});100
101test('analyzeCarbonTxt flags disclosure missing url', () => {102 const doc = parseToml('[org]\ndisclosures = [{ doc_type = "web-page" }]\n');103 const analysis = analyzeCarbonTxt(doc);104 assert.equal(analysis.disclosures[0].issues.length, 1);105 assert.match(analysis.disclosures[0].issues[0], /missing required field 'url'/);106});107
108test('analyzeCarbonTxt flags disclosure with invalid doc_type', () => {109 const doc = parseToml('[org]\ndisclosures = [{ doc_type = "blog-post", url = "https://example.com/x" }]\n');110 const analysis = analyzeCarbonTxt(doc);111 assert.equal(analysis.disclosures[0].issues.length, 1);112 assert.match(analysis.disclosures[0].issues[0], /not one of/);113});114
115test('analyzeCarbonTxt flags disclosure with non-http url', () => {116 const doc = parseToml('[org]\ndisclosures = [{ doc_type = "web-page", url = "ftp://example.com/x" }]\n');117 const analysis = analyzeCarbonTxt(doc);118 assert.equal(analysis.disclosures[0].issues.length, 1);119 assert.match(analysis.disclosures[0].issues[0], /absolute http/);120});121
122test('analyzeCarbonTxt flags upstream service domain with protocol', () => {123 const doc = parseToml('[org]\ndisclosures = [{ doc_type = "web-page", url = "https://example.com/x" }]\n[upstream]\nservices = [{ domain = "https://cloud.google.com" }]\n');124 const analysis = analyzeCarbonTxt(doc);125 assert.equal(analysis.upstreamServices[0].issues.length, 1);126 assert.match(analysis.upstreamServices[0].issues[0], /must not include a protocol/);127});128
129test('analyzeCarbonTxt handles non-table document', () => {130 const analysis = analyzeCarbonTxt('not-a-table');131 assert.equal(analysis.hasOrgSection, false);132 assert.ok(analysis.issues.length > 0);133});134
135/* ---------------------------------------------------------------------------136 * Scoring and grading137 * ------------------------------------------------------------------------- */138
139test('scoreAudit computes percentage of possible points', () => {140 assert.equal(scoreAudit(80, 100), 80);141 assert.equal(scoreAudit(0, 100), 0);142 assert.equal(scoreAudit(0, 0), 0);143});144
145test('gradeFromScore maps score bands to letter grades', () => {146 assert.equal(gradeFromScore(100), 'A+');147 assert.equal(gradeFromScore(90), 'A');148 assert.equal(gradeFromScore(80), 'B');149 assert.equal(gradeFromScore(70), 'C');150 assert.equal(gradeFromScore(55), 'D');151 assert.equal(gradeFromScore(35), 'E');152 assert.equal(gradeFromScore(10), 'F');153});154
155/* ---------------------------------------------------------------------------156 * Check-report pipeline (discovery + toml + analysis combined)157 * ------------------------------------------------------------------------- */158
159test('buildCheckReports scores a fully discovered, valid document highly', () => {160 const doc = parseToml(GOOD_TOML);161 const analysis = analyzeCarbonTxt(doc);162 const discovery = { method: 'root', url: 'https://example.com/carbon.txt', result: { https: true } };163 const { reports, earned, possible } = buildCheckReports({ discovery, tomlValid: true, parseError: null, analysis, disclosureUrlChecks: null });164 const score = scoreAudit(earned, possible);165 assert.ok(score >= 90, `expected high score, got ${score}`);166 assert.ok(reports.every((r) => r.status !== 'missing'));167});168
169test('buildCheckReports scores an undiscoverable domain very low', () => {170 const discovery = { method: 'none', url: null, result: null };171 const analysis = { version: null, lastUpdated: null, hasOrgSection: false, disclosures: [], hasUpstreamSection: false, upstreamServices: [], issues: [] };172 const { reports, earned, possible } = buildCheckReports({ discovery, tomlValid: false, parseError: null, analysis, disclosureUrlChecks: null });173 const score = scoreAudit(earned, possible);174 assert.ok(score <= 10, `expected very low score, got ${score}`);175 assert.equal(reports.find((r) => r.check === 'discovery').status, 'missing');176 assert.equal(reports.find((r) => r.check === 'toml').status, 'missing');177 assert.equal(reports.find((r) => r.check === 'org').status, 'missing');178});179
180test('buildRecommendations deduplicates and provides a fallback', () => {181 const doc = parseToml(GOOD_TOML);182 const analysis = analyzeCarbonTxt(doc);183 const discovery = { method: 'root', url: 'https://example.com/carbon.txt', result: { https: true } };184 const { reports } = buildCheckReports({ discovery, tomlValid: true, parseError: null, analysis, disclosureUrlChecks: null });185 const recs = buildRecommendations(reports);186 assert.ok(Array.isArray(recs));187 assert.ok(recs.length >= 1);188});{ "actorSpecification": 1, "name": "carbon-txt-auditor", "title": "Carbon.txt Auditor", "description": "Discover and audit a public domain's carbon.txt sustainability disclosure file (Green Web Foundation spec v0.5). Validates discovery, TOML syntax, org.disclosures entries, and upstream services. Returns a readiness score, grade, 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": { "inputDomain": { "type": "string", "description": "The domain or URL provided as input" }, "discoveryMethod": { "type": "string", "description": "How the carbon.txt file was located: dns-txt, root, well-known, header, or none" }, "carbonTxtUrl": { "type": "string", "description": "The URL the carbon.txt file was fetched from, if found" }, "https": { "type": "boolean", "description": "Whether the carbon.txt file was served over HTTPS" }, "status": { "type": "integer", "description": "Final HTTP status code of the carbon.txt fetch" }, "fileFound": { "type": "boolean", "description": "Whether a carbon.txt file was found at any discovery location" }, "tomlValid": { "type": "boolean", "description": "Whether the file body parses as valid TOML" }, "parseError": { "type": "string", "description": "TOML parse error message, if any" }, "version": { "type": "string", "description": "Declared carbon.txt syntax version" }, "lastUpdated": { "type": "string", "description": "Declared last_updated date" }, "hasOrgSection": { "type": "boolean", "description": "Whether an [org] table is present" }, "disclosureCount": { "type": "integer", "description": "Number of org.disclosures entries found" }, "disclosures": { "type": "array", "description": "Parsed disclosure entries (docType, url, validUntil, domain, title, and validation issues)" }, "hasUpstreamSection": { "type": "boolean", "description": "Whether an [upstream] table is present" }, "upstreamServiceCount": { "type": "integer", "description": "Number of upstream.services entries found" }, "upstreamServices": { "type": "array", "description": "Parsed upstream service entries (domain, serviceType, validation issues)" }, "disclosureUrlChecks": { "type": "array", "description": "Reachability checks for each disclosure URL, if checkDisclosureUrls was enabled" }, "checks": { "type": "array", "description": "Per-check analysis objects (name, status, note, weight, recommendation)" }, "issues": { "type": "array", "description": "Aggregated issue descriptions" }, "score": { "type": "integer", "description": "Carbon.txt readiness score (0-100)" }, "grade": { "type": "string", "description": "Letter grade (A+, A, B, C, D, E, F)" }, "checkedAt": { "type": "string", "format": "date-time", "description": "ISO timestamp" }, "recommendations": { "type": "array", "description": "Actionable recommendations for carbon.txt configuration" }, "error": { "type": "string", "description": "Top-level fetch error message, if any" } } }, "views": { "overview": { "title": "Overview", "transformation": { "fields": ["carbonTxtUrl", "discoveryMethod", "https", "status", "fileFound", "tomlValid", "hasOrgSection", "disclosureCount", "grade", "score", "issues", "recommendations", "checkedAt"] }, "display": { "component": "table", "properties": { "carbonTxtUrl": { "label": "carbon.txt URL", "format": "link" }, "discoveryMethod": { "label": "Discovery method", "format": "text" }, "https": { "label": "HTTPS", "format": "boolean" }, "status": { "label": "Status", "format": "number" }, "fileFound": { "label": "File found", "format": "boolean" }, "tomlValid": { "label": "Valid TOML", "format": "boolean" }, "hasOrgSection": { "label": "Has org section", "format": "boolean" }, "disclosureCount": { "label": "Disclosures", "format": "number" }, "grade": { "label": "Grade", "format": "text" }, "score": { "label": "Score", "format": "number" }, "issues": { "label": "Issues", "format": "array" }, "recommendations": { "label": "Recommendations", "format": "array" }, "checkedAt": { "label": "Checked", "format": "date" } } } } }}{ "title": "Carbon.txt Auditor", "type": "object", "schemaVersion": 1, "description": "Discover and audit a public domain's carbon.txt sustainability disclosure file against the Green Web Foundation carbon.txt v0.5 syntax. Checks DNS TXT discovery, root and well-known file locations, the CarbonTxt-Location HTTP header, TOML validity, required org.disclosures entries, upstream services, and disclosure URL reachability. Returns a readiness score, grade, and recommendations.", "properties": { "startUrl": { "title": "Domain or URL", "type": "string", "description": "Public domain or URL to audit (e.g. example.com or https://example.com). The actor checks a DNS TXT discovery record, https://<domain>/carbon.txt, https://<domain>/.well-known/carbon.txt, and a CarbonTxt-Location response header, in that order. HTTP and HTTPS only. Private IP ranges and URL credentials are blocked.", "editor": "textfield", "prefill": "https://example.com" }, "checkDisclosureUrls": { "title": "Check disclosure URL reachability", "type": "boolean", "description": "If enabled, the actor performs a HEAD (falling back to a capped GET) request against each org.disclosures[].url found in the carbon.txt file to confirm it resolves publicly. Disabled by default to keep runs fast and side-effect free.", "default": false, "editor": "checkbox" }, "timeoutSeconds": { "title": "Request timeout (seconds)", "type": "integer", "description": "Timeout for each HTTP request.", "minimum": 3, "maximum": 30, "default": 10, "unit": "seconds", "editor": "number" } }, "required": ["startUrl"]}{ "actorOutputSchemaVersion": 1, "title": "Output schema of Carbon.txt Auditor", "description": "Audit results are stored in the default dataset.", "properties": { "results": { "type": "string", "title": "Audit results", "template": "{{links.apiDefaultDatasetUrl}}/items" } }}