Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(brands): decode HTML references in icon URLs
To3akaRin9db5e31cdec1
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 1b841d01..87ab77f6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo> Development identity: `v2.17.0-dev.1`. Not a stable release.### Fixed+- **Escaped brand icon URLs (#454).** Favicon discovery decodes basic named and numeric HTML character references once before URL resolution, preserving percent escapes and the existing network and digest checks.- **Architecture Delta baseline arrowheads (#433).** Removed and rerouted baseline relationships retain their marker definitions in the composed Delta SVG, preserving their authored direction alongside current relationships.- **Compare rollback recovery (#438).** If restoring a previous output fails, compare preserves its recovery directory and reports backup-to-target paths instead of deleting the remaining backups during cleanup.- **固定提交的来源校验 (#420)。** 校验忽略本地 Git replacement refs,始终读取指定提交的原始对象,避免替换后的文件或行范围造成误接受或误拒绝;保留原有来源链接、诊断与用户 Git 配置。diff --git a/archify.zip b/archify.zipindex ede3ba35..b712767f 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/references/brand-marks.md b/archify/references/brand-marks.mdindex 55411787..dcfad1ea 100644--- a/archify/references/brand-marks.md+++ b/archify/references/brand-marks.md@@ -48,6 +48,12 @@ does; `brand` explains whose product it is.URL or silently assign a visually similar company.Known-brand URLs resolve to the bundled vector instead of using the network.+For discovered icon `href` attributes, capture decodes the basic named references+`amp`, `quot`, `apos`, `lt`, `gt` (and their defined uppercase aliases), plus+decimal and hexadecimal numeric references, once before URL resolution. Thus+`/icon.png?v=1&size=32` requests `/icon.png?v=1&size=32`. URL percent escapes+remain intact; nested escapes are not decoded recursively. This bounded decoder+does not add a general HTML parser or support every named HTML entity.Unknown URL capture accepts only bounded raster image formats, blockscredentials, nonstandard public ports, and private or link-local destinations,uses bounded concurrency and one total deadline, and returns the captureddiff --git a/archify/renderers/shared/brand-marks.mjs b/archify/renderers/shared/brand-marks.mjsindex 1e18e0b5..44451027 100644--- a/archify/renderers/shared/brand-marks.mjs+++ b/archify/renderers/shared/brand-marks.mjs@@ -274,13 +274,36 @@ function attribute(tag, name) {return match ? (match[1] ?? match[2] ?? match[3] ?? '') : '';}+// HTML numeric references in the C1 range use the legacy Windows-1252 mapping.+// https://html.spec.whatwg.org/multipage/parsing.html#numeric-character-reference-end-state+const HTML_C1_REFERENCES = [+ 0x20ac, 0x81, 0x201a, 0x192, 0x201e, 0x2026, 0x2020, 0x2021,+ 0x2c6, 0x2030, 0x160, 0x2039, 0x152, 0x8d, 0x17d, 0x8f,+ 0x90, 0x2018, 0x2019, 0x201c, 0x201d, 0x2022, 0x2013, 0x2014,+ 0x2dc, 0x2122, 0x161, 0x203a, 0x153, 0x9d, 0x17e, 0x178,+];+const BASIC_HTML_REFERENCES = { amp: '&', quot: '"', apos: "'", lt: '<', gt: '>' };++function decodeIconHref(value) {+ // Decode only after extracting the attribute, in one pass. Leave percent+ // escapes to URL parsing and do not reinterpret decoded quotes as markup.+ return value.replace(/&#(?:[xX]([0-9a-fA-F]+)|([0-9]+));?|&(amp|AMP|quot|QUOT|lt|LT|gt|GT)(?:;|(?![A-Za-z0-9=]))|&(apos);/g,+ (_match, hex, decimal, named, apostrophe) => {+ if (named || apostrophe) return BASIC_HTML_REFERENCES[(named || apostrophe).toLowerCase()];+ let point = Number.parseInt(hex || decimal, hex ? 16 : 10);+ if (point === 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) return '\uFFFD';+ if (point >= 0x80 && point <= 0x9f) point = HTML_C1_REFERENCES[point - 0x80];+ return String.fromCodePoint(point);+ });+}+function iconCandidates(html, pageUrl) {const candidates = [];for (const match of html.matchAll(/<link\b[^>]*>/gi)) {const tag = match[0];const rel = attribute(tag, 'rel').toLocaleLowerCase('en-US').split(/\s+/);if (!rel.some((value) => value === 'icon' || value === 'apple-touch-icon' || value === 'mask-icon')) continue;- const href = attribute(tag, 'href');+ const href = decodeIconHref(attribute(tag, 'href'));if (!href) continue;try {const url = new URL(href, pageUrl);diff --git a/archify/test/brand-href-entities.test.mjs b/archify/test/brand-href-entities.test.mjsnew file mode 100644index 00000000..40487b1a--- /dev/null+++ b/archify/test/brand-href-entities.test.mjs@@ -0,0 +1,125 @@+import assert from 'node:assert/strict';+import { spawn } from 'node:child_process';+import { createHash } from 'node:crypto';+import fs from 'node:fs';+import http from 'node:http';+import os from 'node:os';+import path from 'node:path';+import test from 'node:test';+import { fileURLToPath } from 'node:url';++const skillRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');+const cli = path.join(skillRoot, 'bin/archify.mjs');+const icon = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64');+const digest = createHash('sha256').update(icon).digest('hex');+const cases = [+ ['named ampersand', '/mark.png?a=1&b=2', '/mark.png?a=1&b=2'],+ ['uppercase ampersand', '/mark.png?a=1&b=2', '/mark.png?a=1&b=2'],+ ['decimal ampersand', '/mark.png?a=1&b=2', '/mark.png?a=1&b=2'],+ ['hexadecimal ampersand', '/mark.png?a=1&b=2', '/mark.png?a=1&b=2'],+ ['basic named references', '/mark.png?q="'<>', '/mark.png?q="\'<>'],+ ['percent escapes', '/mark.png?q=%26amp%3B%2F&v=%2526', '/mark.png?q=%26amp%3B%2F&v=%2526'],+ ['one decoding pass', '/mark.png?a=1&amp;b=2', '/mark.png?a=1&b=2'],+ ['literal query ampersands', '/mark.png?a=1&b=2&token=plain', '/mark.png?a=1&b=2&token=plain'],+ ['ambiguous unterminated names', '/mark.png?a=1&=2&x=3&=4', '/mark.png?a=1&=2&x=3&=4'],+ ['Unicode numeric references', '/mark.png?q=🚀😀', '/mark.png?q=🚀😀'],+ ['invalid numeric code points', '/mark.png?q=���', '/mark.png?q=���'],+ ['unterminated numeric reference', '/mark.png?a=1&b=2', '/mark.png?a=1&b=2'],+ ['legacy numeric C1 mapping', '/mark.png?q=€', '/mark.png?q=€'],+ ['attribute named-reference boundaries', '/mark.png?q=&!&apos!&bogus;&AmP;', '/mark.png?q=&!&apos!&bogus;&AmP;'],+];++function run(args) {+ return new Promise((resolve, reject) => {+ const child = spawn(process.execPath, [cli, ...args], {+ cwd: skillRoot,+ env: { ...process.env, ARCHIFY_BRAND_ALLOW_PRIVATE: '1' },+ stdio: ['ignore', 'pipe', 'pipe'],+ timeout: 15000,+ });+ let stdout = '';+ let stderr = '';+ child.stdout.setEncoding('utf8').on('data', (chunk) => { stdout += chunk; });+ child.stderr.setEncoding('utf8').on('data', (chunk) => { stderr += chunk; });+ child.once('error', reject);+ child.once('close', (status) => resolve({ status, stdout, stderr }));+ });+}++async function fixture(t, href, decoded) {+ const requests = [];+ let expected;+ const server = http.createServer((request, response) => {+ requests.push(request.url);+ if (request.url === '/studio') {+ response.writeHead(200, { 'content-type': 'text/html; charset=utf-8' });+ response.end(`<html><title>Entity fixture</title><link rel="icon" href="${href}"></html>`);+ } else if (expected && request.url === expected.pathname + expected.search) {+ response.writeHead(200, { 'content-type': 'image/png' });+ response.end(icon);+ } else {+ // A wrong query and the fallback must never accidentally yield the right digest.+ response.writeHead(404);+ response.end('no icon at this URL');+ }+ });+ await new Promise((resolve, reject) => {+ server.once('error', reject);+ server.listen(0, '127.0.0.1', resolve);+ });+ t.after(() => new Promise((resolve) => {+ server.closeAllConnections?.();+ server.close(resolve);+ }));+ const url = `http://127.0.0.1:${server.address().port}/studio`;+ if (decoded) expected = new URL(decoded, url);+ return { url, requests, expected };+}++async function capture(data) {+ const result = await run(['brands', 'capture', data.url, '--json']);+ assert.deepEqual(data.requests, ['/studio', data.expected.pathname + data.expected.search], 'request the decoded href exactly once');+ assert.equal(result.status, 0, result.stderr || result.stdout);+ const receipt = JSON.parse(result.stdout);+ assert.equal(receipt.ok, true);+ assert.deepEqual(receipt.brand, { url: data.url, sha256: digest });+ assert.equal(receipt.evidence.status, 'captured');+ assert.equal(receipt.evidence.sha256, digest);+ return receipt.brand;+}++for (const [name, href, decoded] of cases) {+ test(`brands capture resolves ${name} in icon href`, { timeout: 20000 }, async (t) => {+ await capture(await fixture(t, href, decoded));+ });+}++test('captured entity URL is fetched identically for pinned validation and rendering', { timeout: 45000 }, async (t) => {+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-brand-href-'));+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));+ const data = await fixture(t, '/mark.png?v=1&size=32', '/mark.png?v=1&size=32');+ const brand = await capture(data);+ const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/web-app.architecture.json'), 'utf8'));+ diagram.components[0].brand = brand;+ const input = path.join(root, 'diagram.json');+ const output = path.join(root, 'diagram.html');+ fs.writeFileSync(input, JSON.stringify(diagram));+ for (const command of ['validate', 'render']) {+ data.requests.length = 0;+ const args = [command, 'architecture', input, ...(command === 'render' ? [output] : ['--json'])];+ const result = await run(args);+ assert.equal(result.status, 0, result.stderr || result.stdout);+ assert.deepEqual(data.requests, ['/studio', data.expected.pathname + data.expected.search]);+ }+ const html = fs.readFileSync(output, 'utf8');+ assert.match(html, /data-brand-status="captured"/);+ assert.ok(html.includes(`data-brand-sha256="${digest}"`));+ assert.ok(html.includes(`data:image/png;base64,${icon.toString('base64')}`));+});++test('entity-decoded non-HTTP icon URLs are not fetched', { timeout: 20000 }, async (t) => {+ const data = await fixture(t, 'javascript:alert(1)');+ const result = await run(['brands', 'capture', data.url, '--json']);+ assert.notEqual(result.status, 0);+ assert.deepEqual(data.requests, ['/studio', '/favicon.ico']);+});