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): normalize public source provenance

Harlyffda8ee7748b
diff --git a/archify.zip b/archify.zip
index 0fd92e50..1af9a41d 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 09d8efe3..30ab0f2a 100644
--- a/archify/references/brand-marks.md
+++ b/archify/references/brand-marks.md
@@ -65,6 +65,20 @@ 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.
+Remote-brand provenance in capture receipts, node metadata and SVG/HTML keeps
+the source URL's HTTP(S) scheme, host, port and path, but omits userinfo, query
+strings and fragments. The authored `brand.url` and all download/redirect URLs
+remain unchanged so existing pins still reproduce the same bytes and digest.
+Credential-bearing download URLs remain rejected. Built-in marks retain their
+recorded catalogue provenance.
+
+The public source link identifies the original site/path, not necessarily a
+downloadable asset: removing a signed query or a query-based page selector can
+make that link unusable or less specific. Prefer capturing a stable public
+landing page that exposes the intended icon when one is available; do not edit
+an existing pin's URL without capturing and verifying that source again. Paths
+are retained, so this normalization is not a general URL-secret scrubber.
+
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
diff --git a/archify/renderers/shared/brand-marks.mjs b/archify/renderers/shared/brand-marks.mjs
index 42b710c2..a269938a 100644
--- a/archify/renderers/shared/brand-marks.mjs
+++ b/archify/renderers/shared/brand-marks.mjs
@@ -50,6 +50,17 @@ function asUrl(value) {
}
}
+// Public provenance is separate from the URL used to reproduce a pinned asset.
+export function normalizeBrandSourceUrl(value) {
+ const url = asUrl(value);
+ if (!url) return null;
+ url.username = '';
+ url.password = '';
+ url.search = '';
+ url.hash = '';
+ return url.href;
+}
+
function domainMark(hostname) {
const host = hostname.toLocaleLowerCase('en-US').replace(/\.$/, '');
const candidates = [...MARK_BY_DOMAIN.entries()]
@@ -467,13 +478,14 @@ async function imageData(response) {
async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutMilliseconds()) {
const sourceUrl = new URL(value);
+ const publicSourceUrl = normalizeBrandSourceUrl(sourceUrl);
const fallback = (reason) => ({
id: sourceUrl.hostname,
title: sourceUrl.hostname,
category: 'link',
kind: 'fallback',
status: 'unavailable',
- sourceUrl: sourceUrl.href,
+ sourceUrl: publicSourceUrl,
reason,
});
try {
@@ -487,7 +499,7 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
category: 'link',
kind: 'remote',
status: 'captured',
- sourceUrl: sourceUrl.href,
+ sourceUrl: publicSourceUrl,
resolvedUrl: page.finalUrl.href,
...image,
};
@@ -508,7 +520,7 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
category: 'link',
kind: 'remote',
status: 'captured',
- sourceUrl: sourceUrl.href,
+ sourceUrl: publicSourceUrl,
resolvedUrl: fetched.finalUrl.href,
...image,
};
diff --git a/archify/test/brand-source-provenance.test.mjs b/archify/test/brand-source-provenance.test.mjs
new file mode 100644
index 00000000..9be78abf
--- /dev/null
+++ b/archify/test/brand-source-provenance.test.mjs
@@ -0,0 +1,140 @@
+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';
+import { normalizeBrandSourceUrl } from '../renderers/shared/brand-marks.mjs';
+
+const skillRoot = fileURLToPath(new URL('../', 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 = [
+ ['architecture', 'web-app.architecture.json', 'components'],
+ ['workflow', 'agent-tool-call.workflow.json', 'nodes'],
+ ['sequence', 'cache-miss-request.sequence.json', 'participants'],
+ ['dataflow', 'product-analytics.dataflow.json', 'nodes'],
+ ['lifecycle', 'agent-run.lifecycle.json', 'states'],
+];
+
+test('public brand links strip request data while preserving HTTP(S) origin and encoded paths', () => {
+ for (const [input, expected] of [
+ ['https://synthetic-user:[email protected]:443/brand%2Fmark?session=synthetic#part', 'https://example.com/brand%2Fmark'],
+ ['http://example.com:8080/a%20b?revision=synthetic#part', 'http://example.com:8080/a%20b'],
+ ['https://[2001:db8::1]:8443/logo.png?size=16#part', 'https://[2001:db8::1]:8443/logo.png'],
+ ['https://example.com/brand', 'https://example.com/brand'],
+ ['https://example.com', 'https://example.com/'],
+ ['javascript:synthetic', null],
+ ['/relative', null],
+ ]) {
+ assert.equal(normalizeBrandSourceUrl(input), expected);
+ }
+ const request = new URL('https://example.com/mark?revision=synthetic#part');
+ const original = request.href;
+ assert.equal(normalizeBrandSourceUrl(request), 'https://example.com/mark');
+ assert.equal(request.href, original, 'normalization must not mutate the request URL');
+});
+
+function run(directory, args) {
+ return new Promise((resolve, reject) => {
+ const child = spawn(process.execPath, [cli, ...args], {
+ cwd: directory, timeout: 15000,
+ env: { ...process.env, ARCHIFY_BRAND_ALLOW_PRIVATE: '1', ARCHIFY_UPDATE_CHECK_DISABLED: '1' },
+ });
+ let stdout = '', stderr = '';
+ child.stdout.setEncoding('utf8').on('data', data => { stdout += data; });
+ child.stderr.setEncoding('utf8').on('data', data => { stderr += data; });
+ child.once('error', reject);
+ child.once('close', status => resolve({ status, stdout, stderr }));
+ });
+}
+
+async function fixture(t) {
+ const directory = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-brand-source-'));
+ t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+ const requests = [];
+ const server = http.createServer((request, response) => {
+ requests.push(request.url);
+ if (request.url === '/mark.png?revision=synthetic-image'
+ || request.url === '/icon.png?signature=synthetic-icon&size=16') {
+ response.writeHead(200, { 'content-type': 'image/png' });
+ response.end(icon);
+ } else if (request.url === '/redirect?session=synthetic-session') {
+ response.writeHead(302, { location: '/landing?version=synthetic-page' });
+ response.end();
+ } else if (request.url === '/landing?version=synthetic-page') {
+ response.writeHead(200, { 'content-type': 'text/html' });
+ response.end('<head><link rel="icon" href="/icon.png?signature=synthetic-icon&amp;size=16"></head>');
+ } else {
+ response.writeHead(404);
+ response.end();
+ }
+ });
+ await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+ t.after(() => new Promise(resolve => {
+ server.closeAllConnections();
+ server.close(resolve);
+ }));
+ return { directory, requests, origin: `http://127.0.0.1:${server.address().port}` };
+}
+
+for (const [type, example, collection] of cases) {
+ for (const mode of ['image', 'redirected page']) {
+ test(`${type} shares clean brand provenance while fetching the pinned ${mode} unchanged`, { timeout: 30000 }, async t => {
+ const { directory, requests, origin } = await fixture(t);
+ const requestPath = mode === 'image'
+ ? '/mark.png?revision=synthetic-image'
+ : '/redirect?session=synthetic-session';
+ const url = `${origin}${requestPath}#synthetic-fragment`;
+ const publicSource = `${origin}${mode === 'image' ? '/mark.png' : '/redirect'}`;
+ const expectedRequests = mode === 'image' ? [requestPath] : [
+ requestPath, '/landing?version=synthetic-page', '/icon.png?signature=synthetic-icon&size=16',
+ ];
+ const capture = await run(directory, ['brands', 'capture', url, '--json']);
+ assert.equal(capture.status, 0, capture.stderr);
+ const receipt = JSON.parse(capture.stdout);
+ assert.deepEqual(receipt.brand, { url, sha256: digest }, 'retain the full URL in the authored pin');
+ assert.deepEqual(requests, expectedRequests);
+ assert.equal(receipt.evidence.source, publicSource);
+
+ const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples', example), 'utf8'));
+ diagram[collection][0].brand = receipt.brand;
+ diagram.meta.output = 'diagram.html';
+ fs.writeFileSync(path.join(directory, 'input.json'), JSON.stringify(diagram));
+ for (const command of ['validate', 'render']) {
+ requests.length = 0;
+ const result = await run(directory, [command, type, 'input.json', ...(command === 'validate' ? ['--json'] : ['diagram.html'])]);
+ assert.equal(result.status, 0, result.stderr || result.stdout);
+ assert.deepEqual(requests, expectedRequests, `${command} must preserve query-dependent downloads and redirects`);
+ }
+ const html = fs.readFileSync(path.join(directory, 'diagram.html'), 'utf8');
+ assert.ok(html.includes(`data-node-brand-source="${publicSource}"`));
+ assert.ok(html.includes(`data-brand-source="${publicSource}"`));
+ assert.ok(html.includes(`data-brand-sha256="${digest}"`));
+ assert.ok(html.includes(`data:image/png;base64,${icon.toString('base64')}`));
+ assert.doesNotMatch(html, /synthetic-(?:image|session|page|icon|fragment)/);
+ });
+ }
+}
+
+test('normalizing public provenance does not accept credentials or a changed digest', async t => {
+ const { directory, requests, origin } = await fixture(t);
+ const withCredentials = origin.replace('http://', 'http://synthetic-user:synthetic-password@');
+ const capture = await run(directory, ['brands', 'capture', `${withCredentials}/mark.png?revision=synthetic-image`, '--json']);
+ assert.notEqual(capture.status, 0);
+ assert.match(capture.stderr, /credentials/);
+ assert.deepEqual(requests, [], 'credentials must still fail before a request');
+
+ const diagram = JSON.parse(fs.readFileSync(path.join(skillRoot, 'examples/web-app.architecture.json'), 'utf8'));
+ diagram.components[0].brand = { url: `${origin}/mark.png?revision=synthetic-image#synthetic-fragment`, sha256: '0'.repeat(64) };
+ diagram.meta.output = 'diagram.html';
+ fs.writeFileSync(path.join(directory, 'input.json'), JSON.stringify(diagram));
+ const result = await run(directory, ['validate', 'architecture', 'input.json', '--json']);
+ assert.notEqual(result.status, 0);
+ assert.ok(JSON.parse(result.stdout).diagnostics.some(entry => entry.code === 'brand/digest-mismatch'));
+ assert.equal(fs.existsSync(path.join(directory, 'diagram.html')), false);
+});