@slicedearth/whoisleuth-cli 2.3.0 → 2.5.1

package/packages/evidence/domain-posture-context.mjs

@@ -0,0 +1,79 @@
+import { normalizeExplicitIsoTimestamp } from "./observation.mjs";
+import { normalizeDomain } from "./domain-name.mjs";
+export const DOMAIN_POSTURE_COMPARISON_VERSION = 1;
+export const MAX_POSTURE_CHECKS = 32;
+export const MAX_POSTURE_CHECK_RECORDS = 64;
+export const MAX_POSTURE_RECORD_LENGTH = 4096;
+function contextRecord(value, keys, label) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)
+        || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+        || Reflect.ownKeys(value).length !== keys.length)
+        throw new TypeError(`${label} has an invalid structure.`);
+    const result = {};
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (!descriptor?.enumerable || !('value' in descriptor))
+            throw new TypeError(`${label} requires ordinary data fields.`);
+        result[key] = descriptor.value;
+    }
+    if (result.version !== DOMAIN_POSTURE_COMPARISON_VERSION)
+        throw new TypeError(`${label} has an unsupported comparison version.`);
+    return result;
+}
+/** Missing legacy provenance stays missing; declared malformed or future context is rejected. */
+export function normalizeDomainPostureSourceContext(value) {
+    if (value === undefined)
+        return undefined;
+    const source = contextRecord(value, ['version', 'source', 'observedAt', 'state', 'omittedRecords'], 'Posture source context');
+    const observedAt = normalizeExplicitIsoTimestamp(source.observedAt);
+    if (typeof source.source !== 'string' || !['dns_ns', 'dns_mx', 'dns_caa', 'registry_rdap'].includes(source.source)
+        || typeof source.state !== 'string' || !['complete', 'partial', 'unavailable'].includes(source.state)
+        || (source.observedAt !== null && observedAt === null)
+        || (source.omittedRecords !== null && (!Number.isSafeInteger(source.omittedRecords) || Number(source.omittedRecords) < 0))
+        || (source.state === 'complete' && source.omittedRecords !== 0)) {
+        throw new TypeError('Posture source context has invalid provenance or omission counts.');
+    }
+    return Object.freeze({ ...source, observedAt });
+}
+export function normalizeDomainPostureProfileContext(value) {
+    if (value === undefined)
+        return undefined;
+    const source = contextRecord(value, ['version', 'domain', 'profileId', 'profileFingerprint'], 'Posture profile context');
+    const domain = typeof source.domain === 'string' ? normalizeDomain(source.domain) : '';
+    if (!domain || domain !== source.domain || typeof source.profileId !== 'string'
+        || !source.profileId.trim() || source.profileId.length > 200 || /[\u0000-\u001f\u007f]/u.test(source.profileId)
+        || typeof source.profileFingerprint !== 'string' || !/^[a-f0-9]{64}$/u.test(source.profileFingerprint)) {
+        throw new TypeError('Posture profile context has an invalid target or collection identity.');
+    }
+    return Object.freeze(source);
+}
+export const POSTURE_CHECK_SOURCES = Object.freeze({
+    nameservers: 'dns_ns', mx: 'dns_mx', caa: 'dns_caa', registration_lock: 'registry_rdap',
+});
+export const POSTURE_SOURCE_LABELS = Object.freeze({
+    dns_ns: 'DNS NS', dns_mx: 'DNS MX', dns_caa: 'DNS CAA', registry_rdap: 'Registry RDAP',
+});
+export function postureTransferRestriction(records) {
+    if (!records.length)
+        return null;
+    return records.some((value) => value === 'clienttransferprohibited' || value === 'servertransferprohibited')
+        ? 'required' : 'not_required';
+}
+export function postureSourceAdmission(check, capturedAt, now) {
+    if (!check?.sourceContext)
+        return 'Source comparison context is unavailable for this retained check.';
+    const context = check.sourceContext;
+    const expected = POSTURE_CHECK_SOURCES[check.id];
+    if (context.version !== DOMAIN_POSTURE_COMPARISON_VERSION || !expected || expected !== context.source)
+        return 'The source or comparison version does not match this field.';
+    const captured = normalizeExplicitIsoTimestamp(capturedAt);
+    const observed = normalizeExplicitIsoTimestamp(context.observedAt);
+    const reviewed = normalizeExplicitIsoTimestamp(now);
+    if (!captured || !observed || !reviewed)
+        return 'A source, capture or review time is unavailable.';
+    if (Date.parse(observed) > Date.parse(captured) || Date.parse(captured) > Date.parse(reviewed))
+        return 'The source or capture time is later than its review.';
+    if (context.state !== 'complete' || context.omittedRecords !== 0)
+        return 'The source observation is incomplete; retained values cannot establish alignment or drift.';
+    return null;
+}

package/packages/evidence/email-recipient.mjs

@@ -0,0 +1,18 @@
+// Single plain recipient admission for manually opened drafts, not delivery validation.
+const SINGLE_ADDRESS = /^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$/u;
+export function emailRecipient(value) {
+    if (typeof value !== 'string' || value.length > 320 || /[\u0000-\u001f\u007f]/u.test(value))
+        return null;
+    const address = value.trim();
+    return SINGLE_ADDRESS.test(address) ? address : null;
+}
+/** Encode the recipient independently; upstream text never becomes a header. */
+export function recipientMailto(value, headers) {
+    const address = emailRecipient(value);
+    if (!address)
+        return null;
+    const separator = address.indexOf('@');
+    const recipient = `${encodeURIComponent(address.slice(0, separator))}@${encodeURIComponent(address.slice(separator + 1))}`;
+    const query = headers ? `?subject=${encodeURIComponent(headers.subject)}&body=${encodeURIComponent(headers.body)}` : '';
+    return `mailto:${recipient}${query}`;
+}

package/packages/evidence/image-regions.mjs

@@ -0,0 +1,56 @@
+import { array, enumeration, exact, integer, text } from "./artifact-structure.mjs";
+import { readRetainedFileReference } from "./retained-file.mjs";
+// The decoded RGBA surface is bounded independently of compressed file bytes.
+export const MAX_EVIDENCE_IMAGE_PIXELS = 16 * 1024 * 1024;
+export const MAX_EVIDENCE_IMAGE_DIMENSION = 10_000;
+// Each selected region emits at most four solid rectangles; no nested effects.
+export const MAX_EVIDENCE_IMAGE_REGIONS = 64;
+export function readEvidenceImageDimensions(width, height) {
+    const result = {
+        width: integer(width, 'Image width', 1, MAX_EVIDENCE_IMAGE_DIMENSION),
+        height: integer(height, 'Image height', 1, MAX_EVIDENCE_IMAGE_DIMENSION),
+    };
+    if (result.width * result.height > MAX_EVIDENCE_IMAGE_PIXELS)
+        throw new TypeError('This image exceeds the decoded-image pixel bound. Its original bytes are unchanged.');
+    return Object.freeze(result);
+}
+/** Pixel coordinates are integers, remain inside the source, and are never clipped silently. */
+export function readImageRegionPlan(raw) {
+    const value = exact(raw, ['width', 'height', 'regions'], 'Image region plan');
+    const dimensions = readEvidenceImageDimensions(value.width, value.height);
+    const regions = Array.from(array(value.regions, 'Image regions', MAX_EVIDENCE_IMAGE_REGIONS, 1), candidate => {
+        const region = exact(candidate, ['kind', 'x', 'y', 'width', 'height'], 'Image region');
+        const kind = enumeration(region.kind, ['redact', 'outline'], 'Image region kind');
+        const x = integer(region.x, 'Region left coordinate', 0, dimensions.width - 1);
+        const y = integer(region.y, 'Region top coordinate', 0, dimensions.height - 1);
+        const width = integer(region.width, 'Region width', 1, dimensions.width - x);
+        const height = integer(region.height, 'Region height', 1, dimensions.height - y);
+        return Object.freeze({ kind, x, y, width, height });
+    });
+    return Object.freeze({ ...dimensions, regions: Object.freeze(regions) });
+}
+export function readImageDerivation(raw) {
+    const value = exact(raw, ['method', 'sourceAttachmentId', 'source', 'plan'], 'Image derivation');
+    if (value.method !== 'png-regions-v1')
+        throw new TypeError('This image derivation method is unsupported.');
+    return Object.freeze({
+        method: value.method,
+        sourceAttachmentId: text(value.sourceAttachmentId, 'Source attachment ID', 128),
+        source: readRetainedFileReference(value.source),
+        plan: readImageRegionPlan(value.plan),
+    });
+}
+/** Opaque redactions are always last, including where annotations overlap them. */
+export function imageRegionPaintRectangles(raw) {
+    const plan = readImageRegionPlan(raw);
+    const result = [];
+    for (const region of plan.regions.filter(region => region.kind === 'outline')) {
+        const thickness = Math.min(3, region.width, region.height);
+        const { x, y, width, height } = region;
+        result.push({ x, y, width, height: thickness, colour: '#ffbf00' }, { x, y: y + height - thickness, width, height: thickness, colour: '#ffbf00' }, { x, y, width: thickness, height, colour: '#ffbf00' }, { x: x + width - thickness, y, width: thickness, height, colour: '#ffbf00' });
+    }
+    for (const region of plan.regions.filter(region => region.kind === 'redact')) {
+        result.push({ x: region.x, y: region.y, width: region.width, height: region.height, colour: '#000000' });
+    }
+    return result;
+}

package/packages/evidence/latest-observations.mjs

@@ -0,0 +1,28 @@
+import { normalizeExplicitIsoTimestamp } from "./observation.mjs";
+/** Select a time cohort from an already bounded source; never rank undated evidence as older. */
+export function latestObservationCohort(values, observedAt) {
+    let latestTime = null;
+    let latestMillis = -Infinity;
+    let latest = [];
+    const undated = [];
+    let superseded = 0;
+    for (const value of values) {
+        const time = normalizeExplicitIsoTimestamp(observedAt(value));
+        if (time === null) {
+            undated.push(value);
+            continue;
+        }
+        const millis = Date.parse(time);
+        if (millis > latestMillis) {
+            superseded += latest.length;
+            latestTime = time;
+            latestMillis = millis;
+            latest = [value];
+        }
+        else if (millis === latestMillis)
+            latest.push(value);
+        else
+            superseded += 1;
+    }
+    return { observedAt: latestTime, latest, undated, superseded };
+}

package/packages/evidence/lookup-target.mjs

@@ -0,0 +1,108 @@
+// Ordinary collection retains a hostname, not a pasted URL's private path or query.
+// Registration classification and network-address safety remain separate.
+import { isValidAsciiHostname } from "../contracts/domain-name.mjs";
+import { MAX_OUTBOUND_HTTP_URL_CHARACTERS } from "../contracts/http-url.mjs";
+export const MAX_LOOKUP_INPUT_CHARACTERS = 2 * 1024 * 1024;
+const URL_SCHEME = /^[a-z][a-z\d+.-]*:\/\//iu;
+const CONTROL = /[\u0000-\u001f\u007f]/u;
+/** Lexical recognition only; protocol, credentials and target admission remain separate. */
+export function hasLookupUrlScheme(value) {
+    return URL_SCHEME.test(value);
+}
+export function validWebObservationMode(value) {
+    return value === undefined || value === 'selected_url';
+}
+/** A separate deliberate action; ordinary URL input never selects its path. */
+export function prepareSelectedLookupUrl(value, hostname) {
+    if (typeof value !== 'string' || value.includes('\\'))
+        throw new TypeError('Select a valid HTTP(S) URL.');
+    const parsed = parseCredentialFreeHttpUrl(value, MAX_OUTBOUND_HTTP_URL_CHARACTERS);
+    if (!parsed || parsed.port || !isValidAsciiHostname(parsed.hostname)
+        || /^\d+\.\d+\.\d+\.\d+$/u.test(parsed.hostname)
+        || hostname !== undefined && parsed.hostname !== hostname) {
+        throw new TypeError('Selected URL must use the submitted hostname and a default HTTP(S) port, without credentials.');
+    }
+    parsed.hash = '';
+    const url = parsed.toString();
+    if (url.length > MAX_OUTBOUND_HTTP_URL_CHARACTERS)
+        throw new TypeError('Selected URL exceeds the request bound.');
+    return url;
+}
+/** Older results collected supporting evidence at the registrable domain. */
+export function lookupObservationHostname(availability) {
+    const value = availability.observationHostname === undefined ? availability.domain : availability.observationHostname;
+    return typeof value === 'string' && isValidAsciiHostname(value) && value === value.toLowerCase() ? value : null;
+}
+function validLookupObservationHostname(value, query) {
+    return typeof value === 'string' && isValidAsciiHostname(value) && value === value.toLowerCase()
+        && value === (query.inputHostname ?? query.submitted ?? query.registrableDomain)
+        && typeof query.registrableDomain === 'string'
+        && (value === query.registrableDomain || value.endsWith(`.${query.registrableDomain}`));
+}
+/** Bind collection identities without treating an omitted historical identity as new evidence. */
+export function validLookupObservationScope(availability, query) {
+    if (availability.observationHostname !== undefined && !validLookupObservationHostname(availability.observationHostname, query))
+        return false;
+    if (!validWebObservationMode(availability.webObservationMode))
+        return false;
+    if (availability.webObservationMode === 'selected_url') {
+        if (!validLookupObservationHostname(availability.observationHostname, query))
+            return false;
+        const http = availability.http;
+        const requestUrl = http && typeof http === 'object' && !Array.isArray(http) ? Reflect.get(http, 'requestUrl') : null;
+        const parsed = parseCredentialFreeHttpUrl(requestUrl, MAX_OUTBOUND_HTTP_URL_CHARACTERS);
+        if (!parsed || parsed.hostname !== availability.observationHostname || parsed.port || parsed.search || parsed.hash)
+            return false;
+    }
+    const dns = availability.dns;
+    const delegation = dns && typeof dns === 'object' && !Array.isArray(dns) ? Reflect.get(dns, 'delegation') : null;
+    const registrationDomain = delegation && typeof delegation === 'object' && !Array.isArray(delegation) ? Reflect.get(delegation, 'domain') : null;
+    return registrationDomain == null || (typeof registrationDomain === 'string'
+        && isValidAsciiHostname(registrationDomain) && registrationDomain === query.registrableDomain);
+}
+export function parseCredentialFreeHttpUrl(value, maximumLength) {
+    if (typeof value !== 'string' || !value || value.length > maximumLength
+        || value.trim() !== value || CONTROL.test(value))
+        return null;
+    try {
+        const parsed = new URL(value);
+        return (parsed.protocol === 'https:' || parsed.protocol === 'http:')
+            && !parsed.username && !parsed.password && parsed.hostname ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function prepareLookupCollectionTarget(value) {
+    if (value.length > MAX_LOOKUP_INPUT_CHARACTERS || CONTROL.test(value) || value.includes('\\')) {
+        throw new TypeError('Lookup input exceeds its bound or contains control characters.');
+    }
+    const raw = value.trim();
+    if (!raw)
+        throw new TypeError('Enter a domain, IP address or ASN.');
+    const absolute = hasLookupUrlScheme(raw);
+    // An unbracketed IPv6 literal is not a URL with a port. Use the same URL
+    // parser to admit its syntax, then leave address safety and ASN bounds to
+    // the classifier; malformed colon-separated text must not become a request.
+    if (!absolute && !/[\s/@?#\\]/u.test(raw)) {
+        if (/^(?:AS)?\d+$/iu.test(raw))
+            return raw;
+        if ((raw.match(/:/gu)?.length ?? 0) > 1 && !raw.startsWith('[')) {
+            if (!parseCredentialFreeHttpUrl(`https://[${raw}]`, MAX_LOOKUP_INPUT_CHARACTERS + 10)) {
+                throw new TypeError('Enter a valid IPv6 address without a scope identifier.');
+            }
+            return raw;
+        }
+    }
+    const parsed = parseCredentialFreeHttpUrl(absolute ? raw : `https://${raw}`, MAX_LOOKUP_INPUT_CHARACTERS + 'https://'.length);
+    if (!parsed)
+        throw new TypeError('Enter a valid domain, IP, or ASN. URLs must use HTTP(S) without credentials.');
+    if (/^\d+\.\d+\.\d+\.\d+$/u.test(parsed.hostname)) {
+        const authority = (absolute ? raw.slice(raw.indexOf('://') + 3) : raw).split(/[/?#]/u)[0];
+        const originalHost = authority.split(':')[0].replace(/\.$/u, '');
+        if (originalHost !== parsed.hostname)
+            throw new TypeError('Use a complete canonical IP address, not an abbreviated or encoded address.');
+    }
+    // WHATWG URLs bracket IPv6; the existing classifier accepts the bare address.
+    return parsed.hostname.replace(/^\[|\]$/gu, '').toLowerCase();
+}

package/packages/evidence/observation.mjs

@@ -68,6 +68,7 @@ const REGISTERED_DIAGNOSTIC_KEYS = [
     'discarded_relationships',
     'dmarc',
     'documentsParsed',
+    'eligibleAuthorityCount',
     'entities',
     'error',
     'externalScriptsSkipped',
@@ -96,13 +97,17 @@ const REGISTERED_DIAGNOSTIC_KEYS = [
     'objectsExamined',
     'observed',
     'observedAbsence',
+    'omittedAuthorityCount',
     'partialAuthorityCount',
     'passiveHeadersEvaluated',
     'potentialExposure',
     'ptr',
     'queriedAddressCount',
+    'queriedAuthorityCount',
     'redirectCount',
     'referencesExamined',
+    'referenceSignatureTimedOut',
+    'referenceSignatureUnavailable',
     'rejectedRows',
     'relationshipTagsExamined',
     'relationshipUrlsDiscarded',
@@ -238,6 +243,18 @@ function canonicalTimestamp(value, expression, assignUtcWhenMissing) {
 function normalizeExplicitIsoTimestamp(value) {
     return canonicalTimestamp(value, ISO_DATE_TIME_RE, false);
 }
+/** Retain a source's timestamp; missing, invalid or future times have no usable age. */
+function readObservationTime(value, now) {
+    const observedAt = normalizeExplicitIsoTimestamp(value);
+    const reviewedAt = normalizeExplicitIsoTimestamp(now);
+    const elapsed = observedAt && reviewedAt
+        ? Date.parse(reviewedAt) - Date.parse(observedAt)
+        : Number.NaN;
+    return {
+        observedAt,
+        ageDays: Number.isFinite(elapsed) && elapsed >= 0 ? Math.floor(elapsed / 86_400_000) : null,
+    };
+}
 // Frozen legacy schemas accepted zone-less ISO date-times. Preserve that
 // migration path deterministically by assigning UTC instead of consulting the
 // host timezone. Current schemas must use normalizeExplicitIsoTimestamp.
@@ -381,4 +398,4 @@ function readObservationEnvelope(value) {
     }
     return { state: 'supported', observation: createObservationFromSnapshot(record) };
 }
-export { MAX_OBSERVATION_DIAGNOSTICS, MAX_OBSERVATION_LIMITATIONS, MAX_OBSERVATION_LIMITATION_LENGTH, OBSERVATION_VERSION, createObservation, normalizeCtTimestamp, normalizeExplicitIsoTimestamp, normalizeLegacyIsoTimestamp, readObservationEnvelope, };
+export { MAX_OBSERVATION_DIAGNOSTICS, MAX_OBSERVATION_LIMITATIONS, MAX_OBSERVATION_LIMITATION_LENGTH, OBSERVATION_VERSION, createObservation, normalizeCtTimestamp, normalizeExplicitIsoTimestamp, normalizeLegacyIsoTimestamp, readObservationEnvelope, readObservationTime, };

package/packages/evidence/passphrase-encryption.mjs

@@ -0,0 +1,44 @@
+// Passphrase policy and native key derivation shared by portable encrypted files.
+import { MAX_WORKSPACE_ARCHIVE_PASSPHRASE_BYTES, MIN_WORKSPACE_ARCHIVE_PASSPHRASE_CHARACTERS, WORKSPACE_ARCHIVE_PBKDF2_ITERATIONS } from "../contracts/case-portability.mjs";
+export const AES_KEY_BITS = 256;
+const encoder = new TextEncoder();
+export function arrayBuffer(bytes) {
+    return new Uint8Array(bytes).buffer;
+}
+export function assertPassphrase(passphrase) {
+    if (typeof passphrase !== 'string') {
+        throw new Error(`Use a backup passphrase with at least ${MIN_WORKSPACE_ARCHIVE_PASSPHRASE_CHARACTERS} characters.`);
+    }
+    if (passphrase.length > MAX_WORKSPACE_ARCHIVE_PASSPHRASE_BYTES) {
+        throw new Error('Backup passphrases are limited to 1024 UTF-8 bytes.');
+    }
+    if (Array.from(passphrase).length < MIN_WORKSPACE_ARCHIVE_PASSPHRASE_CHARACTERS) {
+        throw new Error(`Use a backup passphrase with at least ${MIN_WORKSPACE_ARCHIVE_PASSPHRASE_CHARACTERS} characters.`);
+    }
+    const bytes = encoder.encode(passphrase);
+    if (bytes.byteLength > MAX_WORKSPACE_ARCHIVE_PASSPHRASE_BYTES) {
+        bytes.fill(0);
+        throw new Error('Backup passphrases are limited to 1024 UTF-8 bytes.');
+    }
+    return bytes;
+}
+export function cryptoProvider(provider = globalThis.crypto) {
+    if (!provider
+        || typeof provider.getRandomValues !== 'function'
+        || typeof provider.subtle?.importKey !== 'function'
+        || typeof provider.subtle?.deriveKey !== 'function'
+        || typeof provider.subtle?.encrypt !== 'function'
+        || typeof provider.subtle?.decrypt !== 'function') {
+        throw new Error('Encrypted workspace archives are unavailable in this browser.');
+    }
+    return provider;
+}
+export async function deriveArchiveKey(provider, passphraseBytes, salt, usages) {
+    const material = await provider.subtle.importKey('raw', arrayBuffer(passphraseBytes), 'PBKDF2', false, ['deriveKey']);
+    return provider.subtle.deriveKey({
+        name: 'PBKDF2',
+        hash: 'SHA-256',
+        salt: arrayBuffer(salt),
+        iterations: WORKSPACE_ARCHIVE_PBKDF2_ITERATIONS,
+    }, material, { name: 'AES-GCM', length: AES_KEY_BITS }, false, usages);
+}

package/packages/evidence/png-pixels.mjs

@@ -0,0 +1,117 @@
+import { decode, convertIndexedToRgb, hasPngSignature } from 'fast-png';
+import { Unzlib } from 'fflate';
+import { updateCrc32 } from "../interchange/crc32.mjs";
+import { readEvidenceImageDimensions } from "./image-regions.mjs";
+/** Admit PNG structure and inflated work before the image library allocates it. */
+export function decodeEvidencePng(bytes) {
+    if (!(bytes instanceof Uint8Array) || !(bytes.buffer instanceof ArrayBuffer) || !hasPngSignature(bytes) || bytes.byteLength < 33)
+        throw new TypeError('Select a valid PNG image.');
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    if (view.getUint32(8) !== 13 || String.fromCharCode(...bytes.subarray(12, 16)) !== 'IHDR')
+        throw new TypeError('The PNG header is malformed.');
+    const { width, height } = readEvidenceImageDimensions(view.getUint32(16), view.getUint32(20));
+    if (bytes[24] < 8 && bytes[28] !== 0)
+        throw new TypeError('Convert this interlaced low-bit-depth PNG to a non-interlaced image before review.');
+    const maximumInflatedBytes = width * height * 8 + height * 8 + 64;
+    let inflatedBytes = 0;
+    const inflater = new Unzlib(chunk => {
+        inflatedBytes += chunk.byteLength;
+        if (inflatedBytes > maximumInflatedBytes)
+            throw new TypeError('The PNG exceeds its dimension-derived decompression bound.');
+    });
+    const selected = [bytes.subarray(0, 8)];
+    let offset = 8, total = 8, ended = false, imageData = false, dataEnded = false, header = false, palette = false, transparency = false;
+    while (offset < bytes.byteLength) {
+        if (bytes.byteLength - offset < 12)
+            throw new TypeError('The PNG contains a truncated chunk.');
+        const length = view.getUint32(offset), end = offset + length + 12;
+        if (end > bytes.byteLength)
+            throw new TypeError('The PNG contains a truncated chunk.');
+        const kind = String.fromCharCode(...bytes.subarray(offset + 4, offset + 8));
+        if (!/^[A-Za-z]{4}$/u.test(kind))
+            throw new TypeError('The PNG contains an invalid chunk type.');
+        const crc = (updateCrc32(0xffff_ffff, bytes.subarray(offset + 4, end - 4)) ^ 0xffff_ffff) >>> 0;
+        if (crc !== view.getUint32(end - 4))
+            throw new TypeError('The PNG chunk checksum does not match.');
+        if (kind === 'acTL' || kind === 'fcTL' || kind === 'fdAT')
+            throw new TypeError('Select a still PNG image; animated frames are not silently omitted.');
+        if (kind === 'IHDR') {
+            if (header || offset !== 8 || length !== 13)
+                throw new TypeError('The PNG has conflicting headers.');
+            header = true;
+        }
+        else if (kind === 'PLTE') {
+            if (palette || imageData || !length || length > 768 || length % 3)
+                throw new TypeError('The PNG palette is malformed.');
+            palette = true;
+        }
+        else if (kind === 'tRNS') {
+            if (transparency || imageData || length > 256)
+                throw new TypeError('The PNG transparency data is malformed.');
+            transparency = true;
+        }
+        else if (kind === 'IDAT') {
+            if (dataEnded)
+                throw new TypeError('The PNG image-data chunks are not consecutive.');
+            imageData = true;
+            // A small compressed slice bounds transient inflation before the callback.
+            for (let position = offset + 8; position < end - 4; position += 1_024)
+                inflater.push(bytes.subarray(position, Math.min(position + 1_024, end - 4)), false);
+        }
+        else if (kind === 'IEND') {
+            if (length || !imageData || end !== bytes.byteLength)
+                throw new TypeError('The PNG trailer is malformed.');
+            ended = true;
+        }
+        else if (kind[0] === kind[0].toUpperCase())
+            throw new TypeError('The PNG has an unsupported critical chunk.');
+        if (imageData && kind !== 'IDAT')
+            dataEnded = true;
+        // Colour-profile and text metadata are irrelevant to QR pixel analysis and
+        // may contain independent compressed payloads. Never decode those payloads.
+        if (['IHDR', 'PLTE', 'tRNS', 'IDAT', 'IEND'].includes(kind)) {
+            const part = bytes.subarray(offset, end);
+            selected.push(part);
+            total += part.byteLength;
+        }
+        offset = end;
+    }
+    if (!ended)
+        throw new TypeError('The PNG trailer is missing.');
+    inflater.push(new Uint8Array(), true);
+    const admitted = new Uint8Array(total);
+    let position = 0;
+    for (const part of selected) {
+        admitted.set(part, position);
+        position += part.byteLength;
+    }
+    let image = decode(admitted, { checkCrc: true });
+    if (image.width !== width || image.height !== height)
+        throw new TypeError('The decoded PNG dimensions changed.');
+    if (image.depth < 8 && !image.palette && image.channels === 1) {
+        const maximum = (1 << image.depth) - 1;
+        // Use the library's packed-sample conversion for grayscale as well as
+        // indexed images; a generated grayscale palette does not parse new bytes.
+        image = { ...image, palette: Array.from({ length: maximum + 1 }, (_, value) => {
+                const grey = Math.round(value * 255 / maximum);
+                return [grey, grey, grey, image.transparency?.[0] === value ? 0 : 255];
+            }) };
+    }
+    const indexed = Boolean(image.palette), samples = indexed ? convertIndexedToRgb(image) : image.data;
+    const channels = indexed ? image.palette[0].length : image.channels;
+    if (![1, 2, 3, 4].includes(channels) || samples.length !== width * height * channels)
+        throw new TypeError('The PNG pixel layout is unsupported.');
+    const pixels = new Uint8ClampedArray(width * height * 4);
+    const sample = (index) => image.depth === 16 && !indexed ? Math.round(samples[index] / 257) : samples[index];
+    for (let index = 0; index < width * height; index++) {
+        const source = index * channels, target = index * 4;
+        pixels[target] = sample(source);
+        pixels[target + 1] = channels <= 2 ? sample(source) : sample(source + 1);
+        pixels[target + 2] = channels <= 2 ? sample(source) : sample(source + 2);
+        pixels[target + 3] = channels === 2 || channels === 4 ? sample(source + channels - 1) : 255;
+        if (!indexed && image.transparency && (channels === 1 ? samples[source] === image.transparency[0]
+            : channels === 3 && [0, 1, 2].every(channel => samples[source + channel] === image.transparency[channel])))
+            pixels[target + 3] = 0;
+    }
+    return { width, height, pixels };
+}

package/packages/evidence/public-address-policy.mjs

@@ -0,0 +1,83 @@
+// Browser-safe canonical public-address policy for analyst-supplied address
+// evidence. This performs no resolution or network work; transport owners must
+// still revalidate and pin addresses before making a request.
+import { ipv6Groups } from "../contracts/ip-address.mjs";
+const IPV4_RE = /^\d{1,3}(?:\.\d{1,3}){3}$/u;
+const IPV6_RE = /^[0-9a-f:]+$/iu;
+function canonicalIpv4(value) {
+    if (typeof value !== 'string' || !IPV4_RE.test(value.trim()))
+        return null;
+    const octets = value.trim().split('.').map(Number);
+    if (octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255))
+        return null;
+    return octets.join('.');
+}
+function isPublicIpv4(value) {
+    const octets = value.split('.').map(Number);
+    const [first = -1, second = -1, third = -1] = octets;
+    return octets.length === 4
+        && first !== 0
+        && first !== 10
+        && first !== 127
+        && first < 224
+        && !(first === 100 && second >= 64 && second <= 127)
+        && !(first === 169 && second === 254)
+        && !(first === 172 && second >= 16 && second <= 31)
+        && !(first === 192 && second === 168)
+        && !(first === 198 && (second === 18 || second === 19))
+        && !(first === 192 && second === 0 && third === 0)
+        && !(first === 192 && second === 0 && third === 2)
+        && !(first === 192 && second === 88 && third === 99)
+        && !(first === 198 && second === 51 && third === 100)
+        && !(first === 203 && second === 0 && third === 113);
+}
+function canonicalIpv6(value) {
+    if (typeof value !== 'string')
+        return null;
+    const candidate = value.trim().toLowerCase();
+    if (!candidate.includes(':') || candidate.includes('%') || candidate.includes('.') || !IPV6_RE.test(candidate)) {
+        return null;
+    }
+    try {
+        const host = new URL(`https://[${candidate}]/`).hostname;
+        return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isPublicIpv6(value) {
+    const groups = ipv6Groups(value);
+    if (groups.length !== 8)
+        return false;
+    const [first = '', second = '', third = ''] = groups;
+    if (groups.every((group) => group === '0000'))
+        return false;
+    if (groups.slice(0, 7).every((group) => group === '0000') && groups[7] === '0001')
+        return false;
+    if (first.startsWith('ff') || /^fe[89ab]/u.test(first) || /^fe[cdef]/u.test(first) || /^f[cd]/u.test(first))
+        return false;
+    if (first === '0100' && groups.slice(1, 4).every((group) => group === '0000'))
+        return false;
+    if (first === '2001' && second === '0db8')
+        return false;
+    if (first === '3fff' && Number.parseInt(second, 16) <= 0x0fff)
+        return false;
+    if (first === '2001' && second === '0002' && third === '0000')
+        return false;
+    if (first === '2001' && /^00[1-2][0-9a-f]$/u.test(second))
+        return false;
+    if (first === '2001' && second === '0000')
+        return false;
+    if (first === '2002')
+        return false;
+    const firstValue = Number.parseInt(first, 16);
+    return Number.isInteger(firstValue) && firstValue >= 0x2000 && firstValue <= 0x3fff;
+}
+export function canonicalPublicIpAddress(value) {
+    const ipv4 = canonicalIpv4(value);
+    if (ipv4)
+        return isPublicIpv4(ipv4) ? ipv4 : null;
+    const ipv6 = canonicalIpv6(value);
+    return ipv6 && isPublicIpv6(ipv6) ? ipv6 : null;
+}