@slicedearth/whoisleuth-cli 2.3.0 → 2.4.0

package/packages/evidence/lookup-target.mjs

@@ -0,0 +1,104 @@
+// 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;
+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 = URL_SCHEME.test(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,11 +97,13 @@ const REGISTERED_DIAGNOSTIC_KEYS = [
     'objectsExamined',
     'observed',
     'observedAbsence',
+    'omittedAuthorityCount',
     'partialAuthorityCount',
     'passiveHeadersEvaluated',
     'potentialExposure',
     'ptr',
     'queriedAddressCount',
+    'queriedAuthorityCount',
     'redirectCount',
     'referencesExamined',
     'rejectedRows',
@@ -238,6 +241,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 +396,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/record-identity.mjs

@@ -0,0 +1,72 @@
+// Shared collision-resistant identities for bounded, already normalised records.
+// Platform cryptography remains the owner of signatures and authentication.
+export const MAX_IDENTITY_DIGEST_BYTES = 1024 * 1024;
+const SHA256_CONSTANTS = Object.freeze([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+function rotateRight(value, bits) {
+    return (value >>> bits) | (value << (32 - bits));
+}
+export function sha256IdentityHex(bytes) {
+    if (bytes.byteLength > MAX_IDENTITY_DIGEST_BYTES)
+        throw new RangeError('Record identity exceeds its byte limit.');
+    // This digest is a collision-resistant record identity, not a password,
+    // signature, MAC, or substitute for the platform cryptography used there.
+    const paddedLength = Math.ceil((bytes.byteLength + 9) / 64) * 64;
+    const padded = new Uint8Array(paddedLength);
+    padded.set(bytes);
+    padded[bytes.byteLength] = 0x80;
+    const view = new DataView(padded.buffer);
+    const bitLength = bytes.byteLength * 8;
+    view.setUint32(paddedLength - 8, Math.floor(bitLength / 0x1_0000_0000), false);
+    view.setUint32(paddedLength - 4, bitLength >>> 0, false);
+    const state = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
+        0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const words = new Uint32Array(64);
+    for (let offset = 0; offset < paddedLength; offset += 64) {
+        for (let index = 0; index < 16; index += 1)
+            words[index] = view.getUint32(offset + index * 4, false);
+        for (let index = 16; index < 64; index += 1) {
+            const left = words[index - 15];
+            const right = words[index - 2];
+            const sigma0 = rotateRight(left, 7) ^ rotateRight(left, 18) ^ (left >>> 3);
+            const sigma1 = rotateRight(right, 17) ^ rotateRight(right, 19) ^ (right >>> 10);
+            words[index] = (words[index - 16] + sigma0 + words[index - 7] + sigma1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = state;
+        for (let index = 0; index < 64; index += 1) {
+            const sum1 = rotateRight(e, 6) ^ rotateRight(e, 11) ^ rotateRight(e, 25);
+            const choice = (e & f) ^ (~e & g);
+            const first = (h + sum1 + choice + SHA256_CONSTANTS[index] + words[index]) >>> 0;
+            const sum0 = rotateRight(a, 2) ^ rotateRight(a, 13) ^ rotateRight(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const second = (sum0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + first) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (first + second) >>> 0;
+        }
+        state[0] = (state[0] + a) >>> 0;
+        state[1] = (state[1] + b) >>> 0;
+        state[2] = (state[2] + c) >>> 0;
+        state[3] = (state[3] + d) >>> 0;
+        state[4] = (state[4] + e) >>> 0;
+        state[5] = (state[5] + f) >>> 0;
+        state[6] = (state[6] + g) >>> 0;
+        state[7] = (state[7] + h) >>> 0;
+    }
+    return [...state].map((value) => value.toString(16).padStart(8, '0')).join('');
+}

package/packages/evidence/registry-dates.mjs

@@ -0,0 +1,190 @@
+// Cross-runtime deterministic normalization for lifecycle dates published by RDAP and
+// WHOIS services. Raw upstream strings remain the provenance source; these
+// helpers only produce additive Date/ISO companions for comparison, storage,
+// and presentation.
+const REGISTRY_MONTHS = Object.freeze({
+    jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6,
+    jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12,
+});
+const REGISTRY_MONTH_NAMES = Object.freeze({
+    january: 1, february: 2, march: 3, april: 4, may: 5, june: 6,
+    july: 7, august: 8, september: 9, october: 10, november: 11, december: 12,
+});
+function utcDateFromParts(year, month, day, hour = 0, minute = 0, second = 0, millisecond = 0) {
+    if (![year, month, day, hour, minute, second, millisecond].every(Number.isInteger))
+        return null;
+    if (year < 1000 || year > 9999 || month < 1 || month > 12 || day < 1
+        || hour < 0 || hour > 23 || minute < 0 || minute > 59
+        || second < 0 || second > 59 || millisecond < 0 || millisecond > 999)
+        return null;
+    const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second, millisecond));
+    if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day
+        || date.getUTCHours() !== hour || date.getUTCMinutes() !== minute
+        || date.getUTCSeconds() !== second || date.getUTCMilliseconds() !== millisecond)
+        return null;
+    return date;
+}
+// Parse the explicit non-ISO formats observed across supported ccTLD WHOIS
+// services before considering ISO-shaped input. Runtime Date parsing treats
+// dotted dates ambiguously and timezone-less timestamps in the host's local
+// timezone, so every accepted shape is validated and normalized through UTC.
+function parseRegistryDate(input) {
+    if (typeof input !== 'string')
+        return null;
+    // The documented .nz WHOIS examples place one space before the RFC3339
+    // `T` separator. Canonicalize that registry-specific presentation quirk
+    // before applying the existing strict ISO-shaped parser.
+    const value = input.trim()
+        .replace(/^(\d{4}-\d{2}-\d{2})[ ]+[Tt](?=\d{2}:)/, '$1T')
+        // The .ee WHOIS service separates an otherwise ISO-shaped numeric
+        // timezone from its clock with one space.
+        .replace(/^(\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?)[ ]+([+-]\d{2}:?\d{2})$/, '$1$2');
+    if (!value)
+        return null;
+    // DD.MM.YYYY[ HH:MM:SS] - e.g. 14.03.2024 10:46:48
+    let match = value.match(/^(\d{1,2})\.(\d{1,2})\.(\d{4})(?:\s+(\d{1,2}):(\d{2}):(\d{2}))?$/);
+    if (match) {
+        const [, day = '', month = '', year = '', hour = '0', minute = '0', second = '0'] = match;
+        return utcDateFromParts(+year, +month, +day, +(hour || 0), +(minute || 0), +(second || 0));
+    }
+    // YYYY. MM. DD. - e.g. 2006. 09. 18.
+    match = value.match(/^(\d{4})\.\s*(\d{1,2})\.\s*(\d{1,2})\.?$/);
+    if (match) {
+        const [, year = '', month = '', day = ''] = match;
+        return utcDateFromParts(+year, +month, +day);
+    }
+    // YYYY.MM.DD HH:MM:SS - used by NASK's .pl WHOIS service.
+    match = value.match(/^(\d{4})\.(\d{1,2})\.(\d{1,2})\s+(\d{1,2}):(\d{2}):(\d{2})$/);
+    if (match) {
+        const [, year = '', month = '', day = '', hour = '', minute = '', second = ''] = match;
+        return utcDateFromParts(+year, +month, +day, +hour, +minute, +second);
+    }
+    // YYYY/MM/DD - an unambiguous year-first form used by CIRA WHOIS.
+    match = value.match(/^(\d{4})\/(\d{1,2})\/(\d{1,2})$/);
+    if (match) {
+        const [, year = '', month = '', day = ''] = match;
+        return utcDateFromParts(+year, +month, +day);
+    }
+    // YYYYMMDD with an optional time or Registro.br contact-reference suffix.
+    // The raw value remains available as provenance while the validated date
+    // and optional clock time are projected into the additive ISO companion.
+    match = value.match(/^(\d{4})(\d{2})(\d{2})(?:\s+(\d{1,2}):(\d{2}):(\d{2})|\s+#[0-9]{1,20})?$/);
+    if (match) {
+        const [, year = '', month = '', day = '', hour = '0', minute = '0', second = '0'] = match;
+        return utcDateFromParts(+year, +month, +day, +(hour || 0), +(minute || 0), +(second || 0));
+    }
+    // YYYY-Mon-DD. - e.g. 1999-Feb-16.
+    match = value.match(/^(\d{4})-([A-Za-z]{3})-(\d{1,2})\.?$/);
+    if (match) {
+        const month = REGISTRY_MONTHS[(match[2] ?? '').toLowerCase()];
+        return month ? utcDateFromParts(+(match[1] ?? ''), month, +(match[3] ?? '')) : null;
+    }
+    // DD-Mon-YYYY[ HH:MM:SS] - used by several ICANN-style ccTLD services.
+    match = value.match(/^(\d{1,2})-([A-Za-z]{3})-(\d{4})(?:\s+(\d{1,2}):(\d{2}):(\d{2}))?$/);
+    if (match) {
+        const month = REGISTRY_MONTHS[(match[2] ?? '').toLowerCase()];
+        return month
+            ? utcDateFromParts(+(match[3] ?? ''), month, +(match[1] ?? ''), +(match[4] || 0), +(match[5] || 0), +(match[6] || 0))
+            : null;
+    }
+    // DD-MM-YYYY - the day-first form published by the currently profiled
+    // registries that use bare numeric hyphen dates. A future month-first
+    // source must receive its own marker-gated parser rather than reusing this
+    // global shape. The four-digit final year remains distinct from ISO below.
+    match = value.match(/^(\d{1,2})-(\d{1,2})-(\d{4})$/);
+    if (match) {
+        const [, day = '', month = '', year = ''] = match;
+        return utcDateFromParts(+year, +month, +day);
+    }
+    // YYYY-MM-DD HH:MM:SS (GMT+H:MM) - the explicit offset form published by
+    // the Kazakhstan registry. Parentheses and the GMT marker are required so
+    // unrelated prose is not accepted as a lifecycle timestamp.
+    match = value.match(/^(\d{4})-(\d{2})-(\d{2})\s+(\d{2}):(\d{2}):(\d{2})\s+\(GMT([+-])(\d{1,2}):(\d{2})\)$/i);
+    if (match) {
+        const [, year = '', month = '', day = '', hour = '', minute = '', second = '', sign = '', offsetHours = '', offsetMinutes = '',] = match;
+        const local = utcDateFromParts(+year, +month, +day, +hour, +minute, +second);
+        if (!local || +offsetHours > 23 || +offsetMinutes > 59)
+            return null;
+        const offsetMs = (+offsetHours * 60 + +offsetMinutes) * 60000;
+        return new Date(local.getTime() + (sign === '+' ? -offsetMs : offsetMs));
+    }
+    // DD-MM-YYYY HH:MM:SS GMT+H - the Tunisian registry's bounded local-time
+    // presentation. Accept an optional minute component but require the GMT
+    // marker and validate the calendar and offset before normalization.
+    match = value.match(/^(\d{1,2})-(\d{1,2})-(\d{4})\s+(\d{2}):(\d{2}):(\d{2})\s+GMT([+-])(\d{1,2})(?::(\d{2}))?$/i);
+    if (match) {
+        const [, day = '', month = '', year = '', hour = '', minute = '', second = '', sign = '', offsetHours = '', offsetMinutes = '0',] = match;
+        const local = utcDateFromParts(+year, +month, +day, +hour, +minute, +second);
+        if (!local || +offsetHours > 23 || +offsetMinutes > 59)
+            return null;
+        const offsetMs = (+offsetHours * 60 + +offsetMinutes) * 60000;
+        return new Date(local.getTime() + (sign === '+' ? -offsetMs : offsetMs));
+    }
+    // DD Mon YYYY - the compact English month form published by THNIC.
+    match = value.match(/^(\d{1,2})\s+([A-Za-z]{3})\s+(\d{4})$/);
+    if (match) {
+        const month = REGISTRY_MONTHS[(match[2] ?? '').toLowerCase()];
+        return month ? utcDateFromParts(+(match[3] ?? ''), month, +(match[1] ?? '')) : null;
+    }
+    // Ordinal-day Month YYYY[ at HH:MM:SS.sss] - the English form published
+    // by the Channel Islands registry. The suffix and `at` token are required
+    // so ordinary prose containing a month name is not accepted as lifecycle
+    // evidence.
+    match = value.match(/^(\d{1,2})(st|nd|rd|th)\s+([A-Za-z]{3,9})\s+(\d{4})(?:\s+at\s+(\d{1,2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?)?$/i);
+    if (match) {
+        const day = +(match[1] ?? '');
+        const suffix = (match[2] ?? '').toLowerCase();
+        const expectedSuffix = day % 100 >= 11 && day % 100 <= 13
+            ? 'th'
+            : ({ 1: 'st', 2: 'nd', 3: 'rd' }[day % 10] || 'th');
+        if (suffix !== expectedSuffix)
+            return null;
+        const monthText = (match[3] ?? '').toLowerCase();
+        const month = REGISTRY_MONTH_NAMES[monthText] || REGISTRY_MONTHS[monthText];
+        const millisecond = match[8] ? Number(`${match[8]}00`.slice(0, 3)) : 0;
+        return month
+            ? utcDateFromParts(+(match[4] ?? ''), month, day, +(match[5] || 0), +(match[6] || 0), +(match[7] || 0), millisecond)
+            : null;
+    }
+    // Ddd Mon DD YYYY[ HH:MM:SS] - the English textual form used by the
+    // Belgian registry. Weekday text is presentation-only; the validated
+    // calendar components determine the canonical UTC companion.
+    match = value.match(/^(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)\s+([A-Za-z]{3})\s+(\d{1,2})\s+(\d{4})(?:\s+(\d{1,2}):(\d{2}):(\d{2}))?$/i);
+    if (match) {
+        const month = REGISTRY_MONTHS[(match[1] ?? '').toLowerCase()];
+        return month
+            ? utcDateFromParts(+(match[3] ?? ''), month, +(match[2] ?? ''), +(match[4] || 0), +(match[5] || 0), +(match[6] || 0))
+            : null;
+    }
+    // Month DD YYYY - ISNIC publishes English month names with variable
+    // spacing and no timezone. Keep the accepted shape narrow and accept only
+    // the twelve exact English names from a fixed table.
+    match = value.match(/^([A-Za-z]{3,9})\s+(\d{1,2})\s+(\d{4})$/);
+    if (match) {
+        const month = REGISTRY_MONTH_NAMES[(match[1] ?? '').toLowerCase()];
+        return month ? utcDateFromParts(+(match[3] ?? ''), month, +(match[2] ?? '')) : null;
+    }
+    // ISO 8601-shaped dates and timestamps. A missing timezone is deliberately
+    // interpreted as UTC so Express and function deployments agree.
+    match = value.match(/^(\d{4})-(\d{2})-(\d{2})(?:[Tt ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(?:([Zz])|([+-])(\d{2}):?(\d{2}))?)?$/);
+    if (!match)
+        return null;
+    const [, year = '', month = '', day = '', hour = '0', minute = '0', second = '0', fraction, zulu, offsetSign, offsetHours = '0', offsetMinutes = '0',] = match;
+    const millisecond = fraction ? Number(`${fraction}000`.slice(0, 3)) : 0;
+    const local = utcDateFromParts(+year, +month, +day, +(hour || 0), +(minute || 0), +(second || 0), millisecond);
+    if (!local)
+        return null;
+    if (!offsetSign || zulu)
+        return local;
+    const offsetHour = +offsetHours;
+    const offsetMinute = +offsetMinutes;
+    if (offsetHour > 23 || offsetMinute > 59)
+        return null;
+    const offsetMs = (offsetHour * 60 + offsetMinute) * 60000;
+    return new Date(local.getTime() + (offsetSign === '+' ? -offsetMs : offsetMs));
+}
+function registryDateIso(value) {
+    const date = parseRegistryDate(value);
+    return date ? date.toISOString() : null;
+}
+export { parseRegistryDate, registryDateIso };

package/packages/evidence/retained-file.mjs

@@ -0,0 +1,69 @@
+import { MAX_SELECTED_FILES, MAX_SELECTED_FILE_BYTES, MAX_SELECTED_FILE_TOTAL_BYTES } from "../contracts/selected-file-limits.mjs";
+import { digest, exact, integer } from "./artifact-structure.mjs";
+import { sha256ArtifactBytes } from "./artifact-integrity.mjs";
+export function readRetainedFileReference(value) {
+    const record = exact(value, ['digestSha256', 'byteLength'], 'Retained file reference');
+    digest(record.digestSha256, 'Retained file digest');
+    const byteLength = integer(record.byteLength, 'Retained file bytes', 1, MAX_SELECTED_FILE_BYTES);
+    return Object.freeze({ digestSha256: record.digestSha256, byteLength });
+}
+/** Partition already bounded collection references without capping the entire workspace at one batch. */
+export function retainedFileGroups(references) {
+    const unique = new Map();
+    for (const item of references) {
+        const checked = readRetainedFileReference({ digestSha256: item.digestSha256, byteLength: item.byteLength });
+        const previous = unique.get(checked.digestSha256);
+        if (previous && previous.byteLength !== checked.byteLength)
+            throw new Error('File references have conflicting byte lengths.');
+        if (!previous)
+            unique.set(checked.digestSha256, item);
+    }
+    const groups = [];
+    let group = [], bytes = 0;
+    for (const item of unique.values()) {
+        if (group.length === MAX_SELECTED_FILES || item.byteLength > MAX_SELECTED_FILE_TOTAL_BYTES - bytes) {
+            groups.push(group);
+            group = [];
+            bytes = 0;
+        }
+        group.push(item);
+        bytes += item.byteLength;
+    }
+    if (group.length)
+        groups.push(group);
+    return groups;
+}
+/** Capture declarations synchronously; Blob contents are immutable. */
+export function captureRetainedFiles(input) {
+    if (!Array.isArray(input) || input.length > MAX_SELECTED_FILES)
+        throw new TypeError(`Select at most ${MAX_SELECTED_FILES} files per operation.`);
+    let total = 0;
+    return Object.freeze(input.map(item => {
+        const reference = readRetainedFileReference(item?.reference);
+        if (!(item.file instanceof Blob) || item.file.size !== reference.byteLength)
+            throw new TypeError('Selected file bytes do not match their declared length.');
+        total += reference.byteLength;
+        if (total > MAX_SELECTED_FILE_TOTAL_BYTES)
+            throw new TypeError('Selected files exceed the combined byte limit.');
+        return Object.freeze({ reference, file: item.file.slice() });
+    }));
+}
+/** Check the complete selected bytes, never a prefix or a canonicalised copy. */
+export async function readVerifiedRetainedFileBytes(reference, file) {
+    const expected = readRetainedFileReference(reference);
+    if (!(file instanceof Blob) || file.size !== expected.byteLength)
+        throw new TypeError('Retained file bytes do not match their declared length.');
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    try {
+        if (bytes.byteLength !== expected.byteLength || await sha256ArtifactBytes(bytes) !== expected.digestSha256)
+            throw new TypeError('Retained file bytes do not match their declared digest.');
+        return bytes;
+    }
+    catch (cause) {
+        bytes.fill(0);
+        throw cause;
+    }
+}
+export async function verifyRetainedFile(reference, file) {
+    (await readVerifiedRetainedFileBytes(reference, file)).fill(0);
+}

package/packages/evidence/review-age.mjs

@@ -0,0 +1,14 @@
+import { normalizeExplicitIsoTimestamp } from "./observation.mjs";
+export const ANALYST_REVIEW_AGING_AFTER_DAYS = 7;
+export const ANALYST_REVIEW_STALE_AFTER_DAYS = 30;
+export function analystReviewAgeAt(observedAt, now) {
+    const observed = normalizeExplicitIsoTimestamp(observedAt);
+    const reviewed = normalizeExplicitIsoTimestamp(now);
+    if (!observed || !reviewed)
+        return 'unknown';
+    const age = Date.parse(reviewed) - Date.parse(observed);
+    if (age < 0)
+        return 'unknown';
+    const days = age / 86_400_000;
+    return days > ANALYST_REVIEW_STALE_AFTER_DAYS ? 'stale' : days > ANALYST_REVIEW_AGING_AFTER_DAYS ? 'aging' : 'current';
+}