|
| 1 | +/** |
| 2 | + * Accessibility Statement Checker |
| 3 | + * |
| 4 | + * Detects whether federal websites publish a digital accessibility statement |
| 5 | + * as required by OMB Memorandum M-24-08 "Strengthening Digital Accessibility |
| 6 | + * and the Management of Section 508 of the Rehabilitation Act" (December 2023). |
| 7 | + * |
| 8 | + * M-24-08 requires each federal agency to publish an accessibility statement |
| 9 | + * that includes: |
| 10 | + * - Contact information for reporting accessibility problems |
| 11 | + * - Known accessibility limitations and alternatives |
| 12 | + * - Process for requesting accessible formats or alternatives |
| 13 | + * - A reference to the agency formal complaints process |
| 14 | + * - A date of last review |
| 15 | + * - A link to the agency Section 508 program page |
| 16 | + * |
| 17 | + * Detection works by probing common accessibility statement URL paths on each |
| 18 | + * unique domain in the scan results using lightweight HTTP HEAD requests. |
| 19 | + * |
| 20 | + * Paths checked (in order): |
| 21 | + * /accessibility |
| 22 | + * /accessibility-statement |
| 23 | + * /accessibility.html |
| 24 | + * /accessibility-statement.html |
| 25 | + * /about/accessibility |
| 26 | + * /section-508 |
| 27 | + * /508 |
| 28 | + */ |
| 29 | + |
| 30 | +import https from 'node:https'; |
| 31 | +import http from 'node:http'; |
| 32 | + |
| 33 | +/** |
| 34 | + * Common URL paths where federal accessibility statements are published. |
| 35 | + * Ordered by prevalence based on observed federal website patterns. |
| 36 | + */ |
| 37 | +export const ACCESSIBILITY_STATEMENT_PATHS = [ |
| 38 | + '/accessibility', |
| 39 | + '/accessibility-statement', |
| 40 | + '/accessibility.html', |
| 41 | + '/accessibility-statement.html', |
| 42 | + '/about/accessibility', |
| 43 | + '/section-508', |
| 44 | + '/508' |
| 45 | +]; |
| 46 | + |
| 47 | +/** |
| 48 | + * Make a HEAD request to a URL and return true if the server responds with |
| 49 | + * a 2xx or 3xx status (the page exists or redirects to something that does). |
| 50 | + * |
| 51 | + * @param {string} urlString |
| 52 | + * @param {number} [timeoutMs=5000] |
| 53 | + * @returns {Promise<boolean>} |
| 54 | + */ |
| 55 | +function headRequest(urlString, timeoutMs = 5000) { |
| 56 | + return new Promise((resolve) => { |
| 57 | + try { |
| 58 | + const parsed = new URL(urlString); |
| 59 | + const client = parsed.protocol === 'https:' ? https : http; |
| 60 | + const options = { |
| 61 | + method: 'HEAD', |
| 62 | + hostname: parsed.hostname, |
| 63 | + port: parsed.port ? Number(parsed.port) : undefined, |
| 64 | + path: parsed.pathname + parsed.search, |
| 65 | + headers: { |
| 66 | + 'User-Agent': 'daily-dap-accessibility-statement-checker/1.0' |
| 67 | + } |
| 68 | + }; |
| 69 | + const req = client.request(options, (res) => { |
| 70 | + const code = res.statusCode ?? 0; |
| 71 | + // Accept 2xx (success) and 3xx (redirect – the path exists even if moved) |
| 72 | + resolve(code >= 200 && code < 400); |
| 73 | + }); |
| 74 | + req.setTimeout(timeoutMs, () => { |
| 75 | + req.destroy(); |
| 76 | + resolve(false); |
| 77 | + }); |
| 78 | + req.on('error', () => resolve(false)); |
| 79 | + req.end(); |
| 80 | + } catch { |
| 81 | + resolve(false); |
| 82 | + } |
| 83 | + }); |
| 84 | +} |
| 85 | + |
| 86 | +/** |
| 87 | + * Check whether the website at baseUrl publishes an accessibility statement. |
| 88 | + * |
| 89 | + * Probes each path in ACCESSIBILITY_STATEMENT_PATHS in order and returns the |
| 90 | + * first URL that responds successfully. If none do, returns |
| 91 | + * `{ has_statement: false, statement_url: null }`. |
| 92 | + * |
| 93 | + * In test / mock mode pass `options.runImpl` to replace the live HEAD request |
| 94 | + * logic with a custom function: |
| 95 | + * `runImpl(baseUrl)` should return `{ has_statement, statement_url }`. |
| 96 | + * |
| 97 | + * @param {string} baseUrl - Scheme + host of the site (e.g. "https://example.gov") |
| 98 | + * @param {{ runImpl?: (baseUrl: string) => Promise<{has_statement: boolean, statement_url: string|null}> }} [options] |
| 99 | + * @returns {Promise<{ has_statement: boolean, statement_url: string|null }>} |
| 100 | + */ |
| 101 | +export async function checkAccessibilityStatement(baseUrl, options = {}) { |
| 102 | + const { runImpl } = options; |
| 103 | + if (typeof runImpl === 'function') { |
| 104 | + return runImpl(baseUrl); |
| 105 | + } |
| 106 | + |
| 107 | + const parsed = new URL(baseUrl); |
| 108 | + const base = `${parsed.protocol}//${parsed.host}`; |
| 109 | + |
| 110 | + for (const urlPath of ACCESSIBILITY_STATEMENT_PATHS) { |
| 111 | + const candidateUrl = `${base}${urlPath}`; |
| 112 | + // eslint-disable-next-line no-await-in-loop |
| 113 | + const exists = await headRequest(candidateUrl); |
| 114 | + if (exists) { |
| 115 | + return { has_statement: true, statement_url: candidateUrl }; |
| 116 | + } |
| 117 | + } |
| 118 | + |
| 119 | + return { has_statement: false, statement_url: null }; |
| 120 | +} |
| 121 | + |
| 122 | +/** |
| 123 | + * Check accessibility statements for all unique domains found in the URL results. |
| 124 | + * |
| 125 | + * Only domains from successfully-scanned URLs are checked. Each unique |
| 126 | + * hostname is checked exactly once regardless of how many scanned pages |
| 127 | + * belong to that domain. |
| 128 | + * |
| 129 | + * @param {Array<{ url?: string, scan_status: string }>} urlResults |
| 130 | + * @param {{ runImpl?: Function }} [options] |
| 131 | + * @returns {Promise<Record<string, { has_statement: boolean, statement_url: string|null }>>} |
| 132 | + */ |
| 133 | +export async function checkAccessibilityStatements(urlResults, options = {}) { |
| 134 | + // Collect unique hostname → baseUrl pairs from successfully-scanned URLs |
| 135 | + const domainMap = new Map(); |
| 136 | + for (const result of urlResults ?? []) { |
| 137 | + if (result?.scan_status !== 'success' || !result?.url) { |
| 138 | + continue; |
| 139 | + } |
| 140 | + try { |
| 141 | + const parsed = new URL(result.url); |
| 142 | + if (!domainMap.has(parsed.host)) { |
| 143 | + domainMap.set(parsed.host, `${parsed.protocol}//${parsed.host}`); |
| 144 | + } |
| 145 | + } catch { |
| 146 | + // Skip malformed URLs |
| 147 | + } |
| 148 | + } |
| 149 | + |
| 150 | + const statements = {}; |
| 151 | + for (const [hostname, baseUrl] of domainMap) { |
| 152 | + // eslint-disable-next-line no-await-in-loop |
| 153 | + statements[hostname] = await checkAccessibilityStatement(baseUrl, options); |
| 154 | + } |
| 155 | + |
| 156 | + return statements; |
| 157 | +} |
| 158 | + |
| 159 | +/** |
| 160 | + * Build a summary object from accessibility statement check results. |
| 161 | + * |
| 162 | + * @param {Record<string, { has_statement: boolean, statement_url: string|null }>} statements |
| 163 | + * @returns {{ |
| 164 | + * domains_checked: number, |
| 165 | + * domains_with_statement: number, |
| 166 | + * statement_rate_percent: number, |
| 167 | + * domains_without_statement: string[], |
| 168 | + * statement_urls: string[] |
| 169 | + * }} |
| 170 | + */ |
| 171 | +export function buildAccessibilityStatementSummary(statements) { |
| 172 | + const entries = Object.entries(statements ?? {}); |
| 173 | + const withStatement = entries.filter(([, v]) => v.has_statement); |
| 174 | + const withoutStatement = entries |
| 175 | + .filter(([, v]) => !v.has_statement) |
| 176 | + .map(([hostname]) => hostname) |
| 177 | + .sort(); |
| 178 | + const statementUrls = withStatement |
| 179 | + .map(([, v]) => v.statement_url) |
| 180 | + .filter(Boolean) |
| 181 | + .sort(); |
| 182 | + const domainsChecked = entries.length; |
| 183 | + const domainsWithStatement = withStatement.length; |
| 184 | + |
| 185 | + return { |
| 186 | + domains_checked: domainsChecked, |
| 187 | + domains_with_statement: domainsWithStatement, |
| 188 | + statement_rate_percent: |
| 189 | + domainsChecked > 0 ? Math.round((domainsWithStatement / domainsChecked) * 100) : 0, |
| 190 | + domains_without_statement: withoutStatement, |
| 191 | + statement_urls: statementUrls |
| 192 | + }; |
| 193 | +} |
0 commit comments