knodin 0.5.0

package/dist/src/update-trust.js

@@ -0,0 +1,503 @@
+import { createHash, createPublicKey, verify as cryptoVerify, timingSafeEqual, } from "node:crypto";
+export class UpdateTrustError extends Error {
+    code;
+    role;
+    constructor(code, message, role) {
+        super(message);
+        this.name = "UpdateTrustError";
+        this.code = code;
+        this.role = role;
+    }
+}
+const ROLES = ["root", "targets", "snapshot", "timestamp"];
+const SHA256 = /^[a-f0-9]{64}$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const COMMIT = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+const MAX_CLOCK_SKEW_MS = 5 * 60 * 1_000;
+const MAX_LIFETIME_MS = {
+    root: 366 * 24 * 60 * 60 * 1_000,
+    targets: 93 * 24 * 60 * 60 * 1_000,
+    snapshot: 32 * 24 * 60 * 60 * 1_000,
+    timestamp: 8 * 24 * 60 * 60 * 1_000,
+};
+function invalid(message, role) {
+    throw new UpdateTrustError("invalid-schema", message, role);
+}
+function canonicalize(value, seen) {
+    if (value === null)
+        return "null";
+    if (typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            invalid("metadata numbers must be finite");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value))
+            invalid("metadata must not contain cycles");
+        seen.add(value);
+        const serialized = `[${value.map((item) => canonicalize(item, seen)).join(",")}]`;
+        seen.delete(value);
+        return serialized;
+    }
+    if (typeof value !== "object" || value === undefined) {
+        invalid(`metadata contains unsupported ${typeof value} value`);
+    }
+    if (seen.has(value))
+        invalid("metadata must not contain cycles");
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        invalid("metadata objects must be plain");
+    seen.add(value);
+    const object = value;
+    const serialized = `{${Object.keys(object)
+        // ECMAScript's default code-unit ordering is locale-independent, which is
+        // required because these bytes are signed on one host and verified on another.
+        // A localeCompare comparator would make trust bytes depend on host ICU data.
+        .sort() // NOSONAR: cryptographic canonicalization must not use locale collation.
+        .map((key) => {
+        if (object[key] === undefined)
+            invalid(`metadata field ${key} must not be undefined`);
+        return `${JSON.stringify(key)}:${canonicalize(object[key], seen)}`;
+    })
+        .join(",")}}`;
+    seen.delete(value);
+    return serialized;
+}
+/** Deterministic JSON used for every signed payload and metadata digest. */
+export function canonicalizeUpdateMetadata(value) {
+    return canonicalize(value, new Set());
+}
+function digest(value) {
+    return createHash("sha256").update(canonicalizeUpdateMetadata(value)).digest("hex");
+}
+export function computeUpdateKeyId(key) {
+    return digest(key);
+}
+export function metadataDescriptor(envelope) {
+    const serialized = canonicalizeUpdateMetadata(envelope);
+    return {
+        version: envelope.signed.version,
+        length: Buffer.byteLength(serialized),
+        hashes: { sha256: createHash("sha256").update(serialized).digest("hex") },
+    };
+}
+function assertRecord(value, label, role) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        invalid(`${label} must be an object`, role);
+    }
+    return value;
+}
+function assertOnlyKeys(record, allowed, label, role) {
+    const extras = Object.keys(record).filter((key) => !allowed.includes(key));
+    if (extras.length > 0)
+        invalid(`${label} contains unsupported fields: ${extras.join(", ")}`, role);
+}
+function validateEnvelopeShape(envelope, role) {
+    const record = assertRecord(envelope, `${role} envelope`, role);
+    assertOnlyKeys(record, ["signed", "signatures"], `${role} envelope`, role);
+    assertRecord(record.signed, `${role} signed payload`, role);
+    if (!Array.isArray(record.signatures) || record.signatures.length > 64) {
+        invalid(`${role} signatures must be a bounded array`, role);
+    }
+}
+function assertPositiveInteger(value, label, role) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        invalid(`${label} must be a positive safe integer`, role);
+    }
+    return value;
+}
+function assertNonNegativeInteger(value, label, role) {
+    if (!Number.isSafeInteger(value) || value < 0) {
+        invalid(`${label} must be a non-negative safe integer`, role);
+    }
+    return value;
+}
+function parseInstant(value, label, role) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}T/.test(value)) {
+        invalid(`${label} must be an ISO-8601 instant`, role);
+    }
+    const milliseconds = Date.parse(value);
+    if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString() !== value) {
+        invalid(`${label} must be a canonical UTC ISO-8601 instant`, role);
+    }
+    return milliseconds;
+}
+function validateCommon(value, expected, now) {
+    const record = assertRecord(value, `${expected} signed payload`, expected);
+    if (record._type !== expected)
+        invalid(`${expected} metadata has the wrong _type`, expected);
+    if (record.specVersion !== "1.0")
+        invalid(`${expected} metadata requires specVersion 1.0`, expected);
+    assertPositiveInteger(record.version, `${expected}.version`, expected);
+    const generatedAt = parseInstant(record.generatedAt, `${expected}.generatedAt`, expected);
+    const expires = parseInstant(record.expires, `${expected}.expires`, expected);
+    if (generatedAt > now + MAX_CLOCK_SKEW_MS) {
+        throw new UpdateTrustError("future-metadata", `${expected} metadata is generated in the future`, expected);
+    }
+    if (expires <= now) {
+        throw new UpdateTrustError("expired", `${expected} metadata expired at ${record.expires}`, expected);
+    }
+    if (expires <= generatedAt || expires - generatedAt > MAX_LIFETIME_MS[expected]) {
+        invalid(`${expected} metadata lifetime exceeds its role policy`, expected);
+    }
+}
+function validatePublicKey(key, keyid) {
+    const record = assertRecord(key, `key ${keyid}`);
+    const keyval = assertRecord(record.keyval, `key ${keyid}.keyval`);
+    assertOnlyKeys(record, ["keytype", "scheme", "keyval"], `key ${keyid}`);
+    assertOnlyKeys(keyval, ["public"], `key ${keyid}.keyval`);
+    if (record.keytype !== "ed25519" || record.scheme !== "ed25519") {
+        invalid(`key ${keyid} must use Ed25519`);
+    }
+    if (typeof keyval.public !== "string" ||
+        keyval.public.length < 32 ||
+        keyval.public.length > 8_192) {
+        invalid(`key ${keyid} has an invalid public key`);
+    }
+    let parsed;
+    try {
+        parsed = createPublicKey(keyval.public);
+    }
+    catch {
+        invalid(`key ${keyid} is not a valid public key`);
+    }
+    if (parsed.asymmetricKeyType !== "ed25519")
+        invalid(`key ${keyid} is not an Ed25519 key`);
+    if (computeUpdateKeyId(record) !== keyid) {
+        invalid(`key ${keyid} does not match its content-derived key id`);
+    }
+}
+function validateRootKeys(value) {
+    const keys = assertRecord(value, "root.keys", "root");
+    if (Object.keys(keys).length < 6 || Object.keys(keys).length > 64) {
+        invalid("root.keys must contain between 6 and 64 keys", "root");
+    }
+    for (const [keyid, key] of Object.entries(keys)) {
+        if (!SHA256.test(keyid))
+            invalid(`root key id ${keyid} is not a SHA-256 digest`, "root");
+        validatePublicKey(key, keyid);
+    }
+    return keys;
+}
+function validateRoleKey(keyid, role, keys, unique, assigned) {
+    if (typeof keyid !== "string" || !Object.hasOwn(keys, keyid)) {
+        invalid(`${role} references an unknown key`, "root");
+    }
+    if (unique.has(keyid))
+        invalid(`${role} contains a duplicate key id`, "root");
+    unique.add(keyid);
+    const previousRole = assigned.get(keyid);
+    if (previousRole !== undefined) {
+        throw new UpdateTrustError("role-separation", `key ${keyid} is assigned to both ${previousRole} and ${role}`, "root");
+    }
+    assigned.set(keyid, role);
+}
+function validateRoleDefinition(value, role, keys, assigned) {
+    const definition = assertRecord(value, `root.roles.${role}`, "root");
+    assertOnlyKeys(definition, ["keyids", "threshold"], `root.roles.${role}`, "root");
+    const threshold = assertPositiveInteger(definition.threshold, `root.roles.${role}.threshold`, "root");
+    if (!Array.isArray(definition.keyids) || definition.keyids.length === 0) {
+        invalid(`root.roles.${role}.keyids must be a non-empty array`, "root");
+    }
+    if (definition.keyids.length > 64)
+        invalid(`${role} contains too many key ids`, "root");
+    if (threshold > definition.keyids.length)
+        invalid(`${role} threshold exceeds its key count`, "root");
+    if ((role === "root" || role === "targets") && threshold < 2) {
+        invalid(`${role} requires a production threshold of at least two`, "root");
+    }
+    const unique = new Set();
+    for (const keyid of definition.keyids)
+        validateRoleKey(keyid, role, keys, unique, assigned);
+}
+function validateRoot(root, now) {
+    validateCommon(root, "root", now);
+    assertOnlyKeys(root, [
+        "_type",
+        "specVersion",
+        "version",
+        "generatedAt",
+        "expires",
+        "consistentSnapshot",
+        "keys",
+        "roles",
+    ], "root signed payload", "root");
+    if (root.consistentSnapshot !== true)
+        invalid("root must require consistent snapshots", "root");
+    const keys = validateRootKeys(root.keys);
+    const roles = assertRecord(root.roles, "root.roles", "root");
+    const assigned = new Map();
+    for (const role of ROLES)
+        validateRoleDefinition(roles[role], role, keys, assigned);
+    const extras = Object.keys(roles).filter((role) => !ROLES.includes(role));
+    if (extras.length > 0)
+        invalid(`root contains unsupported roles: ${extras.join(", ")}`, "root");
+}
+function validateSignatureRecord(signature, role) {
+    const record = assertRecord(signature, `${role} signature`, role);
+    assertOnlyKeys(record, ["keyid", "sig"], `${role} signature`, role);
+    if (typeof record.keyid !== "string" || typeof record.sig !== "string") {
+        invalid(`${role} signature requires keyid and sig strings`, role);
+    }
+    return record;
+}
+function verifyOneSignature(signature, root, role, authorized, payload) {
+    if (!authorized.has(signature.keyid))
+        return "ignored";
+    if (signature.sig.length !== 88 || !BASE64.test(signature.sig)) {
+        invalid(`${role} signature is not canonical Ed25519 base64`, role);
+    }
+    const signatureBytes = Buffer.from(signature.sig, "base64");
+    if (signatureBytes.byteLength !== 64)
+        invalid(`${role} Ed25519 signature must be 64 bytes`, role);
+    const key = root.keys[signature.keyid];
+    return cryptoVerify(null, payload, createPublicKey(key.keyval.public), signatureBytes)
+        ? "valid"
+        : "invalid";
+}
+function verifyRoleSignatures(envelope, root, role) {
+    validateEnvelopeShape(envelope, role);
+    const definition = root.roles[role];
+    const authorized = new Set(definition.keyids);
+    const seen = new Set();
+    const payload = Buffer.from(canonicalizeUpdateMetadata(envelope.signed));
+    let valid = 0;
+    let authorizedInvalid = false;
+    for (const candidate of envelope.signatures) {
+        const signature = validateSignatureRecord(candidate, role);
+        if (seen.has(signature.keyid))
+            invalid(`${role} contains a duplicate signature`, role);
+        seen.add(signature.keyid);
+        const outcome = verifyOneSignature(signature, root, role, authorized, payload);
+        if (outcome === "valid")
+            valid += 1;
+        if (outcome === "invalid")
+            authorizedInvalid = true;
+    }
+    if (valid < definition.threshold) {
+        if (authorizedInvalid) {
+            throw new UpdateTrustError("invalid-signature", `${role} contains an invalid signature`, role);
+        }
+        throw new UpdateTrustError("insufficient-signatures", `${role} has ${valid} valid signature(s); ${definition.threshold} required`, role);
+    }
+}
+function validateDescriptor(value, label, role) {
+    const record = assertRecord(value, label, role);
+    assertOnlyKeys(record, ["version", "length", "hashes"], label, role);
+    assertPositiveInteger(record.version, `${label}.version`, role);
+    assertNonNegativeInteger(record.length, `${label}.length`, role);
+    const hashes = assertRecord(record.hashes, `${label}.hashes`, role);
+    assertOnlyKeys(hashes, ["sha256"], `${label}.hashes`, role);
+    if (typeof hashes.sha256 !== "string" || !SHA256.test(hashes.sha256)) {
+        invalid(`${label}.hashes.sha256 must be a lowercase SHA-256 digest`, role);
+    }
+}
+function validateTarget(target, targetPath) {
+    const record = assertRecord(target, `target ${targetPath}`, "targets");
+    assertOnlyKeys(record, ["length", "hashes", "custom"], `target ${targetPath}`, "targets");
+    assertNonNegativeInteger(record.length, `target ${targetPath}.length`, "targets");
+    const hashes = assertRecord(record.hashes, `target ${targetPath}.hashes`, "targets");
+    assertOnlyKeys(hashes, ["sha256"], `target ${targetPath}.hashes`, "targets");
+    if (typeof hashes.sha256 !== "string" || !SHA256.test(hashes.sha256)) {
+        invalid(`target ${targetPath} requires a lowercase SHA-256 digest`, "targets");
+    }
+    const custom = assertRecord(record.custom, `target ${targetPath}.custom`, "targets");
+    assertOnlyKeys(custom, [
+        "version",
+        "channel",
+        "sourceCommit",
+        "provenanceSha256",
+        "sbomSha256",
+        "sbomAttestationSha256",
+        "releaseAttestationSha256",
+    ], `target ${targetPath}.custom`, "targets");
+    if (typeof custom.version !== "string" ||
+        custom.version.length > 128 ||
+        !SEMVER.test(custom.version)) {
+        invalid(`target ${targetPath} requires a semantic version`, "targets");
+    }
+    if (typeof custom.channel !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(custom.channel)) {
+        invalid(`target ${targetPath} has an invalid channel`, "targets");
+    }
+    if (typeof custom.sourceCommit !== "string" || !COMMIT.test(custom.sourceCommit)) {
+        invalid(`target ${targetPath} requires a full source commit`, "targets");
+    }
+    for (const field of [
+        "provenanceSha256",
+        "sbomSha256",
+        "sbomAttestationSha256",
+        "releaseAttestationSha256",
+    ]) {
+        if (custom[field] !== undefined &&
+            (typeof custom[field] !== "string" || !SHA256.test(custom[field]))) {
+            invalid(`target ${targetPath}.${field} must be a lowercase SHA-256 digest`, "targets");
+        }
+    }
+}
+function validateTargets(targets, now) {
+    validateCommon(targets, "targets", now);
+    assertOnlyKeys(targets, ["_type", "specVersion", "version", "generatedAt", "expires", "targets"], "targets signed payload", "targets");
+    const records = assertRecord(targets.targets, "targets.targets", "targets");
+    if (Object.keys(records).length === 0 || Object.keys(records).length > 1_000) {
+        invalid("targets metadata must contain between 1 and 1000 targets", "targets");
+    }
+    for (const [targetPath, target] of Object.entries(records)) {
+        if (targetPath.length === 0 ||
+            targetPath.length > 512 ||
+            targetPath.startsWith("/") ||
+            targetPath.includes("\\") ||
+            targetPath.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+            invalid(`unsafe target path: ${targetPath}`, "targets");
+        }
+        validateTarget(target, targetPath);
+    }
+}
+function validateSnapshot(snapshot, now) {
+    validateCommon(snapshot, "snapshot", now);
+    assertOnlyKeys(snapshot, ["_type", "specVersion", "version", "generatedAt", "expires", "meta"], "snapshot signed payload", "snapshot");
+    const meta = assertRecord(snapshot.meta, "snapshot.meta", "snapshot");
+    if (Object.keys(meta).length !== 1 || meta["targets.json"] === undefined) {
+        invalid("snapshot must describe exactly targets.json", "snapshot");
+    }
+    validateDescriptor(meta["targets.json"], "snapshot.meta.targets.json", "snapshot");
+}
+function validateTimestamp(timestamp, now) {
+    validateCommon(timestamp, "timestamp", now);
+    assertOnlyKeys(timestamp, ["_type", "specVersion", "version", "generatedAt", "expires", "meta"], "timestamp signed payload", "timestamp");
+    const meta = assertRecord(timestamp.meta, "timestamp.meta", "timestamp");
+    if (Object.keys(meta).length !== 1 || meta["snapshot.json"] === undefined) {
+        invalid("timestamp must describe exactly snapshot.json", "timestamp");
+    }
+    validateDescriptor(meta["snapshot.json"], "timestamp.meta.snapshot.json", "timestamp");
+}
+function requireDescriptorMatch(descriptor, envelope, label) {
+    const actual = metadataDescriptor(envelope);
+    if (descriptor.version !== actual.version ||
+        descriptor.length !== actual.length ||
+        descriptor.hashes.sha256 !== actual.hashes.sha256) {
+        throw new UpdateTrustError("mix-and-match", `${label} does not match its signed descriptor`);
+    }
+}
+function stateEntry(envelope) {
+    return { version: envelope.signed.version, sha256: digest(envelope) };
+}
+function validateTrustedState(previous) {
+    const record = assertRecord(previous, "previous trusted state");
+    assertOnlyKeys(record, ROLES, "previous trusted state");
+    for (const role of ROLES) {
+        const entry = assertRecord(record[role], `previous trusted state.${role}`, role);
+        assertOnlyKeys(entry, ["version", "sha256"], `previous trusted state.${role}`, role);
+        assertPositiveInteger(entry.version, `previous trusted state.${role}.version`, role);
+        if (typeof entry.sha256 !== "string" || !SHA256.test(entry.sha256)) {
+            invalid(`previous trusted state.${role}.sha256 must be a lowercase SHA-256 digest`, role);
+        }
+    }
+}
+function assertMonotonic(current, previous) {
+    if (!previous)
+        return;
+    validateTrustedState(previous);
+    for (const role of ROLES) {
+        if (current[role].version < previous[role].version) {
+            throw new UpdateTrustError("rollback", `${role} version moved backwards`, role);
+        }
+        if (current[role].version === previous[role].version &&
+            current[role].sha256 !== previous[role].sha256) {
+            throw new UpdateTrustError("equivocation", `${role} changed without increasing its version`, role);
+        }
+    }
+}
+function selectRoot(candidate, trusted, pinnedDigest, now) {
+    if (!SHA256.test(pinnedDigest))
+        invalid("trusted root pin must be a lowercase SHA-256 digest", "root");
+    validateEnvelopeShape(trusted, "root");
+    validateRoot(trusted.signed, now);
+    verifyRoleSignatures(trusted, trusted.signed, "root");
+    const trustedDigest = digest(trusted);
+    if (!timingSafeEqual(Buffer.from(trustedDigest, "hex"), Buffer.from(pinnedDigest, "hex"))) {
+        throw new UpdateTrustError("untrusted-root", "trusted root does not match its independent pin", "root");
+    }
+    validateEnvelopeShape(candidate, "root");
+    validateRoot(candidate.signed, now);
+    const candidateDigest = digest(candidate);
+    if (candidate.signed.version < trusted.signed.version) {
+        throw new UpdateTrustError("rollback", "root version moved backwards", "root");
+    }
+    if (candidate.signed.version === trusted.signed.version) {
+        if (candidateDigest !== trustedDigest) {
+            throw new UpdateTrustError("equivocation", "trusted root changed without rotation", "root");
+        }
+        return candidate.signed;
+    }
+    if (candidate.signed.version !== trusted.signed.version + 1) {
+        throw new UpdateTrustError("root-rotation", "root rotations must be applied one version at a time", "root");
+    }
+    verifyRoleSignatures(candidate, trusted.signed, "root");
+    verifyRoleSignatures(candidate, candidate.signed, "root");
+    return candidate.signed;
+}
+/**
+ * Advance an independently pinned root through a bounded caller-supplied chain.
+ * Every candidate must be exactly one version newer and satisfy both the old
+ * and new root thresholds; no fetched root becomes trusted merely by appearing
+ * later in the array.
+ */
+export function verifyUpdateRootChain(initialRoot, initialRootSha256, candidates, now = new Date()) {
+    const verificationTime = now.getTime();
+    if (!Number.isFinite(verificationTime))
+        invalid("verification time must be valid");
+    let trusted = initialRoot;
+    let trustedDigest = initialRootSha256;
+    selectRoot(trusted, trusted, trustedDigest, verificationTime);
+    for (const candidate of candidates) {
+        selectRoot(candidate, trusted, trustedDigest, verificationTime);
+        trusted = candidate;
+        trustedDigest = digest(candidate);
+    }
+    return trusted;
+}
+/**
+ * Verify a complete TUF-inspired metadata chain without network access or mutation.
+ * The caller owns fetching and persistence; this function fails closed on every
+ * trust, freshness, rollback, or binding error.
+ */
+export function verifyUpdateMetadataBundle(bundle, options) {
+    const now = (options.now ?? new Date()).getTime();
+    if (!Number.isFinite(now))
+        invalid("verification time must be valid");
+    const root = selectRoot(bundle.root, options.trustedRoot, options.trustedRootSha256, now);
+    validateTargets(bundle.targets.signed, now);
+    validateSnapshot(bundle.snapshot.signed, now);
+    validateTimestamp(bundle.timestamp.signed, now);
+    verifyRoleSignatures(bundle.targets, root, "targets");
+    verifyRoleSignatures(bundle.snapshot, root, "snapshot");
+    verifyRoleSignatures(bundle.timestamp, root, "timestamp");
+    requireDescriptorMatch(bundle.timestamp.signed.meta["snapshot.json"], bundle.snapshot, "snapshot metadata");
+    requireDescriptorMatch(bundle.snapshot.signed.meta["targets.json"], bundle.targets, "targets metadata");
+    const state = {
+        root: stateEntry(bundle.root),
+        targets: stateEntry(bundle.targets),
+        snapshot: stateEntry(bundle.snapshot),
+        timestamp: stateEntry(bundle.timestamp),
+    };
+    assertMonotonic(state, options.previous);
+    const target = bundle.targets.signed.targets[options.targetPath];
+    if (!target) {
+        throw new UpdateTrustError("target-not-found", `targets metadata does not authorize ${options.targetPath}`, "targets");
+    }
+    return { targetPath: options.targetPath, target, root, rootEnvelope: bundle.root, state };
+}
+/** Verify downloaded bytes before quarantine or any package-manager action. */
+export function verifyTargetArtifact(artifact, target) {
+    if (artifact.byteLength !== target.length) {
+        throw new UpdateTrustError("artifact-mismatch", `artifact length ${artifact.byteLength} does not match signed length ${target.length}`);
+    }
+    const actual = createHash("sha256").update(artifact).digest();
+    const expected = Buffer.from(target.hashes.sha256, "hex");
+    if (actual.byteLength !== expected.byteLength || !timingSafeEqual(actual, expected)) {
+        throw new UpdateTrustError("artifact-mismatch", "artifact SHA-256 does not match signed metadata");
+    }
+}

package/dist/src/version.js

@@ -0,0 +1,13 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+let packageRoot = path.dirname(fileURLToPath(import.meta.url));
+while (!fs.existsSync(path.join(packageRoot, "package.json")) &&
+    packageRoot !== path.parse(packageRoot).root) {
+    packageRoot = path.dirname(packageRoot);
+}
+const packageMetadata = require(path.join(packageRoot, "package.json"));
+/** Installed package version, shared by CLI health and the MCP server. */
+export const KNODIN_VERSION = typeof packageMetadata.version === "string" ? packageMetadata.version : "0.0.0";

package/dist/src/visualization.js

@@ -0,0 +1,162 @@
+import { execFileSync } from "node:child_process";
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+const DEFAULT_BYTE_BUDGET = 32_768;
+const MIN_BYTE_BUDGET = 4_096;
+const MAX_CALL_FLOW_EDGES = 20;
+function html(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;");
+}
+function sourceCommit(repo) {
+    try {
+        return execFileSync("git", ["rev-parse", "HEAD"], {
+            cwd: repo,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "unavailable";
+    }
+}
+function safeOutput(repo, output) {
+    if (!output || path.extname(output).toLowerCase() !== ".html")
+        throw new Error("knodin visualize: --output must be a repository-relative .html path");
+    const absolute = path.resolve(repo, output);
+    if (absolute === repo || !absolute.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin visualize: output path must stay inside the repository");
+    const targetStat = fs.lstatSync(absolute, { throwIfNoEntry: false });
+    if (targetStat?.isSymbolicLink())
+        throw new Error("knodin visualize: output path may not be a symlink");
+    if (targetStat) {
+        const realTarget = fs.realpathSync(absolute);
+        if (!realTarget.startsWith(`${repo}${path.sep}`))
+            throw new Error("knodin visualize: output path may not follow a symlink outside the repository");
+    }
+    let parent = path.dirname(absolute);
+    while (!fs.existsSync(parent) && parent !== repo)
+        parent = path.dirname(parent);
+    const realParent = fs.realpathSync(parent);
+    if (realParent !== repo && !realParent.startsWith(`${repo}${path.sep}`))
+        throw new Error("knodin visualize: output path may not traverse a symlink outside the repository");
+    return { absolute, relative: path.relative(repo, absolute).replaceAll(path.sep, "/") };
+}
+function render(input) {
+    const communityRows = input.communities
+        .map((community) => {
+        const files = (community.files ?? []).slice(0, 12).join(", ") || "no file detail returned";
+        const symbols = (community.symbols ?? []).slice(0, 12).join(", ") || "no symbol detail returned";
+        return `<details><summary>${html(community.name)} <span>${community.size} symbols</span></summary><p>Cohesion: ${community.cohesion.toFixed(3)}</p><p><strong>Files:</strong> ${html(files)}</p><p><strong>Symbols:</strong> ${html(symbols)}</p></details>`;
+    })
+        .join("\n");
+    const hotspot = (kind, rows) => rows
+        .map((node) => {
+        const metric = "degree" in node ? `degree ${node.degree}` : `betweenness ${node.betweenness.toFixed(3)}`;
+        return `<li><strong>${kind}</strong> ${html(node.symbol)} — ${html(metric)}; ${html(node.filePath || "unresolved file")} (${html(node.communityId ?? "unassigned")})</li>`;
+    })
+        .join("\n");
+    const edgeRows = (edges) => edges
+        .map((edge) => `<li data-evidence="${edge.label}"><code>${html(edge.from)}</code> → <code>${html(edge.to)}</code> <span>${html(edge.kind)}</span><br><small>${edge.label === "exact" ? "Source evidence" : "Heuristic source evidence"}: ${html(edge.evidence)}</small></li>`)
+        .join("\n") || "<li>No bounded source-evidenced relationships were returned.</li>";
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>knodin architecture visualization</title><style>body{font:16px system-ui,sans-serif;margin:2rem auto;max-width:74rem;color:#172033;background:#f6f8fb;line-height:1.45}section{background:#fff;border:1px solid #d9dee7;border-radius:.55rem;padding:1rem 1.25rem;margin:1rem 0}details{border-top:1px solid #e5e9ef;padding:.6rem 0}summary{cursor:pointer;font-weight:650}summary span,small{color:#526170}li{margin:.55rem 0}code{background:#edf1f6;padding:.1rem .3rem;border-radius:.2rem;overflow-wrap:anywhere}[data-evidence=heuristic]{border-left:3px solid #d18a00;padding-left:.55rem}</style></head>
+<body><h1>knodin local architecture visualization</h1><p>Generated locally from the persisted knodin graph. Source commit <code>${html(input.commit)}</code>; Index freshness <code>${html(input.freshness)}</code>; ${input.truncated ? "some lists are bounded by the artifact budget." : "all displayed lists fit the requested artifact budget."}</p>
+<section><h2>Subsystem drill-down</h2>${communityRows || "<p>No communities were returned.</p>"}</section>
+<section><h2>Hub and bridge inspection</h2><ul>${hotspot("Hub", input.hubs)}${hotspot("Bridge", input.bridges)}</ul></section>
+<section><h2>Architecture relationships</h2><ul>${edgeRows(input.architectureEdges)}</ul></section>
+<section><h2>Call-flow navigation</h2><p>Static downstream traversal from <code>${html(input.entry)}</code>, depth ${input.depth}; this is not a runtime trace.</p><ul>${edgeRows(input.callFlowEdges)}</ul></section>
+</body></html>\n`;
+}
+export async function writeVisualization(engine, repoPath, request) {
+    const repo = fs.realpathSync(repoPath);
+    const output = safeOutput(repo, request.outputPath);
+    const entry = request.entry.trim();
+    if (!entry)
+        throw new Error("knodin visualize: an entry selector is required");
+    const depth = request.depth ?? 3;
+    if (!Number.isInteger(depth) || depth < 1 || depth > 6)
+        throw new Error("knodin visualize: --depth must be an integer from 1 through 6");
+    const byteBudget = request.byteBudget ?? DEFAULT_BYTE_BUDGET;
+    if (!Number.isInteger(byteBudget) || byteBudget < MIN_BYTE_BUDGET || byteBudget > 65_536)
+        throw new Error("knodin visualize: --max-bytes must be an integer from 4096 through 65536");
+    const [map, traversal] = await Promise.all([
+        engine.map(repo, "standard", { topN: 12, sort: "name" }),
+        engine.query("traverse", entry, repo, undefined, MAX_CALL_FLOW_EDGES, depth, "standard", request.selector, undefined, { direction: "downstream", relationKinds: ["call"], includeDataFlow: true }),
+    ]);
+    if (traversal.ambiguity || traversal.count === 0)
+        throw new Error("knodin visualize: entry selector did not resolve to a traversable symbol");
+    const architectureEdges = map.edges
+        .filter((edge) => Boolean(edge.sourceEvidence))
+        .slice(0, MAX_CALL_FLOW_EDGES)
+        .map((edge) => ({
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind,
+        evidence: edge.sourceEvidence ?? "",
+        label: edge.confidenceLabel === "heuristic" || edge.provenance !== "EXTRACTED"
+            ? "heuristic"
+            : "exact",
+    }));
+    const callFlowEdges = (traversal.edges ?? []).slice(0, MAX_CALL_FLOW_EDGES).map((edge) => ({
+        from: edge.from,
+        to: edge.to,
+        kind: edge.kind ?? "call",
+        evidence: edge.dataFlow?.evidence ??
+            `${edge.fromFile ?? "unresolved file"}:${edge.line ?? "unknown line"}`,
+        label: edge.dataFlow?.heuristic || edge.provenance === "INFERRED"
+            ? "heuristic"
+            : "exact",
+    }));
+    let communities = map.communities.slice(0, 12);
+    let hubs = map.hubs.slice(0, 10);
+    let bridges = map.bridges.slice(0, 10);
+    let architecture = architectureEdges;
+    let callFlow = callFlowEdges;
+    let truncated = Boolean(traversal.truncated);
+    let artifact = "";
+    for (;;) {
+        artifact = render({
+            commit: sourceCommit(repo),
+            freshness: map.staleness ?? "unknown",
+            communities,
+            hubs,
+            bridges,
+            architectureEdges: architecture,
+            callFlowEdges: callFlow,
+            entry,
+            depth,
+            truncated,
+        });
+        if (Buffer.byteLength(artifact) <= byteBudget)
+            break;
+        truncated = true;
+        if (architecture.length)
+            architecture = architecture.slice(0, -1);
+        else if (callFlow.length)
+            callFlow = callFlow.slice(0, -1);
+        else if (communities.length)
+            communities = communities.slice(0, -1);
+        else if (hubs.length)
+            hubs = hubs.slice(0, -1);
+        else if (bridges.length)
+            bridges = bridges.slice(0, -1);
+        else
+            throw new Error("knodin visualize: budget is too small for visualization metadata");
+    }
+    fs.mkdirSync(path.dirname(output.absolute), { recursive: true });
+    fs.writeFileSync(output.absolute, artifact);
+    return {
+        outputPath: output.relative,
+        bytes: Buffer.byteLength(artifact),
+        sha256: crypto.createHash("sha256").update(artifact).digest("hex"),
+        byteBudget,
+        truncated,
+        indexFreshness: map.staleness ?? "unknown",
+        callFlow: { entry, depth, edgeCount: callFlow.length, truncated: Boolean(traversal.truncated) },
+    };
+}