Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix(brands): decode HTML references in icon URLs

To3akaRin9db5e31cdec1
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.zip
index ede3ba35..b712767f 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/references/brand-marks.md b/archify/references/brand-marks.md
index 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, blocks
credentials, nonstandard public ports, and private or link-local destinations,
uses bounded concurrency and one total deadline, and returns the captured
diff --git a/archify/renderers/shared/brand-marks.mjs b/archify/renderers/shared/brand-marks.mjs
index 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.mjs
new file mode 100644
index 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&amp;b=2', '/mark.png?a=1&b=2'],
+ ['uppercase ampersand', '/mark.png?a=1&AMP;b=2', '/mark.png?a=1&b=2'],
+ ['decimal ampersand', '/mark.png?a=1&#38;b=2', '/mark.png?a=1&b=2'],
+ ['hexadecimal ampersand', '/mark.png?a=1&#x26;b=2', '/mark.png?a=1&b=2'],
+ ['basic named references', '/mark.png?q=&quot;&apos;&lt;&gt;', '/mark.png?q="\'<>'],
+ ['percent escapes', '/mark.png?q=%26amp%3B%2F&amp;v=%2526', '/mark.png?q=%26amp%3B%2F&v=%2526'],
+ ['one decoding pass', '/mark.png?a=1&amp;amp;b=2', '/mark.png?a=1&amp;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&amp=2&ampx=3&AMP=4', '/mark.png?a=1&amp=2&ampx=3&AMP=4'],
+ ['Unicode numeric references', '/mark.png?q=&#x1F680;&#128512;', '/mark.png?q=🚀😀'],
+ ['invalid numeric code points', '/mark.png?q=&#0;&#xD800;&#1114112;', '/mark.png?q=���'],
+ ['unterminated numeric reference', '/mark.png?a=1&#38b=2', '/mark.png?a=1&b=2'],
+ ['legacy numeric C1 mapping', '/mark.png?q=&#128;', '/mark.png?q=€'],
+ ['attribute named-reference boundaries', '/mark.png?q=&amp!&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&amp;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, 'jav&#97;script:alert(1)');
+ const result = await run(['brands', 'capture', data.url, '--json']);
+ assert.notEqual(result.status, 0);
+ assert.deepEqual(data.requests, ['/studio', '/favicon.ico']);
+});