From d79ab1e41bffa65f5d7a59040a6ebf7407c4f5ee Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 09:56:37 +0000 Subject: [PATCH] feat(packaging): add TPK1 self-extracting payload format Installer payload appended to the setup program: JSON manifest (components, files with size/SHA-256/offsets/mtime, shortcuts, file types) plus deflate or stored entries and a 64-byte footer with the manifest hash. The reader finds the footer before an Authenticode table, validates every offset, rejects unsafe paths and bounds inflation by the declared size; the writer is deterministic, deduplicates identical content and strips a signed stub. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC --- src/Titano.Core/Packaging/PayloadException.cs | 21 ++ src/Titano.Core/Packaging/PayloadFormat.cs | 52 ++++ src/Titano.Core/Packaging/PayloadManifest.cs | 214 ++++++++++++++++ src/Titano.Core/Packaging/PayloadPath.cs | 68 +++++ src/Titano.Core/Packaging/PayloadReader.cs | 235 ++++++++++++++++++ src/Titano.Core/Packaging/PayloadWriter.cs | 225 +++++++++++++++++ src/Titano.Core/Packaging/PeImage.cs | 56 +++++ src/Titano.Core/Packaging/WindowStream.cs | 42 ++++ .../Packaging/PackagingFixture.cs | 130 ++++++++++ .../Packaging/PayloadIntegrityTests.cs | 213 ++++++++++++++++ .../Packaging/PayloadPathTests.cs | 60 +++++ .../Packaging/PayloadRoundTripTests.cs | 172 +++++++++++++ 12 files changed, 1488 insertions(+) create mode 100644 src/Titano.Core/Packaging/PayloadException.cs create mode 100644 src/Titano.Core/Packaging/PayloadFormat.cs create mode 100644 src/Titano.Core/Packaging/PayloadManifest.cs create mode 100644 src/Titano.Core/Packaging/PayloadPath.cs create mode 100644 src/Titano.Core/Packaging/PayloadReader.cs create mode 100644 src/Titano.Core/Packaging/PayloadWriter.cs create mode 100644 src/Titano.Core/Packaging/PeImage.cs create mode 100644 src/Titano.Core/Packaging/WindowStream.cs create mode 100644 tests/Titano.Core.Tests/Packaging/PackagingFixture.cs create mode 100644 tests/Titano.Core.Tests/Packaging/PayloadIntegrityTests.cs create mode 100644 tests/Titano.Core.Tests/Packaging/PayloadPathTests.cs create mode 100644 tests/Titano.Core.Tests/Packaging/PayloadRoundTripTests.cs diff --git a/src/Titano.Core/Packaging/PayloadException.cs b/src/Titano.Core/Packaging/PayloadException.cs new file mode 100644 index 00000000..ebe08039 --- /dev/null +++ b/src/Titano.Core/Packaging/PayloadException.cs @@ -0,0 +1,21 @@ +namespace Titano.Core.Packaging; + +/// Why a TPK1 payload could not be read, written or extracted. +public enum PayloadError +{ + /// The file carries no payload footer: not a packed installer, or its end was cut off. + NotFound, + + /// Footer, manifest or entry data are inconsistent, truncated or fail their SHA-256. + Corrupt, + + /// A path is absolute, escapes the target folder or uses a name Windows cannot store. + UnsafePath, +} + +/// A payload problem with a machine-readable for exit codes and UI messages. +public sealed class PayloadException(PayloadError error, string message, Exception? innerException = null) + : Exception(message, innerException) +{ + public PayloadError Error { get; } = error; +} diff --git a/src/Titano.Core/Packaging/PayloadFormat.cs b/src/Titano.Core/Packaging/PayloadFormat.cs new file mode 100644 index 00000000..a9d8d4f7 --- /dev/null +++ b/src/Titano.Core/Packaging/PayloadFormat.cs @@ -0,0 +1,52 @@ +using System.Buffers.Binary; + +namespace Titano.Core.Packaging; + +/// +/// The TPK1 self-extracting layout: [setup stub][manifest JSON][entry data][zero padding][footer], optionally +/// followed by an Authenticode certificate table that signtool appends when the installer is signed. +/// The footer is 64 bytes, little-endian: magic "TPK1END\0" · payload offset (int64, absolute offset of the +/// manifest) · manifest length (int64) · data length (int64) · SHA-256 of the manifest bytes (32 bytes). +/// Entry offsets in the manifest are relative to the first byte after the manifest. Padding aligns the end of the +/// footer to 8 bytes so a signature can be appended without signtool inserting bytes of its own. +/// +public static class PayloadFormat +{ + public const int FooterLength = 64; + public const int Alignment = 8; + public const int ManifestFormatVersion = 1; + + /// Upper bound for the manifest; a larger value in a footer means corruption. + public const int MaxManifestLength = 64 << 20; + + /// Deflate cannot expand data by more than about 1032:1; larger declared sizes are rejected up front. + public const int MaxDeflateRatio = 1032; + + public static ReadOnlySpan Magic => "TPK1END\0"u8; +} + +/// Decoded TPK1 footer. +internal readonly record struct PayloadFooter(long PayloadOffset, long ManifestLength, long DataLength, byte[] ManifestHash) +{ + public void WriteTo(Span destination) + { + PayloadFormat.Magic.CopyTo(destination); + BinaryPrimitives.WriteInt64LittleEndian(destination[8..], PayloadOffset); + BinaryPrimitives.WriteInt64LittleEndian(destination[16..], ManifestLength); + BinaryPrimitives.WriteInt64LittleEndian(destination[24..], DataLength); + ManifestHash.CopyTo(destination[32..]); + } + + /// Parses a footer; false when the magic does not match. + public static bool TryParse(ReadOnlySpan source, out PayloadFooter footer) + { + footer = default; + if (source.Length < PayloadFormat.FooterLength || !source[..8].SequenceEqual(PayloadFormat.Magic)) return false; + footer = new PayloadFooter( + BinaryPrimitives.ReadInt64LittleEndian(source[8..]), + BinaryPrimitives.ReadInt64LittleEndian(source[16..]), + BinaryPrimitives.ReadInt64LittleEndian(source[24..]), + source.Slice(32, 32).ToArray()); + return true; + } +} diff --git a/src/Titano.Core/Packaging/PayloadManifest.cs b/src/Titano.Core/Packaging/PayloadManifest.cs new file mode 100644 index 00000000..e4b304cc --- /dev/null +++ b/src/Titano.Core/Packaging/PayloadManifest.cs @@ -0,0 +1,214 @@ +using System.Diagnostics.CodeAnalysis; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Text.RegularExpressions; + +namespace Titano.Core.Packaging; + +/// How an entry's bytes are stored in the data region. +public enum PayloadCompression +{ + Stored, + Deflate, +} + +/// Describes everything a TPK1 installer carries: product, components, files, shortcuts and file types. +public sealed partial class PayloadManifest +{ + public int FormatVersion { get; init; } = PayloadFormat.ManifestFormatVersion; + public required string Product { get; init; } + public required string Version { get; init; } + public List Components { get; init; } = []; + public List Files { get; init; } = []; + public List Shortcuts { get; init; } = []; + public List Associations { get; init; } = []; + + /// The component with (ordinal, case-insensitive), or null. + public PayloadComponent? FindComponent(string id) => + Components.FirstOrDefault(c => c.Id.Equals(id, StringComparison.OrdinalIgnoreCase)); + + /// + /// Files installed by the given components, one entry per path in manifest order. A path shared by several + /// components (identical content, enforced by ) is listed once. + /// + public IReadOnlyList FilesFor(IEnumerable componentIds) + { + var selected = new HashSet(StringComparer.OrdinalIgnoreCase); + foreach (var id in componentIds) + { + var component = FindComponent(id) ?? throw new ArgumentException($"Unknown component '{id}'.", nameof(componentIds)); + selected.Add(component.Id); + } + var seen = new HashSet(PayloadPath.Comparer); + var result = new List(); + foreach (var file in Files) + { + if (selected.Contains(file.Component) && seen.Add(file.Path)) result.Add(file); + } + return result; + } + + /// Rejects manifests that are inconsistent with themselves or with a data region of bytes. + public void Validate(long dataLength) + { + if (FormatVersion != PayloadFormat.ManifestFormatVersion) Fail($"unsupported manifest format {FormatVersion}"); + if (!PayloadPath.IsValidSegment(Product) || Product.Length > 100) Fail("invalid product name"); + if (string.IsNullOrWhiteSpace(Version) || Version.Length > 64) Fail("invalid version"); + if (Components.Count == 0) Fail("no components"); + + var componentIds = new HashSet(StringComparer.OrdinalIgnoreCase); + foreach (var c in Components) + { + if (c is null || !IdentifierRegex().IsMatch(c.Id)) Fail("invalid component id"); + if (!componentIds.Add(c.Id)) Fail($"duplicate component {c.Id}"); + if (string.IsNullOrWhiteSpace(c.DisplayName) || c.DisplayName.Length > 100) Fail($"invalid display name for {c.Id}"); + if (c.EstimatedSize < 0) Fail($"negative size for {c.Id}"); + } + + var perComponent = new HashSet<(string, string)>(); + var byPath = new Dictionary(PayloadPath.Comparer); + foreach (var f in Files) + { + if (f is null) Fail("empty file entry"); + if (!PayloadPath.IsValid(f.Path)) throw new PayloadException(PayloadError.UnsafePath, $"Unsafe payload path '{f.Path}'."); + if (!componentIds.Contains(f.Component)) Fail($"{f.Path} belongs to an unknown component"); + if (!perComponent.Add((f.Component.ToUpperInvariant(), f.Path.ToUpperInvariant()))) Fail($"duplicate file {f.Path}"); + if (f.Size < 0 || f.Offset < 0 || f.Length < 0 || f.Offset > dataLength || f.Length > dataLength - f.Offset) + Fail($"{f.Path} lies outside the data region"); + if (!Sha256Regex().IsMatch(f.Sha256)) Fail($"{f.Path} has no valid SHA-256"); + switch (f.Compression) + { + case PayloadCompression.Stored when f.Length != f.Size: + Fail($"{f.Path}: stored length differs from size"); + break; + case PayloadCompression.Deflate when f.Size / PayloadFormat.MaxDeflateRatio > f.Length: + Fail($"{f.Path}: declared size exceeds the deflate limit"); + break; + case PayloadCompression.Stored or PayloadCompression.Deflate: + break; + default: + Fail($"{f.Path}: unknown compression"); + break; + } + if (byPath.TryGetValue(f.Path, out var other) && (other.Size != f.Size || !other.Sha256.Equals(f.Sha256, StringComparison.Ordinal))) + Fail($"{f.Path} differs between components {other.Component} and {f.Component}"); + byPath.TryAdd(f.Path, f); + } + + foreach (var s in Shortcuts) + { + if (s is null || !PayloadPath.IsValidSegment(s.Name)) Fail("invalid shortcut name"); + if (!OwnsFile(s.Component, s.Target)) Fail($"shortcut {s.Name} targets a file outside its component"); + } + + foreach (var a in Associations) + { + if (a is null || !ExtensionRegex().IsMatch(a.Extension)) Fail("invalid file extension"); + if (!ProgIdRegex().IsMatch(a.ProgId) || a.ProgId.Length > 39) Fail($"invalid ProgID for {a.Extension}"); + if (string.IsNullOrWhiteSpace(a.Description) || a.Description.Length > 100) Fail($"invalid description for {a.Extension}"); + if (!OwnsFile(a.Component, a.Target)) Fail($"{a.Extension} opens a file outside its component"); + } + + bool OwnsFile(string? component, string? path) => + component is not null && path is not null && perComponent.Contains((component.ToUpperInvariant(), path.ToUpperInvariant())); + } + + /// Serializes with a fixed property order and no whitespace, so identical inputs give identical bytes. + public byte[] ToJsonBytes() => JsonSerializer.SerializeToUtf8Bytes(this, PayloadJson.Default.PayloadManifest); + + /// Parses manifest bytes; malformed JSON is reported as . + public static PayloadManifest Parse(ReadOnlySpan json) + { + try + { + return JsonSerializer.Deserialize(json, PayloadJson.Default.PayloadManifest) + ?? throw new PayloadException(PayloadError.Corrupt, "The installer manifest is empty."); + } + catch (JsonException ex) + { + throw new PayloadException(PayloadError.Corrupt, "The installer manifest is not valid JSON.", ex); + } + } + + [DoesNotReturn] + private static void Fail(string reason) => throw new PayloadException(PayloadError.Corrupt, "Invalid installer manifest: " + reason + "."); + + [GeneratedRegex("^[A-Za-z][A-Za-z0-9]{0,63}$")] + internal static partial Regex IdentifierRegex(); + + [GeneratedRegex("^[0-9a-f]{64}$")] + private static partial Regex Sha256Regex(); + + [GeneratedRegex(@"^\.[A-Za-z0-9]{1,16}$")] + private static partial Regex ExtensionRegex(); + + [GeneratedRegex(@"^[A-Za-z][A-Za-z0-9]*(\.[A-Za-z0-9]+)+$")] + private static partial Regex ProgIdRegex(); +} + +/// A selectable part of the product (Titano, Uploader, Server). +public sealed class PayloadComponent +{ + public required string Id { get; init; } + public required string DisplayName { get; init; } + public bool DefaultSelected { get; init; } + + /// Installed size in bytes (sum of the component's files). + public long EstimatedSize { get; init; } +} + +/// One installed file and where its bytes live in the data region. +public sealed class PayloadFile +{ + /// Canonical relative path (). + public required string Path { get; init; } + public required string Component { get; init; } + public long Size { get; init; } + + /// Lower-case hex SHA-256 of the uncompressed content. + public required string Sha256 { get; init; } + public PayloadCompression Compression { get; init; } + + /// Offset of the stored bytes, relative to the start of the data region. + public long Offset { get; init; } + + /// Number of stored (possibly compressed) bytes. + public long Length { get; init; } + + /// Last write time, Unix epoch seconds (UTC). + public long ModifiedUnixSeconds { get; init; } +} + +/// A shortcut to one of a component's files, created in the Start menu and/or on the desktop. +public sealed class PayloadShortcut +{ + public required string Component { get; init; } + + /// File name of the shortcut without .lnk. + public required string Name { get; init; } + + /// Payload path of the program the shortcut opens. + public required string Target { get; init; } + public bool StartMenu { get; init; } + public bool Desktop { get; init; } +} + +/// A file type registered to open with one of a component's programs ("target" "%1"). +public sealed class PayloadAssociation +{ + public required string Component { get; init; } + + /// Extension including the dot, e.g. .titano. + public required string Extension { get; init; } + public required string ProgId { get; init; } + + /// File type name shown by Explorer. + public required string Description { get; init; } + + /// Payload path of the program that opens the file. + public required string Target { get; init; } +} + +[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, UseStringEnumConverter = true, RespectNullableAnnotations = true)] +[JsonSerializable(typeof(PayloadManifest))] +internal sealed partial class PayloadJson : JsonSerializerContext; diff --git a/src/Titano.Core/Packaging/PayloadPath.cs b/src/Titano.Core/Packaging/PayloadPath.cs new file mode 100644 index 00000000..45904c7f --- /dev/null +++ b/src/Titano.Core/Packaging/PayloadPath.cs @@ -0,0 +1,68 @@ +namespace Titano.Core.Packaging; + +/// +/// Canonical payload paths: relative, forward slashes, every segment a name Windows can store. Anything rooted, +/// drive-qualified, stream-qualified (a:b), containing ./.. or empty segments is rejected, so an +/// archive can never write outside the folder it is extracted into. +/// +public static class PayloadPath +{ + public const int MaxLength = 1024; + public const int MaxSegmentLength = 255; + + private static readonly HashSet ReservedNames = new(StringComparer.OrdinalIgnoreCase) + { + "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$", + "COM0", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", + "LPT0", "LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", + }; + + /// Path comparison used for payload paths: Windows file systems are case-insensitive. + public static StringComparer Comparer => StringComparer.OrdinalIgnoreCase; + + /// True when is a canonical, safe relative payload path. + public static bool IsValid(string? path) + { + if (string.IsNullOrEmpty(path) || path.Length > MaxLength) return false; + foreach (var segment in path.Split('/')) + { + if (!IsValidSegment(segment)) return false; + } + return true; + } + + /// True when is a single file or folder name Windows accepts verbatim. + public static bool IsValidSegment(string? name) + { + if (string.IsNullOrEmpty(name) || name.Length > MaxSegmentLength || name is "." or "..") return false; + foreach (var c in name) + { + if (c < 0x20 || c is '<' or '>' or ':' or '"' or '/' or '\\' or '|' or '?' or '*') return false; + } + // Windows silently strips trailing dots and spaces, which would alias two different names. + if (name[^1] is '.' or ' ') return false; + var dot = name.IndexOf('.', StringComparison.Ordinal); + var stem = (dot < 0 ? name : name[..dot]).TrimEnd(' '); + return !ReservedNames.Contains(stem); + } + + /// Converts a path relative to a source folder (either separator) into its canonical payload form. + public static string FromRelative(string relative) + { + var canonical = relative.Replace('\\', '/'); + if (!IsValid(canonical)) throw new PayloadException(PayloadError.UnsafePath, $"'{relative}' cannot be stored in an installer."); + return canonical; + } + + /// Full path of under ; throws when unsafe or outside the root. + public static string Resolve(string root, string relative) + { + if (!IsValid(relative)) throw new PayloadException(PayloadError.UnsafePath, $"Unsafe payload path '{relative}'."); + var fullRoot = Path.TrimEndingDirectorySeparator(Path.GetFullPath(root)); + var full = Path.GetFullPath(Path.Combine(fullRoot, relative.Replace('/', Path.DirectorySeparatorChar))); + var comparison = OperatingSystem.IsWindows() ? StringComparison.OrdinalIgnoreCase : StringComparison.Ordinal; + if (!full.StartsWith(fullRoot + Path.DirectorySeparatorChar, comparison)) + throw new PayloadException(PayloadError.UnsafePath, $"Payload path '{relative}' leaves the target folder."); + return full; + } +} diff --git a/src/Titano.Core/Packaging/PayloadReader.cs b/src/Titano.Core/Packaging/PayloadReader.cs new file mode 100644 index 00000000..05bb94f5 --- /dev/null +++ b/src/Titano.Core/Packaging/PayloadReader.cs @@ -0,0 +1,235 @@ +using System.Buffers; +using System.IO.Compression; +using System.Security.Cryptography; + +namespace Titano.Core.Packaging; + +/// Extraction progress: bytes written so far, total bytes, and the file being written. +public readonly record struct PayloadProgress(long Done, long Total, string CurrentPath); + +/// +/// Reads a TPK1 payload from the end of an installer. Opening validates the footer, the manifest SHA-256 and every +/// manifest offset; extraction verifies each file's SHA-256 and never writes more bytes than the manifest declares. +/// +public sealed class PayloadReader : IDisposable +{ + private const int BufferSize = 1 << 16; + private readonly FileStream _stream; + private readonly long _dataOffset; + + private PayloadReader(string path, FileStream stream) + { + ArchivePath = path; + _stream = stream; + var footerOffset = LocateFooter(stream, out var footer); + var (payloadOffset, manifestLength, dataLength) = (footer.PayloadOffset, footer.ManifestLength, footer.DataLength); + if (payloadOffset < 0 || manifestLength <= 0 || manifestLength > PayloadFormat.MaxManifestLength || dataLength < 0 + || payloadOffset > footerOffset || manifestLength > footerOffset - payloadOffset + || dataLength > footerOffset - payloadOffset - manifestLength) + throw Corrupt("The installer footer points outside the file."); + if (footerOffset - payloadOffset - manifestLength - dataLength >= PayloadFormat.Alignment) + throw Corrupt("The installer has unexpected bytes before its footer."); + + var manifestBytes = new byte[manifestLength]; + stream.Position = payloadOffset; + stream.ReadExactly(manifestBytes); + if (!SHA256.HashData(manifestBytes).AsSpan().SequenceEqual(footer.ManifestHash)) + throw Corrupt("The installer manifest does not match its SHA-256."); + + Manifest = PayloadManifest.Parse(manifestBytes); + Manifest.Validate(dataLength); + PayloadOffset = payloadOffset; + _dataOffset = payloadOffset + manifestLength; + } + + /// The installer file the payload was read from. + public string ArchivePath { get; } + + /// Absolute offset where the payload starts; the bytes before it are the setup program. + public long PayloadOffset { get; } + + public PayloadManifest Manifest { get; } + + /// Opens the payload appended to the running executable. + public static PayloadReader OpenCurrentProcess() => + Open(Environment.ProcessPath ?? throw new PayloadException(PayloadError.NotFound, "The setup program path is unknown.")); + + /// Opens and validates the payload of . + public static PayloadReader Open(string path) + { + FileStream stream; + try + { + stream = new FileStream(path, FileMode.Open, FileAccess.Read, FileShare.Read | FileShare.Delete, BufferSize, FileOptions.RandomAccess); + } + catch (Exception ex) when (ex is FileNotFoundException or DirectoryNotFoundException) + { + throw new PayloadException(PayloadError.NotFound, $"'{path}' does not exist.", ex); + } + try + { + return new PayloadReader(path, stream); + } + catch (IOException ex) + { + stream.Dispose(); + throw Corrupt("The installer could not be read to the end.", ex); + } + catch + { + stream.Dispose(); + throw; + } + } + + /// + /// Writes every file of under , verifying sizes and hashes. + /// The directory should be a fresh staging folder: on failure it holds partial output the caller discards. + /// + public void Extract(IReadOnlyList files, string directory, IProgress? progress = null, CancellationToken cancellationToken = default) + { + long total = 0; + foreach (var f in files) total += f.Size; + long done = 0; + var buffer = ArrayPool.Shared.Rent(BufferSize); + try + { + foreach (var file in files) + { + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new PayloadProgress(done, total, file.Path)); + var target = PayloadPath.Resolve(directory, file.Path); + Directory.CreateDirectory(Path.GetDirectoryName(target)!); + ExtractOne(file, target, buffer, ref done, total, progress, cancellationToken); + } + progress?.Report(new PayloadProgress(done, total, string.Empty)); + } + finally + { + ArrayPool.Shared.Return(buffer); + } + } + + /// + /// Writes the setup program alone: the bytes before the payload, with the signature directory cleared because + /// the installer's signature covered the payload as well. Used for the uninstaller copy. + /// + public void WriteStub(string destinationPath) + { + using var output = new FileStream(destinationPath, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, BufferSize); + _stream.Position = 0; + CopyExactly(_stream, output, PayloadOffset); + PeImage.ClearCertificateDirectory(output); + output.Flush(flushToDisk: true); + } + + public void Dispose() => _stream.Dispose(); + + private void ExtractOne(PayloadFile file, string target, byte[] buffer, ref long done, long total, IProgress? progress, CancellationToken cancellationToken) + { + using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256); + using (var output = new FileStream(target, FileMode.CreateNew, FileAccess.Write, FileShare.None, BufferSize)) + { + var window = new WindowStream(_stream, _dataOffset + file.Offset, file.Length); + using var input = file.Compression == PayloadCompression.Deflate ? new DeflateStream(window, CompressionMode.Decompress) : (Stream)window; + long written = 0; + var lastReport = 0L; + while (true) + { + cancellationToken.ThrowIfCancellationRequested(); + int read; + try + { + read = input.Read(buffer, 0, buffer.Length); + } + catch (InvalidDataException ex) + { + throw Corrupt($"'{file.Path}' is damaged in the installer.", ex); + } + if (read == 0) break; + // Never write past the declared size: a crafted entry cannot inflate beyond what the manifest promised. + if (read > file.Size - written) throw Corrupt($"'{file.Path}' is larger than the installer declares."); + output.Write(buffer, 0, read); + hash.AppendData(buffer, 0, read); + written += read; + done += read; + if (progress is not null && written - lastReport >= 4 << 20) + { + lastReport = written; + progress.Report(new PayloadProgress(done, total, file.Path)); + } + } + if (written != file.Size) throw Corrupt($"'{file.Path}' is shorter than the installer declares."); + output.Flush(flushToDisk: true); + } + if (!Convert.ToHexStringLower(hash.GetHashAndReset()).Equals(file.Sha256, StringComparison.Ordinal)) + throw Corrupt($"'{file.Path}' does not match its SHA-256."); + File.SetLastWriteTimeUtc(target, FromUnixSeconds(file.ModifiedUnixSeconds)); + } + + /// True when ends with a TPK1 footer (an installer must not become another one's stub). + internal static bool HasFooter(FileStream stream) + { + try + { + LocateFooter(stream, out _); + return true; + } + catch (PayloadException) + { + return false; + } + finally + { + stream.Position = 0; + } + } + + /// Finds the footer just before the end of the content (the file end, or the start of a signature). + private static long LocateFooter(FileStream stream, out PayloadFooter footer) + { + var end = PeImage.ContentEnd(stream); + if (end < PayloadFormat.FooterLength) throw new PayloadException(PayloadError.NotFound, "The file is too small to hold an installer payload."); + // signtool may zero-pad up to 7 bytes before the certificate table; the packer aligns, but accept either. + var tailLength = (int)Math.Min(end, PayloadFormat.FooterLength + PayloadFormat.Alignment - 1); + var tail = new byte[tailLength]; + stream.Position = end - tailLength; + stream.ReadExactly(tail); + for (var pad = 0; pad < PayloadFormat.Alignment && pad + PayloadFormat.FooterLength <= tailLength; pad++) + { + var start = tailLength - pad - PayloadFormat.FooterLength; + if (tail.AsSpan(tailLength - pad).ContainsAnyExcept((byte)0)) break; + if (PayloadFooter.TryParse(tail.AsSpan(start, PayloadFormat.FooterLength), out footer)) return end - pad - PayloadFormat.FooterLength; + } + throw new PayloadException(PayloadError.NotFound, "The file carries no installer payload."); + } + + private static void CopyExactly(Stream source, Stream destination, long count) + { + var buffer = ArrayPool.Shared.Rent(BufferSize); + try + { + while (count > 0) + { + var read = source.Read(buffer, 0, (int)Math.Min(buffer.Length, count)); + if (read == 0) throw Corrupt("The setup program is truncated."); + destination.Write(buffer, 0, read); + count -= read; + } + } + finally + { + ArrayPool.Shared.Return(buffer); + } + } + + private static DateTime FromUnixSeconds(long seconds) + { + // File times start in 1601; clamp to a range every file system accepts. + const long min = 315532800; // 1980-01-01 + const long max = 253402300799; // 9999-12-31 + return DateTime.UnixEpoch.AddSeconds(Math.Clamp(seconds, min, max)); + } + + private static PayloadException Corrupt(string message, Exception? inner = null) => new(PayloadError.Corrupt, message, inner); +} diff --git a/src/Titano.Core/Packaging/PayloadWriter.cs b/src/Titano.Core/Packaging/PayloadWriter.cs new file mode 100644 index 00000000..65d7db84 --- /dev/null +++ b/src/Titano.Core/Packaging/PayloadWriter.cs @@ -0,0 +1,225 @@ +using System.Buffers; +using System.IO.Compression; +using System.Security.Cryptography; +using Titano.Core.IO; + +namespace Titano.Core.Packaging; + +/// A component to pack: its manifest identity and the folder whose whole tree it installs. +public sealed record PayloadComponentSource(string Id, string DisplayName, bool DefaultSelected, string Folder); + +/// Everything the packer needs besides the setup program. +public sealed class PayloadSource +{ + public required string Product { get; init; } + public required string Version { get; init; } + public IReadOnlyList Components { get; init; } = []; + public IReadOnlyList Shortcuts { get; init; } = []; + public IReadOnlyList Associations { get; init; } = []; +} + +/// Sizes of a written installer. +public sealed record PayloadWriteResult(long InstallerBytes, long PayloadBytes, long InstalledBytes, int FileCount); + +/// +/// Builds a self-extracting installer: the setup program followed by a TPK1 payload (). +/// Output is deterministic: files are ordered by component then ordinal path, the manifest has a fixed shape, +/// and identical content is stored once. +/// +public static class PayloadWriter +{ + private const int BufferSize = 1 << 16; + private static readonly string EmptySha256 = Convert.ToHexStringLower(SHA256.HashData([])); + + /// Packs after into (written atomically). + public static PayloadWriteResult Write(string stubPath, PayloadSource source, string outputPath, IProgress? progress = null, CancellationToken cancellationToken = default) + { + var output = Path.GetFullPath(outputPath); + var inputs = Enumerate(source, output); + long total = 0; + foreach (var input in inputs) total += new FileInfo(input.FullPath).Length; + + var spoolPath = output + "." + Guid.NewGuid().ToString("N")[..8] + ".spool"; + using var spool = new FileStream(spoolPath, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, BufferSize, FileOptions.DeleteOnClose); + var files = Spool(inputs, spool, total, progress, cancellationToken); + + var components = source.Components.Select(c => new PayloadComponent + { + Id = c.Id, + DisplayName = c.DisplayName, + DefaultSelected = c.DefaultSelected, + EstimatedSize = files.Where(f => f.Component == c.Id).Sum(f => f.Size), + }).ToList(); + var manifest = new PayloadManifest + { + Product = source.Product, + Version = source.Version, + Components = components, + Files = files, + Shortcuts = [.. source.Shortcuts], + Associations = [.. source.Associations], + }; + manifest.Validate(spool.Length); + var manifestBytes = manifest.ToJsonBytes(); + + var temp = AtomicFile.TempPathFor(output); + long installerLength; + try + { + using (var installer = new FileStream(temp, FileMode.CreateNew, FileAccess.ReadWrite, FileShare.None, BufferSize)) + { + var payloadOffset = WriteStub(stubPath, installer); + installer.Write(manifestBytes); + spool.Position = 0; + spool.CopyTo(installer, BufferSize); + installer.Write(new byte[(PayloadFormat.Alignment - installer.Position % PayloadFormat.Alignment) % PayloadFormat.Alignment]); + Span footer = stackalloc byte[PayloadFormat.FooterLength]; + new PayloadFooter(payloadOffset, manifestBytes.Length, spool.Length, SHA256.HashData(manifestBytes)).WriteTo(footer); + installer.Write(footer); + installerLength = installer.Length; + } + AtomicFile.Commit(temp, output); + } + catch + { + if (File.Exists(temp)) File.Delete(temp); + throw; + } + + return new PayloadWriteResult(installerLength, manifestBytes.Length + spool.Length, components.Sum(c => c.EstimatedSize), files.Count); + } + + private sealed record Input(string Component, string Path, string FullPath); + + private static List Enumerate(PayloadSource source, string output) + { + var options = new EnumerationOptions { RecurseSubdirectories = true, AttributesToSkip = 0, IgnoreInaccessible = false }; + var inputs = new List(); + foreach (var component in source.Components) + { + var root = Path.TrimEndingDirectorySeparator(Path.GetFullPath(component.Folder)); + if (!Directory.Exists(root)) throw new DirectoryNotFoundException($"Component folder '{component.Folder}' does not exist."); + if (output.StartsWith(root + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase)) + throw new ArgumentException($"The installer cannot be written inside the component folder '{component.Folder}'.", nameof(output)); + inputs.AddRange(Directory.EnumerateFiles(root, "*", options) + .Select(f => new Input(component.Id, PayloadPath.FromRelative(Path.GetRelativePath(root, f)), f)) + .OrderBy(i => i.Path, StringComparer.Ordinal)); + } + return inputs; + } + + /// Compresses every input into the spool, storing each distinct content once. + private static List Spool(List inputs, FileStream spool, long total, IProgress? progress, CancellationToken cancellationToken) + { + var blobs = new Dictionary(StringComparer.Ordinal); + var files = new List(inputs.Count); + var buffer = ArrayPool.Shared.Rent(BufferSize); + long done = 0; + try + { + foreach (var input in inputs) + { + cancellationToken.ThrowIfCancellationRequested(); + progress?.Report(new PayloadProgress(done, total, input.Path)); + var start = spool.Position; + long size = 0; + using var hash = IncrementalHash.CreateHash(HashAlgorithmName.SHA256); + using (var file = new FileStream(input.FullPath, FileMode.Open, FileAccess.Read, FileShare.Read, BufferSize, FileOptions.SequentialScan)) + using (var deflate = new DeflateStream(spool, CompressionLevel.Optimal, leaveOpen: true)) + { + int read; + while ((read = file.Read(buffer, 0, buffer.Length)) > 0) + { + cancellationToken.ThrowIfCancellationRequested(); + hash.AppendData(buffer, 0, read); + deflate.Write(buffer, 0, read); + size += read; + } + } + done += size; + var sha = size == 0 ? EmptySha256 : Convert.ToHexStringLower(hash.GetHashAndReset()); + + (long Offset, long Length, PayloadCompression Compression) blob; + if (size == 0) + { + Rewind(spool, start); + blob = (0, 0, PayloadCompression.Stored); + } + else if (blobs.TryGetValue(sha, out var existing)) + { + Rewind(spool, start); + blob = existing; + } + else if (spool.Position - start >= size) + { + // Incompressible content (already compressed media, signed binaries): store it verbatim. + Rewind(spool, start); + using (var file = new FileStream(input.FullPath, FileMode.Open, FileAccess.Read, FileShare.Read, BufferSize, FileOptions.SequentialScan)) + CopyExactly(file, spool, size, buffer); + blob = blobs[sha] = (start, size, PayloadCompression.Stored); + } + else + { + blob = blobs[sha] = (start, spool.Position - start, PayloadCompression.Deflate); + } + + files.Add(new PayloadFile + { + Path = input.Path, + Component = input.Component, + Size = size, + Sha256 = sha, + Compression = blob.Compression, + Offset = blob.Offset, + Length = blob.Length, + ModifiedUnixSeconds = new DateTimeOffset(File.GetLastWriteTimeUtc(input.FullPath)).ToUnixTimeSeconds(), + }); + } + progress?.Report(new PayloadProgress(done, Math.Max(total, done), string.Empty)); + } + finally + { + ArrayPool.Shared.Return(buffer); + } + return files; + } + + /// Copies the setup program, dropping an Authenticode table (the installer is signed as a whole later). + private static long WriteStub(string stubPath, FileStream installer) + { + using (var stub = new FileStream(stubPath, FileMode.Open, FileAccess.Read, FileShare.Read, BufferSize)) + { + if (PayloadReader.HasFooter(stub)) throw new ArgumentException($"'{stubPath}' already carries a payload; use the plain setup program.", nameof(stubPath)); + var buffer = ArrayPool.Shared.Rent(BufferSize); + try + { + CopyExactly(stub, installer, PeImage.ContentEnd(stub), buffer); + } + finally + { + ArrayPool.Shared.Return(buffer); + } + } + PeImage.ClearCertificateDirectory(installer); + installer.Seek(0, SeekOrigin.End); + return installer.Position; + } + + private static void Rewind(FileStream spool, long position) + { + spool.SetLength(position); + spool.Position = position; + } + + private static void CopyExactly(Stream source, Stream destination, long count, byte[] buffer) + { + source.Position = 0; + while (count > 0) + { + var read = source.Read(buffer, 0, (int)Math.Min(buffer.Length, count)); + if (read == 0) throw new IOException("The file changed while it was being packed."); + destination.Write(buffer, 0, read); + count -= read; + } + } +} diff --git a/src/Titano.Core/Packaging/PeImage.cs b/src/Titano.Core/Packaging/PeImage.cs new file mode 100644 index 00000000..a42f41df --- /dev/null +++ b/src/Titano.Core/Packaging/PeImage.cs @@ -0,0 +1,56 @@ +using System.Reflection.PortableExecutable; + +namespace Titano.Core.Packaging; + +/// +/// The Authenticode certificate table of a PE file. signtool appends it at the end of the file and points the +/// security data directory at it (a file offset, not an RVA). The payload footer therefore ends where the table +/// starts, and a signed stub must lose its table before a payload is appended (the installer is signed as a whole). +/// +internal readonly record struct PeImage(long CertificateOffset, long CertificateSize, long DirectoryEntryOffset) +{ + private const int SecurityDirectoryIndex = 4; + + public bool IsSigned => CertificateSize > 0; + + /// Reads the PE headers at the start of ; null when it is not a PE file. + public static PeImage? TryRead(Stream stream) + { + stream.Position = 0; + try + { + var headers = new PEHeaders(stream, (int)Math.Min(stream.Length, int.MaxValue)); + if (headers.PEHeader is not { } pe || pe.NumberOfRvaAndSizes <= SecurityDirectoryIndex) return new PeImage(0, 0, -1); + // Data directories follow the fixed optional-header fields: 96 bytes in PE32, 112 in PE32+. + var directories = headers.PEHeaderStartOffset + (pe.Magic == PEMagic.PE32Plus ? 112 : 96); + var table = pe.CertificateTableDirectory; + return new PeImage(table.RelativeVirtualAddress, table.Size, directories + SecurityDirectoryIndex * 8); + } + catch (BadImageFormatException) + { + return null; + } + finally + { + stream.Position = 0; + } + } + + /// Where meaningful content ends: the certificate table when one sits inside the file, else the file end. + public static long ContentEnd(Stream stream) + { + var image = TryRead(stream); + return image is { IsSigned: true } pe && pe.CertificateOffset > 0 && pe.CertificateOffset + pe.CertificateSize <= stream.Length + ? pe.CertificateOffset + : stream.Length; + } + + /// Clears the security directory entry so the file no longer claims a signature. + public static void ClearCertificateDirectory(Stream stream) + { + if (TryRead(stream) is not { DirectoryEntryOffset: >= 0 } pe || !pe.IsSigned) return; + stream.Position = pe.DirectoryEntryOffset; + stream.Write(stackalloc byte[8]); + stream.Position = 0; + } +} diff --git a/src/Titano.Core/Packaging/WindowStream.cs b/src/Titano.Core/Packaging/WindowStream.cs new file mode 100644 index 00000000..42a3ff45 --- /dev/null +++ b/src/Titano.Core/Packaging/WindowStream.cs @@ -0,0 +1,42 @@ +namespace Titano.Core.Packaging; + +/// Read-only view of [offset, offset + length) of a seekable stream; reads never cross the window. +internal sealed class WindowStream(Stream inner, long offset, long length) : Stream +{ + private long _position; + + public override bool CanRead => true; + public override bool CanSeek => false; + public override bool CanWrite => false; + public override long Length => length; + + public override long Position + { + get => _position; + set => throw new NotSupportedException(); + } + + public override int Read(byte[] buffer, int offset, int count) => Read(buffer.AsSpan(offset, count)); + + public override int Read(Span buffer) + { + var remaining = length - _position; + if (remaining <= 0 || buffer.IsEmpty) return 0; + if (buffer.Length > remaining) buffer = buffer[..(int)remaining]; + inner.Position = offset + _position; + var read = inner.Read(buffer); + if (read == 0) throw new PayloadException(PayloadError.Corrupt, "The installer ends inside a file entry."); + _position += read; + return read; + } + + public override void Flush() + { + } + + public override long Seek(long offset, SeekOrigin origin) => throw new NotSupportedException(); + + public override void SetLength(long value) => throw new NotSupportedException(); + + public override void Write(byte[] buffer, int offset, int count) => throw new NotSupportedException(); +} diff --git a/tests/Titano.Core.Tests/Packaging/PackagingFixture.cs b/tests/Titano.Core.Tests/Packaging/PackagingFixture.cs new file mode 100644 index 00000000..94109aee --- /dev/null +++ b/tests/Titano.Core.Tests/Packaging/PackagingFixture.cs @@ -0,0 +1,130 @@ +using System.Buffers.Binary; +using System.Security.Cryptography; +using System.Text; +using Titano.Core.Packaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Packaging; + +/// Synthetic stubs, component trees and hand-made installers for the packaging tests. +internal sealed class PackagingFixture(TestContext context) +{ + public static readonly DateTime FixedTime = new(2026, 3, 14, 15, 9, 26, DateTimeKind.Utc); + + private static readonly byte[] CraftStub = [(byte)'M', (byte)'Z', 1, 2, 3, 4, 5, 6, 7, 8, 9]; + + public string Root { get; } = context.CreateTempDirectory("packaging"); + + /// A setup "program": any bytes work, the format does not interpret the stub unless it is a PE. + public string Stub(int length = 4096) + { + var path = Path.Combine(Root, "Titano.Setup.exe"); + var bytes = new byte[length]; + new Random(7).NextBytes(bytes); + "MZ"u8.CopyTo(bytes); + File.WriteAllBytes(path, bytes); + return path; + } + + /// Creates (payload path → content) under a new folder with a fixed mtime. + public string Folder(string name, params (string Path, byte[] Content)[] files) + { + var dir = Path.Combine(Root, name); + Directory.CreateDirectory(dir); + foreach (var (relative, content) in files) + { + var path = Path.Combine(dir, relative.Replace('/', Path.DirectorySeparatorChar)); + Directory.CreateDirectory(Path.GetDirectoryName(path)!); + File.WriteAllBytes(path, content); + File.SetLastWriteTimeUtc(path, FixedTime); + } + return dir; + } + + public static byte[] Text(string s, int repeat = 1) => Encoding.UTF8.GetBytes(string.Concat(Enumerable.Repeat(s, repeat))); + + public static byte[] Random(int length, int seed) + { + var bytes = new byte[length]; + new Random(seed).NextBytes(bytes); + return bytes; + } + + public static PayloadSource Source(params PayloadComponentSource[] components) => new() + { + Product = "Titano", + Version = "1.2.3", + Components = components, + }; + + public string Pack(string stub, PayloadSource source, string name = "Titano-Setup.exe") + { + var output = Path.Combine(Root, "out", name); + Directory.CreateDirectory(Path.GetDirectoryName(output)!); + PayloadWriter.Write(stub, source, output); + return output; + } + + /// + /// A minimal PE32+ header (no sections) followed by filler, with an optional certificate table at the end the + /// way signtool lays it out: 8-byte aligned, pointed at by the security data directory. + /// + public static byte[] PortableExecutable(int fillerLength, byte[]? certificate = null) + { + const int peOffset = 0x80; + const int optionalHeaderSize = 240; + var headerLength = peOffset + 4 + 20 + optionalHeaderSize; + var image = new byte[headerLength + fillerLength]; + "MZ"u8.CopyTo(image); + BinaryPrimitives.WriteInt32LittleEndian(image.AsSpan(0x3C), peOffset); + "PE\0\0"u8.CopyTo(image.AsSpan(peOffset)); + var coff = image.AsSpan(peOffset + 4); + BinaryPrimitives.WriteUInt16LittleEndian(coff, 0x8664); + BinaryPrimitives.WriteUInt16LittleEndian(coff[16..], optionalHeaderSize); + BinaryPrimitives.WriteUInt16LittleEndian(coff[18..], 0x0022); + var optional = image.AsSpan(peOffset + 24); + BinaryPrimitives.WriteUInt16LittleEndian(optional, 0x20B); + BinaryPrimitives.WriteUInt32LittleEndian(optional[32..], 0x1000); // SectionAlignment + BinaryPrimitives.WriteUInt32LittleEndian(optional[36..], 0x200); // FileAlignment + BinaryPrimitives.WriteUInt32LittleEndian(optional[108..], 16); // NumberOfRvaAndSizes + new Random(3).NextBytes(image.AsSpan(headerLength)); + return certificate is null ? image : Sign(image, certificate); + } + + /// Appends a certificate table and points the security directory at it, as signtool does. + public static byte[] Sign(byte[] file, byte[] certificate) + { + var aligned = (file.Length + 7) / 8 * 8; + var signed = new byte[aligned + certificate.Length]; + file.CopyTo(signed, 0); + certificate.CopyTo(signed, aligned); + var entry = SecurityDirectoryOffset(signed); + BinaryPrimitives.WriteUInt32LittleEndian(signed.AsSpan(entry), (uint)aligned); + BinaryPrimitives.WriteUInt32LittleEndian(signed.AsSpan(entry + 4), (uint)certificate.Length); + return signed; + } + + /// File offset of the security data directory entry of an image built by . + public static int SecurityDirectoryOffset(byte[] image) => + BinaryPrimitives.ReadInt32LittleEndian(image.AsSpan(0x3C)) + 4 + 20 + 112 + 4 * 8; + + /// Assembles an installer by hand from a manifest and data region, bypassing the writer's checks. + public string Craft(PayloadManifest manifest, byte[] data, string name = "crafted.exe") + { + var stub = CraftStub; + var json = manifest.ToJsonBytes(); + using var ms = new MemoryStream(); + ms.Write(stub); + ms.Write(json); + ms.Write(data); + ms.Write(new byte[(8 - ms.Length % 8) % 8]); + var footer = new byte[PayloadFormat.FooterLength]; + new PayloadFooter(stub.Length, json.Length, data.Length, SHA256.HashData(json)).WriteTo(footer); + ms.Write(footer); + var path = Path.Combine(Root, name); + File.WriteAllBytes(path, ms.ToArray()); + return path; + } + + public static string Sha256(byte[] content) => Convert.ToHexStringLower(SHA256.HashData(content)); +} diff --git a/tests/Titano.Core.Tests/Packaging/PayloadIntegrityTests.cs b/tests/Titano.Core.Tests/Packaging/PayloadIntegrityTests.cs new file mode 100644 index 00000000..a9ba9231 --- /dev/null +++ b/tests/Titano.Core.Tests/Packaging/PayloadIntegrityTests.cs @@ -0,0 +1,213 @@ +using System.Buffers.Binary; +using System.IO.Compression; +using Titano.Core.Packaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Packaging; + +public sealed class PayloadIntegrityTests(TestContext context) +{ + private readonly PackagingFixture _fx = new(context); + + private (string Installer, long PayloadOffset, byte[] Bytes) PackSample() + { + var app = _fx.Folder("app", + ("Titano.exe", PackagingFixture.Text("program ", 3000)), + ("noise.bin", PackagingFixture.Random(40_000, 5)), + ("docs/readme.txt", PackagingFixture.Text("read me ", 200))); + var installer = _fx.Pack(_fx.Stub(), PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app))); + using var reader = PayloadReader.Open(installer); + return (installer, reader.PayloadOffset, File.ReadAllBytes(installer)); + } + + [Test] + public void TamperedManifestIsRejected() + { + var (installer, offset, bytes) = PackSample(); + // Flip the first letter of "Titano" in "product":"Titano". + var at = Array.IndexOf(bytes, (byte)'T', (int)offset); + bytes[at] = (byte)'X'; + File.WriteAllBytes(installer, bytes); + var ex = Assert.Throws(() => PayloadReader.Open(installer)); + Assert.Equal(PayloadError.Corrupt, ex.Error); + Assert.Contains("SHA-256", ex.Message); + } + + [Test] + public void TamperedFooterHashIsRejected() + { + var (installer, _, bytes) = PackSample(); + bytes[^1] ^= 0x5A; + File.WriteAllBytes(installer, bytes); + Assert.Equal(PayloadError.Corrupt, Assert.Throws(() => PayloadReader.Open(installer)).Error); + } + + [Test] + public void FooterPointingOutsideTheFileIsRejected() + { + var (installer, _, bytes) = PackSample(); + BinaryPrimitives.WriteInt64LittleEndian(bytes.AsSpan(bytes.Length - PayloadFormat.FooterLength + 16), long.MaxValue - 3); + File.WriteAllBytes(installer, bytes); + Assert.Equal(PayloadError.Corrupt, Assert.Throws(() => PayloadReader.Open(installer)).Error); + } + + [Test] + public void CorruptStoredEntryFailsItsHash() + { + var (installer, _, bytes) = PackSample(); + PayloadFile noise; + long dataOffset; + using (var reader = PayloadReader.Open(installer)) + { + noise = reader.Manifest.Files.Single(f => f.Path == "noise.bin"); + dataOffset = DataOffset(bytes, reader.PayloadOffset); + } + Assert.Equal(PayloadCompression.Stored, noise.Compression); + bytes[dataOffset + noise.Offset + 1234] ^= 0xFF; + File.WriteAllBytes(installer, bytes); + + using var tampered = PayloadReader.Open(installer); + var ex = Assert.Throws(() => tampered.Extract([noise], context.CreateTempDirectory())); + Assert.Equal(PayloadError.Corrupt, ex.Error); + Assert.Contains("noise.bin", ex.Message); + } + + [Test] + public void EveryCorruptPayloadByteIsDetectedOrHarmless() + { + var (installer, offset, original) = PackSample(); + var expected = new Dictionary + { + ["Titano.exe"] = PackagingFixture.Text("program ", 3000), + ["noise.bin"] = PackagingFixture.Random(40_000, 5), + ["docs/readme.txt"] = PackagingFixture.Text("read me ", 200), + }; + var step = Math.Max(1, (int)((original.Length - offset) / 150)); + for (var at = offset; at < original.Length; at += step) + { + var bytes = (byte[])original.Clone(); + bytes[at] ^= 0xFF; + File.WriteAllBytes(installer, bytes); + var target = context.CreateTempDirectory("fuzz"); + try + { + using var reader = PayloadReader.Open(installer); + reader.Extract(reader.Manifest.Files, target); + foreach (var (path, content) in expected) + Assert.BytesEqual(content, File.ReadAllBytes(Path.Combine(target, path.Replace('/', Path.DirectorySeparatorChar))), $"flip at {at} produced wrong {path}"); + } + catch (PayloadException) + { + // Detected: the expected outcome for almost every byte. + } + } + } + + [Test] + public void TruncatedInstallersFailCleanly() + { + var (installer, _, original) = PackSample(); + var lengths = new List { 0, 1, 7, PayloadFormat.FooterLength - 1, PayloadFormat.FooterLength, original.Length - 1, original.Length - PayloadFormat.FooterLength }; + for (var n = 97; n < original.Length; n += original.Length / 60) lengths.Add(n); + foreach (var length in lengths) + { + File.WriteAllBytes(installer, original.AsSpan(0, length).ToArray()); + var ex = Assert.Throws(() => PayloadReader.Open(installer), $"truncated to {length}"); + Assert.True(ex.Error is PayloadError.NotFound or PayloadError.Corrupt, $"truncated to {length}: {ex.Error}"); + } + } + + [Test] + public void MissingFileIsReportedAsNotFound() => + Assert.Equal(PayloadError.NotFound, Assert.Throws(() => PayloadReader.Open(Path.Combine(_fx.Root, "nope.exe"))).Error); + + [Theory] + [Case("../evil.txt")] + [Case("a/../../evil.txt")] + [Case("/etc/passwd")] + [Case("C:/Windows/evil.dll")] + [Case("sub\\evil.txt")] + [Case("file.txt:stream")] + public void ManifestPathEscapingTheTargetIsRejected(string path) + { + var content = PackagingFixture.Text("x"); + var manifest = new PayloadManifest + { + Product = "Titano", + Version = "1.0.0", + Components = [new PayloadComponent { Id = "Titano", DisplayName = "Titano", DefaultSelected = true, EstimatedSize = 1 }], + Files = [new PayloadFile { Path = path, Component = "Titano", Size = 1, Sha256 = PackagingFixture.Sha256(content), Compression = PayloadCompression.Stored, Offset = 0, Length = 1 }], + }; + var installer = _fx.Craft(manifest, content); + Assert.Equal(PayloadError.UnsafePath, Assert.Throws(() => PayloadReader.Open(installer)).Error); + } + + [Test] + public void DeclaredSizeBeyondTheDeflateLimitIsRejectedUpFront() + { + var manifest = new PayloadManifest + { + Product = "Titano", + Version = "1.0.0", + Components = [new PayloadComponent { Id = "Titano", DisplayName = "Titano" }], + Files = [new PayloadFile { Path = "bomb.bin", Component = "Titano", Size = 1L << 40, Sha256 = new string('0', 64), Compression = PayloadCompression.Deflate, Offset = 0, Length = 16 }], + }; + var installer = _fx.Craft(manifest, new byte[16]); + Assert.Equal(PayloadError.Corrupt, Assert.Throws(() => PayloadReader.Open(installer)).Error); + } + + [Test] + public void EntryInflatingPastItsDeclaredSizeStopsAtTheLimit() + { + var zeros = new byte[4 << 20]; + using var compressed = new MemoryStream(); + using (var deflate = new DeflateStream(compressed, CompressionLevel.SmallestSize, leaveOpen: true)) deflate.Write(zeros); + var data = compressed.ToArray(); + var manifest = new PayloadManifest + { + Product = "Titano", + Version = "1.0.0", + Components = [new PayloadComponent { Id = "Titano", DisplayName = "Titano" }], + Files = [new PayloadFile { Path = "bomb.bin", Component = "Titano", Size = 1000, Sha256 = PackagingFixture.Sha256(new byte[1000]), Compression = PayloadCompression.Deflate, Offset = 0, Length = data.Length }], + }; + using var reader = PayloadReader.Open(_fx.Craft(manifest, data)); + var target = context.CreateTempDirectory(); + var ex = Assert.Throws(() => reader.Extract(reader.Manifest.Files, target)); + Assert.Contains("larger", ex.Message); + Assert.True(new FileInfo(Path.Combine(target, "bomb.bin")).Length <= 1000); + } + + [Test] + public void SignedStubLosesItsSignatureAndSignedInstallerStillOpens() + { + var stubBytes = PackagingFixture.PortableExecutable(5000, certificate: PackagingFixture.Random(1500, 9)); + var stub = Path.Combine(_fx.Root, "signed-stub.exe"); + File.WriteAllBytes(stub, stubBytes); + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app", 50))); + var installer = _fx.Pack(stub, PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app))); + + var packed = File.ReadAllBytes(installer); + var entry = PackagingFixture.SecurityDirectoryOffset(packed); + Assert.Equal(0L, BinaryPrimitives.ReadInt64LittleEndian(packed.AsSpan(entry)), "stub signature directory cleared"); + + // Sign the whole installer the way signtool does, then read it back. + File.WriteAllBytes(installer, PackagingFixture.Sign(packed, PackagingFixture.Random(2048, 4))); + using var reader = PayloadReader.Open(installer); + Assert.Equal((long)(stubBytes.Length - 1500), reader.PayloadOffset); + var target = context.CreateTempDirectory(); + reader.Extract(reader.Manifest.Files, target); + Assert.BytesEqual(PackagingFixture.Text("app", 50), File.ReadAllBytes(Path.Combine(target, "Titano.exe"))); + + var copy = Path.Combine(target, "Uninstall Titano.exe"); + reader.WriteStub(copy); + var copied = File.ReadAllBytes(copy); + Assert.Equal(reader.PayloadOffset, (long)copied.Length); + Assert.Equal(0L, BinaryPrimitives.ReadInt64LittleEndian(copied.AsSpan(entry)), "uninstaller signature directory cleared"); + } + + private static long DataOffset(byte[] installer, long payloadOffset) + { + var footer = installer.AsSpan(installer.Length - PayloadFormat.FooterLength); + return payloadOffset + BinaryPrimitives.ReadInt64LittleEndian(footer[16..]); + } +} diff --git a/tests/Titano.Core.Tests/Packaging/PayloadPathTests.cs b/tests/Titano.Core.Tests/Packaging/PayloadPathTests.cs new file mode 100644 index 00000000..f6c58fd0 --- /dev/null +++ b/tests/Titano.Core.Tests/Packaging/PayloadPathTests.cs @@ -0,0 +1,60 @@ +using Titano.Core.Packaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Packaging; + +public sealed class PayloadPathTests(TestContext context) +{ + [Theory] + [Case("Titano.exe")] + [Case("lib/deep/file.dll")] + [Case("città/日本語 ✓.txt")] + [Case(".hidden")] + [Case("CONFIG.SYS")] + [Case("console.log")] + public void AcceptsCanonicalRelativePaths(string path) => Assert.True(PayloadPath.IsValid(path), path); + + [Theory] + [Case("")] + [Case("..")] + [Case("../x")] + [Case("a/../b")] + [Case("a/./b")] + [Case("a//b")] + [Case("/rooted")] + [Case("trailing/")] + [Case("C:/x")] + [Case("a\\b")] + [Case("a:stream")] + [Case("con")] + [Case("aux.txt")] + [Case("COM1")] + [Case("lpt9.log")] + [Case("dot.")] + [Case("space ")] + [Case("tab\tname")] + [Case("star*")] + public void RejectsUnsafePaths(string path) => Assert.False(PayloadPath.IsValid(path), path); + + [Test] + public void RejectsOverlongPaths() + { + Assert.False(PayloadPath.IsValid(new string('a', 256))); + Assert.False(PayloadPath.IsValid(string.Join('/', Enumerable.Repeat("abcdefghij", 100)))); + } + + [Test] + public void ResolveStaysInsideTheRoot() + { + var root = context.CreateTempDirectory(); + Assert.Equal(Path.Combine(root, "a", "b.txt"), PayloadPath.Resolve(root, "a/b.txt")); + Assert.Equal(PayloadError.UnsafePath, Assert.Throws(() => PayloadPath.Resolve(root, "../b.txt")).Error); + } + + [Test] + public void ConvertsNativeSeparators() + { + Assert.Equal("a/b/c.txt", PayloadPath.FromRelative("a\\b\\c.txt")); + Assert.Throws(() => PayloadPath.FromRelative("..\\c.txt")); + } +} diff --git a/tests/Titano.Core.Tests/Packaging/PayloadRoundTripTests.cs b/tests/Titano.Core.Tests/Packaging/PayloadRoundTripTests.cs new file mode 100644 index 00000000..55d2f575 --- /dev/null +++ b/tests/Titano.Core.Tests/Packaging/PayloadRoundTripTests.cs @@ -0,0 +1,172 @@ +using Titano.Core.Packaging; +using Titano.Testing; + +namespace Titano.Core.Tests.Packaging; + +public sealed class PayloadRoundTripTests(TestContext context) +{ + private readonly PackagingFixture _fx = new(context); + + [Test] + public void ExtractsNestedEmptyUnicodeAndIncompressibleFilesExactly() + { + var files = new (string Path, byte[] Content)[] + { + ("Titano.exe", PackagingFixture.Text("MZ program body ", 4000)), + ("lib/deep/er/still/config.json", PackagingFixture.Text("{\"a\":1}", 50)), + ("empty.txt", []), + ("città/日本語 ✓.txt", PackagingFixture.Text("ciao 世界 ", 300)), + ("media/noise.bin", PackagingFixture.Random(3 << 20, seed: 11)), + }; + var app = _fx.Folder("app", files); + var installer = _fx.Pack(_fx.Stub(), PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app))); + + using var reader = PayloadReader.Open(installer); + var manifest = reader.Manifest; + Assert.Equal("Titano", manifest.Product); + Assert.Equal("1.2.3", manifest.Version); + Assert.Count(files.Length, manifest.Files); + Assert.Equal(files.Sum(f => (long)f.Content.Length), manifest.Components[0].EstimatedSize); + Assert.Equal(PayloadCompression.Stored, manifest.Files.Single(f => f.Path == "media/noise.bin").Compression); + Assert.Equal(PayloadCompression.Deflate, manifest.Files.Single(f => f.Path == "Titano.exe").Compression); + var empty = manifest.Files.Single(f => f.Path == "empty.txt"); + Assert.Equal(0L, empty.Length); + + var target = context.CreateTempDirectory("extract"); + reader.Extract(manifest.FilesFor(["Titano"]), target); + foreach (var (relative, content) in files) + { + var path = Path.Combine(target, relative.Replace('/', Path.DirectorySeparatorChar)); + Assert.BytesEqual(content, File.ReadAllBytes(path), relative); + Assert.Equal(PackagingFixture.FixedTime, File.GetLastWriteTimeUtc(path), relative); + } + } + + [Test] + public void ReportsProgressUpToTheTotalSize() + { + var app = _fx.Folder("app", ("a.bin", PackagingFixture.Random(9 << 20, 1)), ("b.txt", PackagingFixture.Text("b", 10))); + var installer = _fx.Pack(_fx.Stub(), PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app))); + using var reader = PayloadReader.Open(installer); + var reports = new List(); + reader.Extract(reader.Manifest.Files, context.CreateTempDirectory(), new SyncProgress(reports.Add)); + Assert.True(reports.Count >= 3); + Assert.Monotonic(reports.Select(r => (double)r.Done)); + Assert.Equal(reports[^1].Total, reports[^1].Done); + Assert.Equal((9L << 20) + 10, reports[^1].Total); + } + + [Test] + public void IdenticalInputsProduceIdenticalInstallers() + { + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app", 999)), ("sub/z.txt", PackagingFixture.Text("z")), ("sub/a.txt", PackagingFixture.Text("a"))); + var up = _fx.Folder("uploader", ("Titano.Uploader.exe", PackagingFixture.Text("uploader", 500))); + var stub = _fx.Stub(); + var source = PackagingFixture.Source( + new PayloadComponentSource("Titano", "Titano", true, app), + new PayloadComponentSource("Uploader", "Titano Uploader", false, up)); + var first = _fx.Pack(stub, source, "first.exe"); + var second = _fx.Pack(stub, source, "second.exe"); + Assert.BytesEqual(File.ReadAllBytes(first), File.ReadAllBytes(second)); + Assert.Equal(0L, new FileInfo(first).Length % PayloadFormat.Alignment); + } + + [Test] + public void SharedFilesAreStoredOnceAndInstalledOnce() + { + var shared = PackagingFixture.Text("shared runtime ", 2000); + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app", 100)), ("runtime.dll", shared)); + var up = _fx.Folder("uploader", ("Titano.Uploader.exe", PackagingFixture.Text("up", 100)), ("runtime.dll", shared)); + var installer = _fx.Pack(_fx.Stub(), PackagingFixture.Source( + new PayloadComponentSource("Titano", "Titano", true, app), + new PayloadComponentSource("Uploader", "Uploader", true, up))); + + using var reader = PayloadReader.Open(installer); + var copies = reader.Manifest.Files.Where(f => f.Path == "runtime.dll").ToList(); + Assert.Count(2, copies); + Assert.Equal(copies[0].Offset, copies[1].Offset); + var both = reader.Manifest.FilesFor(["Titano", "Uploader"]); + Assert.Count(3, both); + Assert.Count(2, reader.Manifest.FilesFor(["uploader"])); + Assert.Throws(() => reader.Manifest.FilesFor(["Server"])); + } + + [Test] + public void DifferentContentAtTheSamePathAcrossComponentsIsRejected() + { + var app = _fx.Folder("app", ("same.dll", PackagingFixture.Text("one"))); + var up = _fx.Folder("uploader", ("same.dll", PackagingFixture.Text("two"))); + var ex = Assert.Throws(() => _fx.Pack(_fx.Stub(), PackagingFixture.Source( + new PayloadComponentSource("Titano", "Titano", true, app), + new PayloadComponentSource("Uploader", "Uploader", true, up)))); + Assert.Equal(PayloadError.Corrupt, ex.Error); + } + + [Test] + public void ShortcutsAndAssociationsSurviveTheRoundTrip() + { + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app"))); + var source = new PayloadSource + { + Product = "Titano", + Version = "2.0.0-beta.1", + Components = [new PayloadComponentSource("Titano", "Titano", true, app)], + Shortcuts = [new PayloadShortcut { Component = "Titano", Name = "Titano", Target = "Titano.exe", StartMenu = true, Desktop = true }], + Associations = [new PayloadAssociation { Component = "Titano", Extension = ".titano", ProgId = "Titano.Project", Description = "Titano project", Target = "Titano.exe" }], + }; + using var reader = PayloadReader.Open(_fx.Pack(_fx.Stub(), source)); + var shortcut = reader.Manifest.Shortcuts.Single(); + Assert.True(shortcut.Desktop && shortcut.StartMenu); + Assert.Equal("Titano.exe", shortcut.Target); + Assert.Equal("Titano.Project", reader.Manifest.Associations.Single().ProgId); + } + + [Test] + public void ShortcutToAFileOutsideItsComponentIsRejected() + { + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app"))); + var source = new PayloadSource + { + Product = "Titano", + Version = "1.0.0", + Components = [new PayloadComponentSource("Titano", "Titano", true, app)], + Shortcuts = [new PayloadShortcut { Component = "Titano", Name = "Missing", Target = "Missing.exe", StartMenu = true }], + }; + Assert.Throws(() => _fx.Pack(_fx.Stub(), source)); + } + + [Test] + public void StubCopyEndsAtThePayload() + { + var stub = _fx.Stub(10_000); + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app", 10))); + using var reader = PayloadReader.Open(_fx.Pack(stub, PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app)))); + Assert.Equal(10_000L, reader.PayloadOffset); + var copy = Path.Combine(context.CreateTempDirectory(), "Uninstall Titano.exe"); + reader.WriteStub(copy); + Assert.BytesEqual(File.ReadAllBytes(stub), File.ReadAllBytes(copy)); + Assert.Equal(PayloadError.NotFound, Assert.Throws(() => PayloadReader.Open(copy)).Error); + } + + [Test] + public void OutputInsideAComponentFolderIsRefused() + { + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app"))); + Assert.Throws(() => PayloadWriter.Write(_fx.Stub(), PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app)), Path.Combine(app, "setup.exe"))); + } + + [Test] + public void AnInstallerCannotBeUsedAsStub() + { + var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app"))); + var source = PackagingFixture.Source(new PayloadComponentSource("Titano", "Titano", true, app)); + var installer = _fx.Pack(_fx.Stub(), source); + Assert.Throws(() => _fx.Pack(installer, source, "nested.exe")); + } + + /// Synchronous (Progress<T> posts to the thread pool). + private sealed class SyncProgress(Action report) : IProgress + { + public void Report(T value) => report(value); + } +}