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);
+ }
+}