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 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:56:37 +00:00
1 parent c40b6a7cd3
commit d79ab1e41b
12 files changed
+1488

No files matched your search

@@ -0,0 +1,21 @@
namespace Titano.Core.Packaging;
/// <summary>Why a TPK1 payload could not be read, written or extracted.</summary>
public enum PayloadError
{
/// <summary>The file carries no payload footer: not a packed installer, or its end was cut off.</summary>
NotFound,
/// <summary>Footer, manifest or entry data are inconsistent, truncated or fail their SHA-256.</summary>
Corrupt,
/// <summary>A path is absolute, escapes the target folder or uses a name Windows cannot store.</summary>
UnsafePath,
}
/// <summary>A payload problem with a machine-readable <see cref="Error"/> for exit codes and UI messages.</summary>
public sealed class PayloadException(PayloadError error, string message, Exception? innerException = null)
: Exception(message, innerException)
{
public PayloadError Error { get; } = error;
}
@@ -0,0 +1,52 @@
using System.Buffers.Binary;
namespace Titano.Core.Packaging;
/// <summary>
/// The TPK1 self-extracting layout: <c>[setup stub][manifest JSON][entry data][zero padding][footer]</c>, optionally
/// followed by an Authenticode certificate table that signtool appends when the installer is signed.
/// The footer is 64 bytes, little-endian: magic <c>"TPK1END\0"</c> · 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.
/// </summary>
public static class PayloadFormat
{
public const int FooterLength = 64;
public const int Alignment = 8;
public const int ManifestFormatVersion = 1;
/// <summary>Upper bound for the manifest; a larger value in a footer means corruption.</summary>
public const int MaxManifestLength = 64 << 20;
/// <summary>Deflate cannot expand data by more than about 1032:1; larger declared sizes are rejected up front.</summary>
public const int MaxDeflateRatio = 1032;
public static ReadOnlySpan<byte> Magic => "TPK1END\0"u8;
}
/// <summary>Decoded TPK1 footer.</summary>
internal readonly record struct PayloadFooter(long PayloadOffset, long ManifestLength, long DataLength, byte[] ManifestHash)
{
public void WriteTo(Span<byte> destination)
{
PayloadFormat.Magic.CopyTo(destination);
BinaryPrimitives.WriteInt64LittleEndian(destination[8..], PayloadOffset);
BinaryPrimitives.WriteInt64LittleEndian(destination[16..], ManifestLength);
BinaryPrimitives.WriteInt64LittleEndian(destination[24..], DataLength);
ManifestHash.CopyTo(destination[32..]);
}
/// <summary>Parses a footer; false when the magic does not match.</summary>
public static bool TryParse(ReadOnlySpan<byte> 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;
}
}
@@ -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;
/// <summary>How an entry's bytes are stored in the data region.</summary>
public enum PayloadCompression
{
Stored,
Deflate,
}
/// <summary>Describes everything a TPK1 installer carries: product, components, files, shortcuts and file types.</summary>
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<PayloadComponent> Components { get; init; } = [];
public List<PayloadFile> Files { get; init; } = [];
public List<PayloadShortcut> Shortcuts { get; init; } = [];
public List<PayloadAssociation> Associations { get; init; } = [];
/// <summary>The component with <paramref name="id"/> (ordinal, case-insensitive), or null.</summary>
public PayloadComponent? FindComponent(string id) =>
Components.FirstOrDefault(c => c.Id.Equals(id, StringComparison.OrdinalIgnoreCase));
/// <summary>
/// Files installed by the given components, one entry per path in manifest order. A path shared by several
/// components (identical content, enforced by <see cref="Validate"/>) is listed once.
/// </summary>
public IReadOnlyList<PayloadFile> FilesFor(IEnumerable<string> componentIds)
{
var selected = new HashSet<string>(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<string>(PayloadPath.Comparer);
var result = new List<PayloadFile>();
foreach (var file in Files)
{
if (selected.Contains(file.Component) && seen.Add(file.Path)) result.Add(file);
}
return result;
}
/// <summary>Rejects manifests that are inconsistent with themselves or with a data region of <paramref name="dataLength"/> bytes.</summary>
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<string>(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<string, PayloadFile>(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()));
}
/// <summary>Serializes with a fixed property order and no whitespace, so identical inputs give identical bytes.</summary>
public byte[] ToJsonBytes() => JsonSerializer.SerializeToUtf8Bytes(this, PayloadJson.Default.PayloadManifest);
/// <summary>Parses manifest bytes; malformed JSON is reported as <see cref="PayloadError.Corrupt"/>.</summary>
public static PayloadManifest Parse(ReadOnlySpan<byte> 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();
}
/// <summary>A selectable part of the product (Titano, Uploader, Server).</summary>
public sealed class PayloadComponent
{
public required string Id { get; init; }
public required string DisplayName { get; init; }
public bool DefaultSelected { get; init; }
/// <summary>Installed size in bytes (sum of the component's files).</summary>
public long EstimatedSize { get; init; }
}
/// <summary>One installed file and where its bytes live in the data region.</summary>
public sealed class PayloadFile
{
/// <summary>Canonical relative path (<see cref="PayloadPath"/>).</summary>
public required string Path { get; init; }
public required string Component { get; init; }
public long Size { get; init; }
/// <summary>Lower-case hex SHA-256 of the uncompressed content.</summary>
public required string Sha256 { get; init; }
public PayloadCompression Compression { get; init; }
/// <summary>Offset of the stored bytes, relative to the start of the data region.</summary>
public long Offset { get; init; }
/// <summary>Number of stored (possibly compressed) bytes.</summary>
public long Length { get; init; }
/// <summary>Last write time, Unix epoch seconds (UTC).</summary>
public long ModifiedUnixSeconds { get; init; }
}
/// <summary>A shortcut to one of a component's files, created in the Start menu and/or on the desktop.</summary>
public sealed class PayloadShortcut
{
public required string Component { get; init; }
/// <summary>File name of the shortcut without <c>.lnk</c>.</summary>
public required string Name { get; init; }
/// <summary>Payload path of the program the shortcut opens.</summary>
public required string Target { get; init; }
public bool StartMenu { get; init; }
public bool Desktop { get; init; }
}
/// <summary>A file type registered to open with one of a component's programs (<c>"target" "%1"</c>).</summary>
public sealed class PayloadAssociation
{
public required string Component { get; init; }
/// <summary>Extension including the dot, e.g. <c>.titano</c>.</summary>
public required string Extension { get; init; }
public required string ProgId { get; init; }
/// <summary>File type name shown by Explorer.</summary>
public required string Description { get; init; }
/// <summary>Payload path of the program that opens the file.</summary>
public required string Target { get; init; }
}
[JsonSourceGenerationOptions(PropertyNamingPolicy = JsonKnownNamingPolicy.CamelCase, UseStringEnumConverter = true, RespectNullableAnnotations = true)]
[JsonSerializable(typeof(PayloadManifest))]
internal sealed partial class PayloadJson : JsonSerializerContext;
+68
View File
@@ -0,0 +1,68 @@
namespace Titano.Core.Packaging;
/// <summary>
/// Canonical payload paths: relative, forward slashes, every segment a name Windows can store. Anything rooted,
/// drive-qualified, stream-qualified (<c>a:b</c>), containing <c>.</c>/<c>..</c> or empty segments is rejected, so an
/// archive can never write outside the folder it is extracted into.
/// </summary>
public static class PayloadPath
{
public const int MaxLength = 1024;
public const int MaxSegmentLength = 255;
private static readonly HashSet<string> 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",
};
/// <summary>Path comparison used for payload paths: Windows file systems are case-insensitive.</summary>
public static StringComparer Comparer => StringComparer.OrdinalIgnoreCase;
/// <summary>True when <paramref name="path"/> is a canonical, safe relative payload path.</summary>
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;
}
/// <summary>True when <paramref name="name"/> is a single file or folder name Windows accepts verbatim.</summary>
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);
}
/// <summary>Converts a path relative to a source folder (either separator) into its canonical payload form.</summary>
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;
}
/// <summary>Full path of <paramref name="relative"/> under <paramref name="root"/>; throws when unsafe or outside the root.</summary>
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;
}
}
+235
View File
@@ -0,0 +1,235 @@
using System.Buffers;
using System.IO.Compression;
using System.Security.Cryptography;
namespace Titano.Core.Packaging;
/// <summary>Extraction progress: bytes written so far, total bytes, and the file being written.</summary>
public readonly record struct PayloadProgress(long Done, long Total, string CurrentPath);
/// <summary>
/// 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.
/// </summary>
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;
}
/// <summary>The installer file the payload was read from.</summary>
public string ArchivePath { get; }
/// <summary>Absolute offset where the payload starts; the bytes before it are the setup program.</summary>
public long PayloadOffset { get; }
public PayloadManifest Manifest { get; }
/// <summary>Opens the payload appended to the running executable.</summary>
public static PayloadReader OpenCurrentProcess() =>
Open(Environment.ProcessPath ?? throw new PayloadException(PayloadError.NotFound, "The setup program path is unknown."));
/// <summary>Opens and validates the payload of <paramref name="path"/>.</summary>
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;
}
}
/// <summary>
/// Writes every file of <paramref name="files"/> under <paramref name="directory"/>, verifying sizes and hashes.
/// The directory should be a fresh staging folder: on failure it holds partial output the caller discards.
/// </summary>
public void Extract(IReadOnlyList<PayloadFile> files, string directory, IProgress<PayloadProgress>? progress = null, CancellationToken cancellationToken = default)
{
long total = 0;
foreach (var f in files) total += f.Size;
long done = 0;
var buffer = ArrayPool<byte>.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<byte>.Shared.Return(buffer);
}
}
/// <summary>
/// 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.
/// </summary>
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<PayloadProgress>? 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));
}
/// <summary>True when <paramref name="stream"/> ends with a TPK1 footer (an installer must not become another one's stub).</summary>
internal static bool HasFooter(FileStream stream)
{
try
{
LocateFooter(stream, out _);
return true;
}
catch (PayloadException)
{
return false;
}
finally
{
stream.Position = 0;
}
}
/// <summary>Finds the footer just before the end of the content (the file end, or the start of a signature).</summary>
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<byte>.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<byte>.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);
}
+225
View File
@@ -0,0 +1,225 @@
using System.Buffers;
using System.IO.Compression;
using System.Security.Cryptography;
using Titano.Core.IO;
namespace Titano.Core.Packaging;
/// <summary>A component to pack: its manifest identity and the folder whose whole tree it installs.</summary>
public sealed record PayloadComponentSource(string Id, string DisplayName, bool DefaultSelected, string Folder);
/// <summary>Everything the packer needs besides the setup program.</summary>
public sealed class PayloadSource
{
public required string Product { get; init; }
public required string Version { get; init; }
public IReadOnlyList<PayloadComponentSource> Components { get; init; } = [];
public IReadOnlyList<PayloadShortcut> Shortcuts { get; init; } = [];
public IReadOnlyList<PayloadAssociation> Associations { get; init; } = [];
}
/// <summary>Sizes of a written installer.</summary>
public sealed record PayloadWriteResult(long InstallerBytes, long PayloadBytes, long InstalledBytes, int FileCount);
/// <summary>
/// Builds a self-extracting installer: the setup program followed by a TPK1 payload (<see cref="PayloadFormat"/>).
/// Output is deterministic: files are ordered by component then ordinal path, the manifest has a fixed shape,
/// and identical content is stored once.
/// </summary>
public static class PayloadWriter
{
private const int BufferSize = 1 << 16;
private static readonly string EmptySha256 = Convert.ToHexStringLower(SHA256.HashData([]));
/// <summary>Packs <paramref name="source"/> after <paramref name="stubPath"/> into <paramref name="outputPath"/> (written atomically).</summary>
public static PayloadWriteResult Write(string stubPath, PayloadSource source, string outputPath, IProgress<PayloadProgress>? 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<byte> 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<Input> Enumerate(PayloadSource source, string output)
{
var options = new EnumerationOptions { RecurseSubdirectories = true, AttributesToSkip = 0, IgnoreInaccessible = false };
var inputs = new List<Input>();
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;
}
/// <summary>Compresses every input into the spool, storing each distinct content once.</summary>
private static List<PayloadFile> Spool(List<Input> inputs, FileStream spool, long total, IProgress<PayloadProgress>? progress, CancellationToken cancellationToken)
{
var blobs = new Dictionary<string, (long Offset, long Length, PayloadCompression Compression)>(StringComparer.Ordinal);
var files = new List<PayloadFile>(inputs.Count);
var buffer = ArrayPool<byte>.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<byte>.Shared.Return(buffer);
}
return files;
}
/// <summary>Copies the setup program, dropping an Authenticode table (the installer is signed as a whole later).</summary>
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<byte>.Shared.Rent(BufferSize);
try
{
CopyExactly(stub, installer, PeImage.ContentEnd(stub), buffer);
}
finally
{
ArrayPool<byte>.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;
}
}
}
+56
View File
@@ -0,0 +1,56 @@
using System.Reflection.PortableExecutable;
namespace Titano.Core.Packaging;
/// <summary>
/// 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).
/// </summary>
internal readonly record struct PeImage(long CertificateOffset, long CertificateSize, long DirectoryEntryOffset)
{
private const int SecurityDirectoryIndex = 4;
public bool IsSigned => CertificateSize > 0;
/// <summary>Reads the PE headers at the start of <paramref name="stream"/>; null when it is not a PE file.</summary>
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;
}
}
/// <summary>Where meaningful content ends: the certificate table when one sits inside the file, else the file end.</summary>
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;
}
/// <summary>Clears the security directory entry so the file no longer claims a signature.</summary>
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;
}
}
+42
View File
@@ -0,0 +1,42 @@
namespace Titano.Core.Packaging;
/// <summary>Read-only view of <c>[offset, offset + length)</c> of a seekable stream; reads never cross the window.</summary>
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<byte> 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();
}
@@ -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;
/// <summary>Synthetic stubs, component trees and hand-made installers for the packaging tests.</summary>
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");
/// <summary>A setup "program": any bytes work, the format does not interpret the stub unless it is a PE.</summary>
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;
}
/// <summary>Creates <paramref name="files"/> (payload path → content) under a new folder with a fixed mtime.</summary>
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;
}
/// <summary>
/// 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.
/// </summary>
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);
}
/// <summary>Appends a certificate table and points the security directory at it, as signtool does.</summary>
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;
}
/// <summary>File offset of the security data directory entry of an image built by <see cref="PortableExecutable"/>.</summary>
public static int SecurityDirectoryOffset(byte[] image) =>
BinaryPrimitives.ReadInt32LittleEndian(image.AsSpan(0x3C)) + 4 + 20 + 112 + 4 * 8;
/// <summary>Assembles an installer by hand from a manifest and data region, bypassing the writer's checks.</summary>
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));
}
@@ -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<PayloadException>(() => 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<PayloadException>(() => 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<PayloadException>(() => 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<PayloadException>(() => 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<string, byte[]>
{
["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<int> { 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<PayloadException>(() => 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<PayloadException>(() => 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<PayloadException>(() => 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<PayloadException>(() => 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<PayloadException>(() => 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..]);
}
}
@@ -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<PayloadException>(() => PayloadPath.Resolve(root, "../b.txt")).Error);
}
[Test]
public void ConvertsNativeSeparators()
{
Assert.Equal("a/b/c.txt", PayloadPath.FromRelative("a\\b\\c.txt"));
Assert.Throws<PayloadException>(() => PayloadPath.FromRelative("..\\c.txt"));
}
}
@@ -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<PayloadProgress>();
reader.Extract(reader.Manifest.Files, context.CreateTempDirectory(), new SyncProgress<PayloadProgress>(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<ArgumentException>(() => 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<PayloadException>(() => _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<PayloadException>(() => _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<PayloadException>(() => PayloadReader.Open(copy)).Error);
}
[Test]
public void OutputInsideAComponentFolderIsRefused()
{
var app = _fx.Folder("app", ("Titano.exe", PackagingFixture.Text("app")));
Assert.Throws<ArgumentException>(() => 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<ArgumentException>(() => _fx.Pack(installer, source, "nested.exe"));
}
/// <summary>Synchronous <see cref="IProgress{T}"/> (Progress&lt;T&gt; posts to the thread pool).</summary>
private sealed class SyncProgress<T>(Action<T> report) : IProgress<T>
{
public void Report(T value) => report(value);
}
}