create-principles-disciple 1.121.8 → 1.121.9

package/dist/update/transaction-journal.js

@@ -0,0 +1,333 @@
+/**
+ * Transaction journal and recovery (SPEC §8, §14.3).
+ *
+ * An update follows a persisted state machine:
+ *
+ *   planned -> downloaded -> verified -> staged -> probed
+ *           -> activated -> host_verified -> confirmed
+ *           -> rolled_back | refused | failed
+ *
+ * EVERY transition is appended (and fsynced) to the transaction journal
+ * BEFORE the side effect it describes. On restart, recovery reconciles any
+ * unfinished transaction: the outcome is always old-confirmed, new-confirmed,
+ * or an explicit safe refusal — never a hybrid.
+ */
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { writeRecordAtomically } from './atomic-file.js';
+export const TRANSACTION_STATES = [
+    'planned',
+    'downloaded',
+    'verified',
+    'staged',
+    'probed',
+    'activated',
+    'host_verified',
+    'confirmed',
+    'rolled_back',
+    'refused',
+    'failed',
+];
+export class TransactionJournalError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'TransactionJournalError';
+        this.code = code;
+    }
+}
+const VALID_STATES = new Set(TRANSACTION_STATES);
+const TERMINAL_STATES = new Set(['confirmed', 'rolled_back', 'refused', 'failed']);
+const ACTIVATION_OR_LATER = new Set(['activated', 'host_verified', 'confirmed']);
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseTransition(line, lineNumber) {
+    let parsed;
+    try {
+        parsed = JSON.parse(line);
+    }
+    catch {
+        throw new TransactionJournalError('journal_line_invalid', `Journal line ${lineNumber} is not valid JSON.`);
+    }
+    if (!isPlainObject(parsed)) {
+        throw new TransactionJournalError('journal_line_invalid', `Journal line ${lineNumber} is not an object.`);
+    }
+    const required = [
+        ['at', 'string'], ['to', 'string'], ['transactionId', 'string'],
+        ['releaseId', 'string'], ['productVersion', 'string'],
+        ['releaseMetadataDigest', 'string'], ['generation', 'number'],
+    ];
+    for (const [field, kind] of required) {
+        const value = Object.hasOwn(parsed, field) ? parsed[field] : undefined;
+        if (kind === 'string' && (typeof value !== 'string' || value.length === 0)) {
+            throw new TransactionJournalError('journal_field_invalid', `Journal line ${lineNumber}: field "${field}" must be a non-empty string.`);
+        }
+        if (kind === 'number' && (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)) {
+            throw new TransactionJournalError('journal_field_invalid', `Journal line ${lineNumber}: field "${field}" must be a positive integer.`);
+        }
+    }
+    const { to } = parsed;
+    if (typeof to !== 'string' || !VALID_STATES.has(to)) {
+        throw new TransactionJournalError('journal_state_invalid', `Journal line ${lineNumber}: unknown state ${JSON.stringify(to)}.`);
+    }
+    const fromValue = parsed.from;
+    if (fromValue !== null && (typeof fromValue !== 'string' || !VALID_STATES.has(fromValue))) {
+        throw new TransactionJournalError('journal_state_invalid', `Journal line ${lineNumber}: invalid from-state ${JSON.stringify(fromValue)}.`);
+    }
+    if (typeof parsed.releaseMetadataDigest !== 'string' || !/^[a-f0-9]{64}$/.test(parsed.releaseMetadataDigest)) {
+        throw new TransactionJournalError('journal_field_invalid', `Journal line ${lineNumber}: releaseMetadataDigest must be 64-char hex.`);
+    }
+    return {
+        at: parsed.at,
+        from: fromValue,
+        to: to,
+        transactionId: parsed.transactionId,
+        releaseId: parsed.releaseId,
+        productVersion: parsed.productVersion,
+        releaseMetadataDigest: parsed.releaseMetadataDigest,
+        generation: parsed.generation,
+        detail: typeof parsed.detail === 'string' ? parsed.detail : undefined,
+    };
+}
+function readJournalLines(journalPath, options) {
+    if (!existsSync(journalPath))
+        return { transitions: [], tornTailDetected: false };
+    const raw = readFileSync(journalPath, 'utf8');
+    const segments = raw.split('\n');
+    // A trailing '\n' makes split() yield a final empty segment; every other
+    // segment is a newline-terminated (complete) physical record.
+    const terminated = raw.endsWith('\n');
+    const completeLines = segments.slice(0, -1);
+    const trailingSegment = terminated ? '' : (segments[segments.length - 1] ?? '');
+    const transitions = [];
+    let lineNumber = 0;
+    for (const line of completeLines) {
+        lineNumber += 1;
+        if (line.trim().length === 0)
+            continue;
+        transitions.push(parseTransition(line, lineNumber));
+    }
+    let tornTailDetected = false;
+    if (trailingSegment.trim().length > 0) {
+        lineNumber += 1;
+        if (options.recoveryAware) {
+            try {
+                transitions.push(parseTransition(trailingSegment, lineNumber));
+            }
+            catch {
+                // Torn tail: unparseable, unterminated final record. Its transition
+                // never durably committed — drop it and flag for the recovery caller.
+                tornTailDetected = true;
+            }
+        }
+        else {
+            transitions.push(parseTransition(trailingSegment, lineNumber));
+        }
+    }
+    for (let index = 1; index < transitions.length; index += 1) {
+        const previous = transitions[index - 1];
+        const current = transitions[index];
+        if (!previous || !current)
+            continue;
+        if (previous.to !== current.from) {
+            throw new TransactionJournalError('journal_sequence_broken', `Journal transition ${index + 1} claims from=${JSON.stringify(current.from)} but the previous transition ended at ${JSON.stringify(previous.to)}.`);
+        }
+        if (TERMINAL_STATES.has(previous.to)) {
+            throw new TransactionJournalError('journal_terminal_continued', `Journal continues after the terminal state ${previous.to} at transition ${index + 1}.`);
+        }
+    }
+    return { transitions, tornTailDetected };
+}
+/** Reads and strictly validates the whole journal (fail loud on any tear). */
+export function readTransactionJournal(journalPath) {
+    return readJournalLines(journalPath, { recoveryAware: false }).transitions;
+}
+/**
+ * Recovery-aware journal reader (crash contract, SPEC §8).
+ *
+ * The writer appends `JSON + '\n'` and fsyncs. A crash mid-append can leave a
+ * TORN final record: unparseable JSON without a trailing newline. Such a
+ * record never durably committed, so recovery drops it. Everything else is
+ * strict: a malformed line anywhere else (including a complete-but-invalid
+ * final line that DOES end with a newline) fails loud, because a complete
+ * write with bad content is corruption, not a torn write.
+ */
+export function readTransactionJournalForRecovery(journalPath) {
+    return readJournalLines(journalPath, { recoveryAware: true });
+}
+/**
+ * Appends one transition durably (append + fsync) BEFORE the caller performs
+ * the side effect the transition describes. Journal-first ordering is what
+ * makes crash recovery sound.
+ */
+export function appendJournalTransition(journalPath, transition) {
+    const line = `${JSON.stringify(transition)}\n`;
+    const directory = dirname(journalPath);
+    mkdirSync(directory, { recursive: true });
+    let descriptor;
+    try {
+        descriptor = openSync(journalPath, 'a');
+        appendFileSync(descriptor, line);
+        fsyncSync(descriptor);
+    }
+    finally {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+    }
+}
+/** Serializes + atomically replaces active.json (see atomic-file adapter). */
+export function writeActiveRecord(recordPath, write) {
+    const record = { schemaVersion: 1, ...write };
+    writeRecordAtomically(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+}
+/** Strict active.json reader; returns null when absent. */
+export function readActiveRecord(recordPath) {
+    if (!existsSync(recordPath))
+        return null;
+    let text;
+    try {
+        text = readFileSync(recordPath, 'utf8');
+    }
+    catch (error) {
+        throw new TransactionJournalError('active_record_corrupt', `active.json could not be read (${recordPath}): ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch (error) {
+        // A bare SyntaxError here would escape every ReleaseManager reason
+        // contract; corrupt active state maps to its own stable code (rc-3/rc-9).
+        throw new TransactionJournalError('active_record_corrupt', `active.json is not valid JSON (${recordPath}): ${error instanceof Error ? error.message : String(error)}. Recovery must consult the transaction journal, never guess from a partial file.`);
+    }
+    if (!isPlainObject(value)) {
+        throw new TransactionJournalError('active_record_corrupt', `active.json is not an object: ${recordPath}`);
+    }
+    if (value.schemaVersion !== 1) {
+        throw new TransactionJournalError('active_record_corrupt', `active.json has unsupported schemaVersion: ${JSON.stringify(value.schemaVersion)}`);
+    }
+    const { generation } = value;
+    const { releaseId } = value;
+    const digest = value.releaseMetadataDigest;
+    const { previousReleaseId } = value;
+    const { transactionId } = value;
+    const { productVersion } = value;
+    if (typeof generation !== 'number' || !Number.isSafeInteger(generation) || generation < 1
+        || typeof releaseId !== 'string' || releaseId.length === 0
+        || typeof digest !== 'string' || !/^[a-f0-9]{64}$/.test(digest)
+        || (previousReleaseId !== null && (typeof previousReleaseId !== 'string' || previousReleaseId.length === 0))
+        || typeof transactionId !== 'string' || transactionId.length === 0
+        || typeof productVersion !== 'string' || productVersion.length === 0) {
+        throw new TransactionJournalError('active_record_corrupt', `active.json has malformed fields: ${recordPath}`);
+    }
+    return {
+        schemaVersion: 1,
+        generation,
+        releaseId,
+        releaseMetadataDigest: digest,
+        previousReleaseId,
+        transactionId,
+        productVersion,
+    };
+}
+/**
+ * Reconciles ONE transaction against the active record after a crash. The
+ * invariant: the result is old-confirmed, new-confirmed, or an explicit
+ * refusal — never a hybrid release (SPEC §18-4).
+ *
+ * Rules:
+ * - No journal activity for this transaction → nothing to reconcile.
+ * - Journal reached `confirmed` → new release stands.
+ * - Journal never reached `activated` → old release stands (nothing was
+ *   swapped); staging residue is cleaned up by the caller.
+ * - Journal reached `activated` (or later, unconfirmed) but active.json does
+ *   not carry this transaction's generation → the crash interrupted the
+ *   active-record write. The journal-confirmed PREVIOUS generation wins:
+ *   recovery re-points to it; a hybrid (new code, old pointer) is never
+ *   activated. If there is no previous pointer to fall back to, refuse
+ *   explicitly and demand the official installer.
+ */
+export function recoverUnfinishedTransaction(input) {
+    const { transitions, activeRecord, previousRecord, transactionId } = input;
+    const mine = transitions.filter((transition) => transition.transactionId === transactionId);
+    if (mine.length === 0) {
+        return { kind: 'old_confirmed', releaseId: null, generation: null, reason: 'no journal activity for this transaction' };
+    }
+    const last = mine[mine.length - 1];
+    if (last.to === 'confirmed') {
+        return {
+            kind: 'new_confirmed',
+            releaseId: last.releaseId,
+            generation: last.generation,
+            reason: 'journal already confirmed the new release',
+        };
+    }
+    if (last.to === 'rolled_back' || last.to === 'refused' || last.to === 'failed') {
+        return {
+            kind: 'old_confirmed',
+            releaseId: previousRecord?.releaseId ?? activeRecord?.releaseId ?? null,
+            generation: previousRecord?.generation ?? activeRecord?.generation ?? null,
+            reason: `transaction ended in ${last.to}; the previously confirmed release remains active`,
+        };
+    }
+    const reachedActivation = mine.some((transition) => ACTIVATION_OR_LATER.has(transition.to));
+    if (!reachedActivation) {
+        return {
+            kind: 'old_confirmed',
+            releaseId: previousRecord?.releaseId ?? activeRecord?.releaseId ?? null,
+            generation: previousRecord?.generation ?? activeRecord?.generation ?? null,
+            reason: 'activation was never journaled; no swap happened and staging can be discarded',
+        };
+    }
+    // Activation started. The active record decides which side of the swap
+    // actually landed, and its generation must match a journal transition.
+    const activeMatchesNew = activeRecord !== null
+        && activeRecord.transactionId === transactionId
+        && activeRecord.generation === last.generation
+        && activeRecord.releaseId === last.releaseId;
+    if (activeMatchesNew && last.to !== 'activated') {
+        // host_verified was journaled but confirmation didn't land — the active
+        // pointer plus the journal's activation lineage still close on the new
+        // generation; confirm it.
+        return {
+            kind: 'new_confirmed',
+            releaseId: activeRecord.releaseId,
+            generation: activeRecord.generation,
+            reason: 'active record matches the journaled activation lineage; completing confirmation',
+        };
+    }
+    if (activeMatchesNew && last.to === 'activated') {
+        // Pointer landed but host verification never ran: NOT confirmed. The
+        // previous confirmed generation is the safe answer when it exists.
+        if (previousRecord !== null) {
+            return {
+                kind: 'old_confirmed',
+                releaseId: previousRecord.releaseId,
+                generation: previousRecord.generation,
+                reason: 'activation pointer landed but the release was never host-verified; falling back to the previous confirmed generation',
+            };
+        }
+        return {
+            kind: 'explicit_refusal',
+            reason: 'activation_interrupted_without_previous',
+            nextAction: 'The first-ever activation was interrupted before host verification and there is no previously confirmed release to fall back to. Re-run the official installer to install a complete release.',
+        };
+    }
+    // Active record does not carry this transaction — the swap never landed.
+    const fallback = previousRecord ?? activeRecord;
+    if (fallback !== null) {
+        return {
+            kind: 'old_confirmed',
+            releaseId: fallback.releaseId,
+            generation: fallback.generation,
+            reason: 'the active record never took this transaction\'s generation; the previously confirmed release stands',
+        };
+    }
+    return {
+        kind: 'explicit_refusal',
+        reason: 'activation_interrupted_without_previous',
+        nextAction: 'Activation was interrupted before any confirmed generation existed. Re-run the official installer to install a complete release.',
+    };
+}
+//# sourceMappingURL=transaction-journal.js.map

package/dist/update/transaction-journal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-journal.js","sourceRoot":"","sources":["../../src/update/transaction-journal.ts"],"names":[],"mappings":"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"}

package/dist/update/trust-metadata.d.ts

@@ -0,0 +1,55 @@
+import { type Fetcher } from 'tuf-js';
+export type ReleaseTrustErrorCode = 'invalid_request' | 'metadata_refresh_failed' | 'target_not_found' | 'target_identity_mismatch' | 'target_integrity_missing';
+interface ReleaseTrustErrorOptions {
+    code: ReleaseTrustErrorCode;
+    message: string;
+    nextAction: string;
+    cause?: unknown;
+}
+export declare class ReleaseTrustError extends Error {
+    readonly code: ReleaseTrustErrorCode;
+    readonly nextAction: string;
+    constructor(options: ReleaseTrustErrorOptions);
+}
+export interface ResolveTrustedReleaseTargetOptions {
+    metadataDir: string;
+    metadataBaseUrl: string;
+    targetPath: string;
+    expectedChannel: string;
+    expectedPlatform: string;
+    fetcher?: Fetcher;
+}
+export interface TrustedReleaseTarget {
+    artifactSha256: string;
+    artifactSize: number;
+    channel: string;
+    platform: string;
+    releaseId: string;
+    targetPath: string;
+}
+/**
+ * Resolves a release target only after the official TUF client verifies the
+ * trusted-root → timestamp → snapshot → targets metadata chain.
+ *
+ * This module deliberately does not download or install the target. Phase 1
+ * uses it as an independently testable trust boundary before update execution
+ * is wired to the new release system.
+ */
+export declare function resolveTrustedReleaseTarget(options: ResolveTrustedReleaseTargetOptions): Promise<TrustedReleaseTarget>;
+export interface DownloadTrustedReleasePayloadOptions {
+    metadataDir: string;
+    metadataBaseUrl: string;
+    targetPath: string;
+    destinationPath: string;
+    fetcher?: Fetcher;
+}
+/**
+ * Downloads a trusted target to an exact destination path. The TUF client
+ * verifies length + digest DURING the download; a mismatch aborts and the
+ * partial file never reaches the destination. The destination is replaced
+ * atomically only after verification (temp file + rename in the same
+ * directory).
+ */
+export declare function downloadTrustedReleasePayload(options: DownloadTrustedReleasePayloadOptions): Promise<void>;
+export {};
+//# sourceMappingURL=trust-metadata.d.ts.map

package/dist/update/trust-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-metadata.d.ts","sourceRoot":"","sources":["../../src/update/trust-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,QAAQ,CAAC;AAE/C,MAAM,MAAM,qBAAqB,GAC7B,iBAAiB,GACjB,yBAAyB,GACzB,kBAAkB,GAClB,0BAA0B,GAC1B,0BAA0B,CAAC;AAE/B,UAAU,wBAAwB;IAChC,IAAI,EAAE,qBAAqB,CAAC;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY,OAAO,EAAE,wBAAwB,EAK5C;CACF;AAED,MAAM,WAAW,kCAAkC;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AA4CD;;;;;;;GAOG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,kCAAkC,GAC1C,OAAO,CAAC,oBAAoB,CAAC,CAoD/B;AAOD,MAAM,WAAW,oCAAoC;IACnD,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;GAMG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,oCAAoC,GAC5C,OAAO,CAAC,IAAI,CAAC,CAoDf"}

package/dist/update/trust-metadata.js

@@ -0,0 +1,170 @@
+import { Updater } from 'tuf-js';
+export class ReleaseTrustError extends Error {
+    code;
+    nextAction;
+    constructor(options) {
+        super(options.message, { cause: options.cause });
+        this.name = 'ReleaseTrustError';
+        this.code = options.code;
+        this.nextAction = options.nextAction;
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function hasRequiredOptions(options) {
+    return isNonEmptyString(options.metadataDir)
+        && isNonEmptyString(options.metadataBaseUrl)
+        && isNonEmptyString(options.targetPath)
+        && isNonEmptyString(options.expectedChannel)
+        && isNonEmptyString(options.expectedPlatform);
+}
+function readSignedIdentity(custom) {
+    const releaseId = Object.hasOwn(custom, 'releaseId') ? custom.releaseId : undefined;
+    const channel = Object.hasOwn(custom, 'channel') ? custom.channel : undefined;
+    const platform = Object.hasOwn(custom, 'platform') ? custom.platform : undefined;
+    if (!isNonEmptyString(releaseId) || !isNonEmptyString(channel) || !isNonEmptyString(platform)) {
+        throw new ReleaseTrustError({
+            code: 'target_identity_mismatch',
+            message: 'The signed target is missing a release ID, channel, or platform identity.',
+            nextAction: 'Do not install this release. Publish complete signed target metadata and retry.',
+        });
+    }
+    return { releaseId, channel, platform };
+}
+function readArtifactSha256(hashes) {
+    const sha256 = Object.hasOwn(hashes, 'sha256') ? hashes.sha256 : undefined;
+    if (typeof sha256 !== 'string' || !/^[a-f0-9]{64}$/i.test(sha256)) {
+        throw new ReleaseTrustError({
+            code: 'target_integrity_missing',
+            message: 'The signed target does not contain a valid SHA-256 artifact hash.',
+            nextAction: 'Do not install this release. Publish signed target metadata with a SHA-256 hash and retry.',
+        });
+    }
+    return sha256.toLowerCase();
+}
+/**
+ * Resolves a release target only after the official TUF client verifies the
+ * trusted-root → timestamp → snapshot → targets metadata chain.
+ *
+ * This module deliberately does not download or install the target. Phase 1
+ * uses it as an independently testable trust boundary before update execution
+ * is wired to the new release system.
+ */
+export async function resolveTrustedReleaseTarget(options) {
+    if (!hasRequiredOptions(options)) {
+        throw new ReleaseTrustError({
+            code: 'invalid_request',
+            message: 'Trusted release verification requires metadata storage, a repository URL, target path, channel, and platform.',
+            nextAction: 'Correct the release verification request before retrying.',
+        });
+    }
+    let target;
+    try {
+        const updater = new Updater({
+            metadataDir: options.metadataDir,
+            metadataBaseUrl: options.metadataBaseUrl,
+            fetcher: options.fetcher,
+        });
+        await updater.refresh();
+        target = await updater.getTargetInfo(options.targetPath);
+    }
+    catch (error) {
+        throw new ReleaseTrustError({
+            code: 'metadata_refresh_failed',
+            message: 'Release metadata could not be verified against the trusted root.',
+            nextAction: 'Do not install this release. Check the signed release repository and retry after the metadata issue is resolved.',
+            cause: error,
+        });
+    }
+    if (!target) {
+        throw new ReleaseTrustError({
+            code: 'target_not_found',
+            message: `No signed target exists for ${options.targetPath}.`,
+            nextAction: 'Do not install this release. Publish the target in signed metadata or select a supported channel and platform.',
+        });
+    }
+    const identity = readSignedIdentity(target.custom);
+    if (identity.channel !== options.expectedChannel || identity.platform !== options.expectedPlatform) {
+        throw new ReleaseTrustError({
+            code: 'target_identity_mismatch',
+            message: `The signed target identity (${identity.channel}/${identity.platform}) does not match the requested channel and platform (${options.expectedChannel}/${options.expectedPlatform}).`,
+            nextAction: 'Do not install this release. Select the matching signed channel and platform target.',
+        });
+    }
+    return {
+        artifactSha256: readArtifactSha256(target.hashes),
+        artifactSize: target.length,
+        channel: identity.channel,
+        platform: identity.platform,
+        releaseId: identity.releaseId,
+        targetPath: target.path,
+    };
+}
+function destinationDirOf(destinationPath) {
+    const lastSeparator = Math.max(destinationPath.lastIndexOf('/'), destinationPath.lastIndexOf('\\'));
+    return lastSeparator === -1 ? '.' : destinationPath.slice(0, lastSeparator);
+}
+/**
+ * Downloads a trusted target to an exact destination path. The TUF client
+ * verifies length + digest DURING the download; a mismatch aborts and the
+ * partial file never reaches the destination. The destination is replaced
+ * atomically only after verification (temp file + rename in the same
+ * directory).
+ */
+export async function downloadTrustedReleasePayload(options) {
+    for (const field of ['metadataDir', 'metadataBaseUrl', 'targetPath', 'destinationPath']) {
+        if (typeof options[field] !== 'string' || options[field].trim().length === 0) {
+            throw new ReleaseTrustError({
+                code: 'invalid_request',
+                message: `Trusted payload download requires ${field}.`,
+                nextAction: 'Correct the download request before retrying.',
+            });
+        }
+    }
+    let downloaded;
+    try {
+        const updater = new Updater({
+            metadataDir: options.metadataDir,
+            metadataBaseUrl: options.metadataBaseUrl,
+            targetBaseUrl: `${options.metadataBaseUrl.replace(/\/+$/, '')}/targets`,
+            fetcher: options.fetcher,
+        });
+        await updater.refresh();
+        const target = await updater.getTargetInfo(options.targetPath);
+        if (!target) {
+            throw new Error(`target not found: ${options.targetPath}`);
+        }
+        const destinationDirectory = destinationDirOf(options.destinationPath);
+        const { mkdirSync, renameSync, existsSync } = await import('node:fs');
+        const { join } = await import('node:path');
+        const { randomUUID } = await import('node:crypto');
+        mkdirSync(destinationDirectory, { recursive: true });
+        // UUID-named staging path: pid+timestamp collides when two downloads
+        // land in the same millisecond and the verifier would overwrite a
+        // concurrent verified payload.
+        const stagingPath = join(destinationDirectory, `.pd-payload-download-${randomUUID()}`);
+        downloaded = await updater.downloadTarget(target, stagingPath);
+        if (!existsSync(downloaded)) {
+            throw new Error(`verified download did not materialize: ${downloaded}`);
+        }
+        renameSync(downloaded, options.destinationPath);
+        downloaded = undefined;
+    }
+    catch (error) {
+        const causeMessage = error instanceof Error ? error.message : String(error);
+        throw new ReleaseTrustError({
+            code: 'metadata_refresh_failed',
+            message: `The trusted release payload could not be downloaded and verified (${options.targetPath}): ${causeMessage}`,
+            nextAction: 'Do not use this payload. Check the signed release repository and retry.',
+            cause: error,
+        });
+    }
+    finally {
+        if (downloaded !== undefined) {
+            const { rmSync } = await import('node:fs');
+            rmSync(downloaded, { force: true });
+        }
+    }
+}
+//# sourceMappingURL=trust-metadata.js.map

package/dist/update/trust-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-metadata.js","sourceRoot":"","sources":["../../src/update/trust-metadata.ts"],"names":[],"mappings":"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"}

package/dist/update/update-history.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Update history semantics (SPEC §12).
+ *
+ * History events use explicit kinds: update, reinstall, channel_promotion,
+ * legacy_migration, rollback, refusal, and recovery. Direction is DERIVED
+ * from canonical release identity and metadata sequence — never from
+ * package.json values found in a checkout. Every failed or refused event
+ * states what happened, whether the previous release remains active, and
+ * the safest next action.
+ */
+export type HistoryKind = 'update' | 'reinstall' | 'channel_promotion' | 'legacy_migration' | 'rollback' | 'refusal' | 'recovery';
+export type HistoryDirection = 'forward' | 'backward' | 'none';
+export type HistoryOutcome = 'succeeded' | 'refused' | 'failed' | 'recovered';
+export interface UpdateHistoryEvent {
+    readonly at: string;
+    readonly kind: HistoryKind;
+    readonly direction: HistoryDirection;
+    readonly outcome: HistoryOutcome;
+    readonly productVersion: string | null;
+    readonly releaseId: string | null;
+    readonly previousReleaseId: string | null;
+    /** True when the previously confirmed release is still the active one. */
+    readonly previousRemainsActive: boolean;
+    readonly reason: string | null;
+    readonly nextAction: string | null;
+    readonly transactionId: string | null;
+}
+export declare class UpdateHistoryError extends Error {
+    readonly field: string;
+    constructor(field: string, message: string);
+}
+/**
+ * Direction is derived from canonical publication sequences: forward when the
+ * event's release is newer than the previous one, backward when older,
+ * none for reinstall/refusal/unknown.
+ */
+export declare function classifyDirection(input: {
+    kind: HistoryKind;
+    releasePublicationSequence: number | null;
+    previousPublicationSequence: number | null;
+}): HistoryDirection;
+/** Appends one durable history event to `<pdHome>/logs/history.jsonl`. */
+export declare function appendHistoryEvent(historyFilePath: string, event: UpdateHistoryEvent): void;
+/** Strict reader for tests and the Console history surface. */
+export declare function readHistoryEvents(historyFilePath: string): UpdateHistoryEvent[];
+//# sourceMappingURL=update-history.d.ts.map

package/dist/update/update-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-history.d.ts","sourceRoot":"","sources":["../../src/update/update-history.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,WAAW,GACX,mBAAmB,GACnB,kBAAkB,GAClB,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;AAE/D,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,gBAAgB,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,0EAA0E;IAC1E,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB,YAAY,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIzC;CACF;AAgBD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,IAAI,EAAE,WAAW,CAAC;IAClB,0BAA0B,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1C,2BAA2B,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C,GAAG,gBAAgB,CAMnB;AAiBD,0EAA0E;AAC1E,wBAAgB,kBAAkB,CAAC,eAAe,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAU3F;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,eAAe,EAAE,MAAM,GAAG,kBAAkB,EAAE,CA6C/E"}