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): normalize public source provenance
Harlyffda8ee7748b
diff --git a/archify.zip b/archify.zipindex 0fd92e50..1af9a41d 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/references/brand-marks.md b/archify/references/brand-marks.mdindex 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 insteadof 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 rangeafter the complete directory and within the downloaded file. This bounds checkalso applies when reproducing a pinned capture. PNG/DIB payloads, multiplediff --git a/archify/renderers/shared/brand-marks.mjs b/archify/renderers/shared/brand-marks.mjsindex 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() + captureTimeoutMcategory: '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() + captureTimeoutMcategory: '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.mjsnew file mode 100644index 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&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);+});