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): validate ICO image data ranges

To3akaRindea6354d909e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6f16a6e6..50f3f932 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -20,6 +20,7 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
- **Japanese entry point under the same maintenance contract.** `README_JA.md` joins the language switcher and every README parity check: brand mark and demo-section placement, the animated proof and demo deep links, share-card and real-repository proofs, the update-awareness disclosure, the Hermes Agent and DSH installation rows, the self-hosted Star History ending, and release-identity validation of the version badge, the Japanese development marker, and the Raven manual-ZIP boundary. The switcher check is now driven by one per-language table, so a future language is added in one place.
### Fixed
+- **Brand ICO data bounds (#585).** Capture and pinned re-fetches reject empty, directory-overlapping or out-of-bounds image ranges in ICO directory entries, while preserving valid PNG/DIB payloads and normal icon fallback.
- **Lifecycle transition notes (#549).** Notes render when the transition label is omitted or empty, with matching route-space reservations and collision checks; existing label-only and label-plus-note layouts retain their behavior.
- **Brand content-encoding negotiation (#514).** Capture and pinned re-fetches request identity encoding and reject unexpected encoded response bodies before parsing or hashing, with the coding error preserved if favicon fallback also fails.
- **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.
diff --git a/archify.zip b/archify.zip
index 4b30b835..c0b669f4 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 ae054cd4..09d8efe3 100644
--- a/archify/references/brand-marks.md
+++ b/archify/references/brand-marks.md
@@ -65,6 +65,13 @@ content digest. Later render and validate operations require that exact digest;
blocked, unavailable, changed, oversized, or unsafe content fails closed instead
of silently changing the artifact.
+For ICO captures, every directory entry must reference a non-empty image range
+after the complete directory and within the downloaded file. This bounds check
+also applies when reproducing a pinned capture. PNG/DIB payloads, multiple
+images, shared or out-of-order ranges, and trailing bytes remain supported;
+the check does not decode pixels or guarantee that an otherwise bounded payload
+is decodable. A rejected ICO candidate does not prevent trying later icons.
+
Page, icon and redirect requests send `Accept-Encoding: identity`. Capture does
not decompress response bodies: a successful response declaring another content
coding is closed and rejected explicitly. This keeps the existing byte limits
diff --git a/archify/renderers/shared/brand-marks.mjs b/archify/renderers/shared/brand-marks.mjs
index 5eb520e3..42b710c2 100644
--- a/archify/renderers/shared/brand-marks.mjs
+++ b/archify/renderers/shared/brand-marks.mjs
@@ -411,6 +411,20 @@ function iconCandidates(html, pageUrl) {
return [...unique.values()].slice(0, 5).concat({ url: fallback, score: -1 });
}
+function validIcoImageRanges(buffer) {
+ if (buffer.length < 6 || buffer.readUInt16LE(0) !== 0 || buffer.readUInt16LE(2) !== 1) return false;
+ const count = buffer.readUInt16LE(4);
+ const directoryEnd = 6 + count * 16;
+ if (count === 0 || directoryEnd > buffer.length) return false;
+ for (let index = 0; index < count; index += 1) {
+ const entry = 6 + index * 16;
+ const size = buffer.readUInt32LE(entry + 8);
+ const offset = buffer.readUInt32LE(entry + 12);
+ if (size === 0 || offset < directoryEnd || offset + size > buffer.length) return false;
+ }
+ return true;
+}
+
async function imageData(response) {
const contentType = (response.headers.get('content-type') || '').split(';')[0].trim().toLocaleLowerCase('en-US');
const allowed = new Set([
@@ -442,10 +456,7 @@ async function imageData(response) {
&& buffer.toString('ascii', 0, 4) === 'RIFF'
&& buffer.toString('ascii', 8, 12) === 'WEBP'
&& buffer.readUInt32LE(4) + 8 <= buffer.length
- : buffer.length >= 22
- && buffer[0] === 0 && buffer[1] === 0 && buffer[2] === 1 && buffer[3] === 0
- && buffer.readUInt16LE(4) > 0
- && 6 + buffer.readUInt16LE(4) * 16 <= buffer.length));
+ : validIcoImageRanges(buffer)));
if (!signatureMatches) throw new Error(`brand asset bytes do not match ${contentType}`);
return {
dataUrl: `data:${contentType};base64,${buffer.toString('base64')}`,
diff --git a/archify/test/brand-ico-bounds.test.mjs b/archify/test/brand-ico-bounds.test.mjs
new file mode 100644
index 00000000..cbef3499
--- /dev/null
+++ b/archify/test/brand-ico-bounds.test.mjs
@@ -0,0 +1,180 @@
+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 sha256 = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const png = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64');
+// BITMAPINFOHEADER, one opaque red BGRA pixel, and a DWORD-aligned AND mask.
+const dib = Buffer.alloc(48);
+dib.writeUInt32LE(40, 0);
+dib.writeInt32LE(1, 4);
+dib.writeInt32LE(2, 8); // ICO DIB height includes the XOR and AND planes.
+dib.writeUInt16LE(1, 12);
+dib.writeUInt16LE(32, 14);
+dib.writeUInt32LE(8, 20);
+dib[42] = 255;
+dib[43] = 255;
+
+function ico(payloads, order = payloads.map((_, index) => index)) {
+ const directory = Buffer.alloc(6 + 16 * order.length);
+ directory.writeUInt16LE(1, 2);
+ directory.writeUInt16LE(order.length, 4);
+ const offsets = payloads.map((_, index) => directory.length
+ + payloads.slice(0, index).reduce((sum, value) => sum + value.length, 0));
+ order.forEach((payload, index) => {
+ const entry = 6 + index * 16;
+ directory[entry] = 1;
+ directory[entry + 1] = 1;
+ directory.writeUInt16LE(1, entry + 4);
+ directory.writeUInt16LE(32, entry + 6);
+ directory.writeUInt32LE(payloads[payload].length, entry + 8);
+ directory.writeUInt32LE(offsets[payload], entry + 12);
+ });
+ return Buffer.concat([directory, ...payloads]);
+}
+function entry(value, { index = 0, size, offset }) {
+ const bytes = Buffer.from(value);
+ if (size !== undefined) bytes.writeUInt32LE(size, 6 + index * 16 + 8);
+ if (offset !== undefined) bytes.writeUInt32LE(offset, 6 + index * 16 + 12);
+ return bytes;
+}
+const valid = ico([png]);
+const invalid = [
+ ['zero image length', entry(valid, { size: 0 })],
+ ['offset inside header', entry(valid, { offset: 0 })],
+ ['offset inside directory', entry(valid, { offset: 21 })],
+ ['image ends one byte beyond EOF', entry(valid, { size: png.length + 1 })],
+ ['missing image bytes', valid.subarray(0, 22)],
+ ['maximum uint32 offset', entry(valid, { offset: 0xffffffff })],
+ ['maximum uint32 size', entry(valid, { size: 0xffffffff })],
+ ['truncated directory', ico([png, dib]).subarray(0, 37)],
+ ['later image entry out of bounds', entry(ico([png, dib]), { index: 1, size: dib.length + 1 })],
+];
+
+function run(args) {
+ return new Promise((resolve, reject) => {
+ const child = spawn(process.execPath, [cli, ...args], {
+ cwd: skillRoot, stdio: ['ignore', 'pipe', 'pipe'], timeout: 15000,
+ env: { ...process.env, ARCHIFY_BRAND_ALLOW_PRIVATE: '1' },
+ });
+ let stdout = '', 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, routes) {
+ const requests = [];
+ const server = http.createServer((request, response) => {
+ requests.push(request.url);
+ const resource = routes[request.url];
+ response.writeHead(resource ? 200 : 404, { 'content-type': resource?.type || 'text/plain' });
+ response.end(resource?.bytes || 'missing');
+ });
+ 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); }));
+ return { origin: `http://127.0.0.1:${server.address().port}`, requests };
+}
+const resource = (bytes, type = 'image/x-icon') => ({ bytes, type });
+async function successfulCapture(url, bytes) {
+ const result = await run(['brands', 'capture', url, '--json']);
+ 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, sha256: sha256(bytes) });
+ assert.equal(receipt.evidence.sha256, sha256(bytes));
+ return receipt.brand;
+}
+
+for (const [name, bytes] of invalid) {
+ test(`ICO capture rejects ${name}`, { timeout: 20000 }, async (t) => {
+ const data = await fixture(t, { '/icon.ico': resource(bytes) });
+ const result = await run(['brands', 'capture', `${data.origin}/icon.ico`, '--json']);
+ assert.notEqual(result.status, 0, 'must not pin a directory with an invalid image range');
+ assert.match(result.stderr, /brand asset bytes do not match image\/x-icon/);
+ assert.deepEqual(data.requests, ['/icon.ico']);
+ });
+}
+
+for (const type of ['image/x-icon', 'image/vnd.microsoft.icon']) {
+ for (const [format, bytes] of [['PNG', valid], ['DIB', ico([dib])]]) {
+ test(`ICO capture retains ${format} bytes served as ${type}`, { timeout: 20000 }, async (t) => {
+ const data = await fixture(t, { '/icon.ico': resource(bytes, type) });
+ await successfulCapture(`${data.origin}/icon.ico`, bytes);
+ });
+ }
+}
+for (const [name, bytes] of [
+ ['multiple images out of directory order', ico([png, dib], [1, 0])],
+ ['multiple entries sharing image data', ico([png], [0, 0])],
+ ['trailing byte after image data', Buffer.concat([valid, Buffer.from([0])])],
+]) {
+ test(`ICO capture accepts ${name}`, { timeout: 20000 }, async (t) => {
+ const data = await fixture(t, { '/icon.ico': resource(bytes) });
+ await successfulCapture(`${data.origin}/icon.ico`, bytes);
+ });
+}
+
+for (const laterValid of [true, false]) {
+ test(`HTML icon discovery ${laterValid ? 'continues to a valid candidate' : 'rejects all malformed candidates'}`, { timeout: 20000 }, async (t) => {
+ const page = '<head><link rel="icon" href="/bad.ico"><link rel="icon" href="/next.ico"></head>';
+ const data = await fixture(t, {
+ '/page': resource(page, 'text/html'), '/bad.ico': resource(invalid[0][1]),
+ '/next.ico': resource(laterValid ? valid : invalid[4][1]),
+ '/favicon.ico': resource(invalid[1][1]),
+ });
+ if (laterValid) await successfulCapture(`${data.origin}/page`, valid);
+ else {
+ const result = await run(['brands', 'capture', `${data.origin}/page`, '--json']);
+ assert.notEqual(result.status, 0);
+ assert.match(result.stderr, /brand asset bytes do not match/);
+ }
+ assert.deepEqual(data.requests, laterValid ? ['/page', '/bad.ico', '/next.ico']
+ : ['/page', '/bad.ico', '/next.ico', '/favicon.ico']);
+ });
+}
+
+for (const healthy of [false, true]) {
+ test(`digest-pinned validation and rendering ${healthy ? 'preserve valid ICO bytes' : 'reject malformed ICO even with a matching digest'}`, { timeout: 45000 }, async (t) => {
+ const bytes = healthy ? valid : invalid[4][1];
+ const data = await fixture(t, { '/icon.ico': resource(bytes) });
+ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-ico-pin-'));
+ t.after(() => fs.rmSync(root, { recursive: true, force: true }));
+ const input = path.join(root, 'input.json'), output = path.join(root, 'output.html');
+ const document = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/web-app.architecture.json'), 'utf8'));
+ // Author the known digest directly: rejection must validate bytes, not rely on prior capture.
+ document.components[0].brand = { url: `${data.origin}/icon.ico`, sha256: sha256(bytes) };
+ fs.writeFileSync(input, JSON.stringify(document));
+ const previous = Buffer.from('previous trusted artifact');
+ fs.writeFileSync(output, previous);
+ for (const command of ['validate', 'render']) {
+ data.requests.length = 0;
+ const result = await run([command, 'architecture', input, ...(command === 'render' ? [output] : ['--json'])]);
+ assert.deepEqual(data.requests, ['/icon.ico']);
+ if (healthy) assert.equal(result.status, 0, result.stderr || result.stdout);
+ else {
+ assert.notEqual(result.status, 0);
+ assert.match(result.stdout + result.stderr, /brand asset bytes do not match/);
+ assert.doesNotMatch(result.stdout + result.stderr, /digest-mismatch/);
+ assert.deepEqual(fs.readFileSync(output), previous);
+ }
+ }
+ if (healthy) {
+ const html = fs.readFileSync(output, 'utf8');
+ assert.ok(html.includes(`data-brand-sha256="${sha256(bytes)}"`));
+ assert.ok(html.includes(`data:image/x-icon;base64,${bytes.toString('base64')}`));
+ }
+ });
+}