@zogien/native-sdk 0.11.0-fork.3 → 0.11.0-fork.5

package/src/tooling/templates.zig

@@ -1597,6 +1597,9 @@ fn buildZig(allocator: std.mem.Allocator, names: TemplateNames, framework_path:
         \\    package.addArgs(&.{ "--web-layer", if (web_layer) "include" else "exclude" });
         \\    if (cef_auto_install) package.addArg("--cef-auto-install");
         \\    if (app_config.updates_enabled and package_target == .macos and b.graph.host.result.os.tag == .macos) package.addArg("--update-archive");
+        \\    // Windows updates reach only installed apps, so an app with updates
+        \\    // ships the per-user setup program beside the archive its feed names.
+        \\    if (app_config.updates_enabled and package_target == .windows) package.addArgs(&.{ "--installer", "--update-archive" });
         \\    package.step.dependOn(&package_exe.step);
         \\    package.step.dependOn(&frontend_build.step);
         \\    const package_step = b.step("package", "Create a local package artifact");
@@ -2440,8 +2443,9 @@ fn runnerZig() []const u8 {
     \\            .bundle_id = self.bundle_id,
     \\            .icon_path = self.icon_path,
     \\            .update_feed_url = manifestUpdateString("feed_url"),
-    \\            .update_public_key = manifestUpdateString("public_key"),
+    \\            .update_public_key = manifestUpdatePublicKeys(),
     \\            .update_check_on_start = manifestUpdateCheckOnStart(),
+    \\            .update_mode = manifestUpdateMode(),
     \\        };
     \\        const windows = manifestWindowOptions(buffers);
     \\        if (windows.len > 0) {
@@ -2518,6 +2522,36 @@ fn runnerZig() []const u8 {
     \\    return app_manifest.updates.check_on_start;
     \\}
     \\
+    \\/// The trusted update keys the updater verifies feeds against:
+    \\/// `public_key` followed by any `public_keys`, comma-joined.
+    \\fn manifestUpdatePublicKeys() []const u8 {
+    \\    const primary = comptime manifestUpdateString("public_key");
+    \\    if (comptime primary.len == 0) return "";
+    \\    if (comptime !@hasField(@TypeOf(app_manifest.updates), "public_keys")) return primary;
+    \\    comptime var keys: []const u8 = primary;
+    \\    inline for (app_manifest.updates.public_keys) |key| keys = keys ++ "," ++ key;
+    \\    return keys;
+    \\}
+    \\
+    \\fn manifestUpdateMode() native_sdk.platform.UpdateMode {
+    \\    if (comptime !@hasField(@TypeOf(app_manifest), "updates")) return .host;
+    \\    if (comptime !@hasField(@TypeOf(app_manifest.updates), "mode")) return .host;
+    \\    return comptime std.meta.stringToEnum(native_sdk.platform.UpdateMode, app_manifest.updates.mode) orelse
+    \\        @compileError("app manifest updates.mode must be \"host\" or \"app\"");
+    \\}
+    \\
+    \\/// Points the app-driven updater at this installation (see
+    \\/// `updater.configureApp`).
+    \\fn configureUpdates(app_info: *native_sdk.platform.AppInfo, environ_map: *std.process.Environ.Map) void {
+    \\    const host: native_sdk.updater.Host = comptime if (std.mem.eql(u8, build_options.platform, "windows"))
+    \\        .windows
+    \\    else if (std.mem.eql(u8, build_options.platform, "macos") and std.mem.eql(u8, build_options.web_engine, "system"))
+    \\        .macos_appkit
+    \\    else
+    \\        .other;
+    \\    native_sdk.updater.configureApp(host, app_info, environ_map);
+    \\}
+    \\
     \\const CommandStorage = struct {
     \\    commands: [native_sdk.app_manifest.max_commands]native_sdk.Command = undefined,
     \\
@@ -3062,6 +3096,7 @@ fn runnerZig() []const u8 {
     \\fn runMacos(app: native_sdk.App, options: RunOptions, init: std.process.Init) !void {
     \\    var buffers: StateBuffers = undefined;
     \\    var app_info = options.appInfo(&buffers);
+    \\    configureUpdates(&app_info, init.environ_map);
     \\    const store = prepareStateStore(init.io, init.environ_map, &app_info, &buffers);
     \\    // Heap wrapper, latch-gated free: worker threads hold this address
     \\    // as the channel wake context and an abandoned wake call may
@@ -3120,6 +3155,7 @@ fn runnerZig() []const u8 {
     \\fn runLinux(app: native_sdk.App, options: RunOptions, init: std.process.Init) !void {
     \\    var buffers: StateBuffers = undefined;
     \\    var app_info = options.appInfo(&buffers);
+    \\    configureUpdates(&app_info, init.environ_map);
     \\    const store = prepareStateStore(init.io, init.environ_map, &app_info, &buffers);
     \\    // Heap wrapper, latch-gated free: worker threads hold this address
     \\    // as the channel wake context and an abandoned wake call may
@@ -3178,6 +3214,7 @@ fn runnerZig() []const u8 {
     \\fn runWindows(app: native_sdk.App, options: RunOptions, init: std.process.Init) !void {
     \\    var buffers: StateBuffers = undefined;
     \\    var app_info = options.appInfo(&buffers);
+    \\    configureUpdates(&app_info, init.environ_map);
     \\    const store = prepareStateStore(init.io, init.environ_map, &app_info, &buffers);
     \\    // Heap wrapper, latch-gated free: worker threads hold this address
     \\    // as the channel wake context and an abandoned wake call may
@@ -4272,6 +4309,7 @@ test "writeDefaultApp emits Vite project files" {
     // the packaged artifact structurally agrees with the compiled exe.
     try std.testing.expect(std.mem.indexOf(u8, build_zig_text, "package.addArgs(&.{ \"--web-layer\", if (web_layer) \"include\" else \"exclude\" })") != null);
     try std.testing.expect(std.mem.indexOf(u8, build_zig_text, "package.addArg(\"--update-archive\")") != null);
+    try std.testing.expect(std.mem.indexOf(u8, build_zig_text, "package_target == .windows) package.addArgs(&.{ \"--installer\", \"--update-archive\" })") != null);
     try std.testing.expect(std.mem.indexOf(u8, build_zig_text, "options.addOption(bool, \"web_layer\", web_layer)") != null);
     try std.testing.expect(std.mem.indexOf(u8, build_zig_text, "std.json.parseFromSliceLeaky(InferenceManifest") != null);
     try std.testing.expect(std.mem.indexOf(u8, build_zig_text, "fn appManifestModule") != null);
@@ -4336,8 +4374,12 @@ test "writeDefaultApp emits Vite project files" {
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, "fn appInfo(self: RunOptions, buffers: *StateBuffers)") != null);
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, ".version = manifestStringField(\"version\")") != null);
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, ".update_feed_url = manifestUpdateString(\"feed_url\")") != null);
-    try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, ".update_public_key = manifestUpdateString(\"public_key\")") != null);
+    try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, ".update_public_key = manifestUpdatePublicKeys()") != null);
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, ".update_check_on_start = manifestUpdateCheckOnStart()") != null);
+    try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, ".update_mode = manifestUpdateMode()") != null);
+    // Ejected apps configure the app-driven updater on every desktop
+    // platform.
+    try std.testing.expectEqual(@as(usize, 3), std.mem.count(u8, runner_zig_text, "configureUpdates(&app_info, init.environ_map);"));
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, "fn manifestWindowOptions") != null);
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, "info.windows = windows") != null);
     try std.testing.expect(std.mem.indexOf(u8, runner_zig_text, "for (restored_windows, 0..)") != null);

package/src/tooling/update.zig

@@ -1,6 +1,7 @@
 const std = @import("std");
 const manifest_tool = @import("manifest.zig");
 const update_feed = @import("update_feed");
+const install_config = @import("windows_install_config");
 
 const Ed25519 = std.crypto.sign.Ed25519;
 
@@ -50,9 +51,14 @@ fn sign(allocator: std.mem.Allocator, io: std.Io, args: []const []const u8) !voi
     var target: ?[]const u8 = null;
     var release_notes: []const u8 = "";
     var output_path: []const u8 = "native-update.json";
+    var url_policy: update_feed.UrlPolicy = .{};
     var index: usize = 0;
     while (index < args.len) : (index += 1) {
         const name = args[index];
+        if (std.mem.eql(u8, name, "--allow-loopback-http")) {
+            url_policy.allow_loopback_http = true;
+            continue;
+        }
         index += 1;
         if (index >= args.len) return error.InvalidArguments;
         const value = args[index];
@@ -61,15 +67,16 @@ fn sign(allocator: std.mem.Allocator, io: std.Io, args: []const []const u8) !voi
     const archive = archive_path orelse return error.InvalidArguments;
     const url = archive_url orelse return error.InvalidArguments;
     const release_target = target orelse return error.InvalidArguments;
-    if (!update_feed.archiveUrlIsValid(url)) return error.InvalidArchiveUrl;
-    if (!std.mem.eql(u8, release_target, "macos-aarch64") and !std.mem.eql(u8, release_target, "macos-x86_64")) return error.InvalidTarget;
+    if (!update_feed.urlAllowed(url, url_policy)) return error.InvalidArchiveUrl;
+    if (!update_feed.isTarget(release_target)) return error.InvalidTarget;
     if (!std.mem.endsWith(u8, archive, ".zip")) return error.InvalidArchive;
     const metadata = try manifest_tool.readMetadata(allocator, io, manifest_path orelse manifest_tool.defaultPath(io) orelse "app.json");
     defer metadata.deinit(allocator);
     if (!metadata.updates.enabled()) return error.UpdatesNotConfigured;
     _ = manifest_tool.parseVersion(metadata.version) catch return error.InvalidManifestVersion;
     if (release_notes.len > 16 * 1024) return error.ReleaseNotesTooLarge;
-    validateUpdateArchive(allocator, io, archive, metadata.id, metadata.version, metadata.name, release_target) catch |err| switch (err) {
+    const validate = if (std.mem.startsWith(u8, release_target, "windows-")) &validateWindowsUpdateArchive else &validateUpdateArchive;
+    validate(allocator, io, archive, metadata.id, metadata.version, metadata.name, release_target) catch |err| switch (err) {
         error.UpdateArchitectureMismatch => return error.UpdateArchitectureMismatch,
         else => return error.InvalidArchive,
     };
@@ -83,12 +90,14 @@ fn sign(allocator: std.mem.Allocator, io: std.Io, args: []const []const u8) !voi
     var extra: [1]u8 = undefined;
     if (try key_reader.interface.readSliceShort(&extra) != 0) return error.InvalidPrivateKey;
     const key_pair = try Ed25519.KeyPair.generateDeterministic(seed);
-    const configured_public_key = metadata.updates.public_key orelse return error.UpdatesNotConfigured;
-    var configured_public_key_bytes: [Ed25519.PublicKey.encoded_length]u8 = undefined;
-    const configured_public_key_size = std.base64.standard.Decoder.calcSizeForSlice(configured_public_key) catch return error.InvalidUpdatePublicKey;
-    if (configured_public_key_size != configured_public_key_bytes.len) return error.InvalidUpdatePublicKey;
-    std.base64.standard.Decoder.decode(&configured_public_key_bytes, configured_public_key) catch return error.InvalidUpdatePublicKey;
-    if (!std.crypto.timing_safe.eql([Ed25519.PublicKey.encoded_length]u8, key_pair.public_key.toBytes(), configured_public_key_bytes)) return error.UpdateKeyMismatch;
+    // The release's installs trust the manifest's `public_key` and any
+    // `public_keys`, so a release that rotates keys is signed with the key
+    // the installs it replaces already know.
+    if (metadata.updates.public_key == null) return error.UpdatesNotConfigured;
+    if (!metadata.updates.publicKeysAreValid()) return error.InvalidUpdatePublicKey;
+    var signing_public_key_base64: [std.base64.standard.Encoder.calcSize(Ed25519.PublicKey.encoded_length)]u8 = undefined;
+    const signing_public_key = std.base64.standard.Encoder.encode(&signing_public_key_base64, &key_pair.public_key.toBytes());
+    if (!metadata.updates.trustsPublicKey(signing_public_key)) return error.UpdateKeyMismatch;
 
     var archive_file = try std.Io.Dir.cwd().openFile(io, archive, .{});
     defer archive_file.close(io);
@@ -139,7 +148,7 @@ fn sign(allocator: std.mem.Allocator, io: std.Io, args: []const []const u8) !voi
     defer output_writer.deinit();
     try std.json.Stringify.value(.{ .payload = payload_base64, .signature = &signature_base64 }, .{ .whitespace = .indent_2 }, &output_writer.writer);
     try output_writer.writer.writeByte('\n');
-    var verified = try update_feed.verifyEnvelope(allocator, output_writer.written(), configured_public_key);
+    var verified = try update_feed.verifyEnvelopeWithPolicy(allocator, output_writer.written(), signing_public_key, url_policy);
     defer verified.deinit(allocator);
     if (!std.mem.eql(u8, verified.release.bundle_id, metadata.id) or
         !std.mem.eql(u8, verified.release.version, metadata.version) or
@@ -149,6 +158,9 @@ fn sign(allocator: std.mem.Allocator, io: std.Io, args: []const []const u8) !voi
     try atomic.file.writeStreamingAll(io, output_writer.written());
     try atomic.replace(io);
     std.debug.print("signed {s} {s} update ({d} bytes) into {s}\n", .{ metadata.displayName(), metadata.version, archive_stat.size, output_path });
+    if (!update_feed.archiveUrlIsValid(url)) {
+        std.debug.print("note: the archive URL is loopback http://; installed apps accept this feed only while NATIVE_SDK_UPDATES_FEED_URL points them at it\n", .{});
+    }
 }
 
 const max_info_plist_bytes: u64 = 1024 * 1024;
@@ -218,6 +230,72 @@ fn validateUpdateArchive(
         !plistStringValueEquals(plist, "CFBundlePackageType", "APPL")) return error.InvalidArchive;
 }
 
+/// A Windows update archive is the install image `native package
+/// --update-archive` writes: the app's install configuration naming this
+/// app and version, its launcher, and `bin\<name>.exe` built for the
+/// target architecture.
+fn validateWindowsUpdateArchive(
+    allocator: std.mem.Allocator,
+    io: std.Io,
+    archive_path: []const u8,
+    expected_bundle_id: []const u8,
+    expected_version: []const u8,
+    expected_name: []const u8,
+    expected_target: []const u8,
+) !void {
+    const expected_machine: u16 = if (std.mem.eql(u8, expected_target, "windows-aarch64")) 0xaa64 else if (std.mem.eql(u8, expected_target, "windows-x86_64")) 0x8664 else return error.InvalidTarget;
+    var file = try std.Io.Dir.cwd().openFile(io, archive_path, .{});
+    defer file.close(io);
+    var reader_buffer: [64 * 1024]u8 = undefined;
+    var reader = file.reader(io, &reader_buffer);
+    var iterator = try std.zip.Iterator.init(&reader);
+    var filename_buffer: [std.Io.Dir.max_path_bytes]u8 = undefined;
+    var executable_name_buffer: [256]u8 = undefined;
+    const executable_name = try std.fmt.bufPrint(&executable_name_buffer, "bin/{s}.exe", .{expected_name});
+    var config_bytes: ?[]u8 = null;
+    defer if (config_bytes) |bytes| allocator.free(bytes);
+    var has_launcher = false;
+    var executable_machine: ?u16 = null;
+    var entries: usize = 0;
+
+    while (try iterator.next()) |entry| {
+        const filename = try zipEntryFilename(&reader, entry, &filename_buffer);
+        if (!zipEntryPathIsSafe(filename)) return error.InvalidArchive;
+        // Installed apps unpack with std.zip, which reads only these.
+        if (entry.compression_method != .store and entry.compression_method != .deflate) return error.InvalidArchive;
+        entries += 1;
+        if (entries > 1_000_000) return error.InvalidArchive;
+        if (std.mem.eql(u8, filename, install_config.file_name)) {
+            if (config_bytes != null) return error.InvalidArchive;
+            config_bytes = try readZipEntryAlloc(allocator, &reader, entry, filename, install_config.max_config_bytes);
+        } else if (std.mem.eql(u8, filename, "native-launcher.exe")) {
+            has_launcher = true;
+        } else if (std.ascii.eqlIgnoreCase(filename, executable_name)) {
+            var header: [4096]u8 = undefined;
+            const prefix = try readZipEntryPrefix(&reader, entry, filename, &header);
+            executable_machine = peMachine(prefix) orelse return error.InvalidArchive;
+        }
+    }
+
+    const bytes = config_bytes orelse return error.InvalidArchive;
+    var parsed = install_config.parse(allocator, bytes) catch return error.InvalidArchive;
+    defer parsed.deinit();
+    const config = parsed.value;
+    if (!std.mem.eql(u8, config.bundle_id, expected_bundle_id) or
+        !std.mem.eql(u8, config.version, expected_version) or
+        !std.mem.eql(u8, config.name, expected_name)) return error.InvalidArchive;
+    if (!has_launcher) return error.InvalidArchive;
+    const machine = executable_machine orelse return error.InvalidArchive;
+    if (machine != expected_machine) return error.UpdateArchitectureMismatch;
+}
+
+fn peMachine(header: []const u8) ?u16 {
+    if (header.len < 0x40 or header[0] != 'M' or header[1] != 'Z') return null;
+    const pe_offset: usize = std.mem.readInt(u32, header[0x3c..0x40], .little);
+    if (pe_offset + 6 > header.len or !std.mem.eql(u8, header[pe_offset..][0..4], "PE\x00\x00")) return null;
+    return std.mem.readInt(u16, header[pe_offset + 4 ..][0..2], .little);
+}
+
 const max_macho_architectures: usize = 64;
 const max_macho_header_bytes: usize = 8 + max_macho_architectures * 32;
 const cpu_type_x86_64: u32 = 0x01000007;
@@ -574,3 +652,143 @@ test "update archive validation requires one matching app bundle" {
     try std.testing.expectError(error.InvalidArchive, validateUpdateArchive(std.testing.allocator, std.testing.io, valid_path, "com.example.other", "1.2.3", "demo", "macos-aarch64"));
     try std.testing.expectError(error.InvalidArchive, validateUpdateArchive(std.testing.allocator, std.testing.io, valid_path, "com.example.demo", "1.2.4", "demo", "macos-aarch64"));
 }
+
+test "a release that rotates update keys is signed with a key its installs already trust" {
+    const allocator = std.testing.allocator;
+    const io = std.testing.io;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const root = try std.fmt.allocPrint(allocator, ".zig-cache/tmp/{s}", .{tmp.sub_path});
+    defer allocator.free(root);
+
+    const old_key = try Ed25519.KeyPair.generateDeterministic([_]u8{0x51} ** Ed25519.KeyPair.seed_length);
+    const unrelated_key = try Ed25519.KeyPair.generateDeterministic([_]u8{0x53} ** Ed25519.KeyPair.seed_length);
+    const old_seed = old_key.secret_key.seed();
+    const unrelated_seed = unrelated_key.secret_key.seed();
+    try tmp.dir.writeFile(io, .{ .sub_path = "old.key", .data = &old_seed });
+    try tmp.dir.writeFile(io, .{ .sub_path = "unrelated.key", .data = &unrelated_seed });
+    // The new release names its new key as `public_key` and keeps the old
+    // one in `public_keys`; installs of the previous release know only
+    // the old one.
+    try tmp.dir.writeFile(io, .{ .sub_path = "app.json", .data =
+        \\{
+        \\  "id": "com.example.demo",
+        \\  "name": "demo",
+        \\  "version": "1.2.3",
+        \\  "updates": {
+        \\    "feed_url": "https://example.com/releases/{target}/native-update.json",
+        \\    "public_key": "IBLLkMpg6OXY2vZuInLSIz4EhtVX6MZhQe2JIBd9frc=",
+        \\    "public_keys": ["wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo="]
+        \\  }
+        \\}
+    });
+    var plist_buffer: [1024]u8 = undefined;
+    const plist = try updateInfoPlist("com.example.demo", "1.2.3", "demo", &plist_buffer);
+    const executable = thinMachO64(cpu_type_arm64);
+    const archive_entries = [_]StoredZipEntry{
+        .{ .name = "Demo.app/Contents/Info.plist", .data = plist },
+        .{ .name = "Demo.app/Contents/MacOS/demo", .data = &executable },
+    };
+    const archive = try storedZipAlloc(allocator, &archive_entries);
+    defer allocator.free(archive);
+    try tmp.dir.writeFile(io, .{ .sub_path = "demo.zip", .data = archive });
+
+    const manifest_path = try std.fmt.allocPrint(allocator, "{s}/app.json", .{root});
+    defer allocator.free(manifest_path);
+    const archive_path = try std.fmt.allocPrint(allocator, "{s}/demo.zip", .{root});
+    defer allocator.free(archive_path);
+    const old_key_path = try std.fmt.allocPrint(allocator, "{s}/old.key", .{root});
+    defer allocator.free(old_key_path);
+    const unrelated_key_path = try std.fmt.allocPrint(allocator, "{s}/unrelated.key", .{root});
+    defer allocator.free(unrelated_key_path);
+    const output_path = try std.fmt.allocPrint(allocator, "{s}/native-update.json", .{root});
+    defer allocator.free(output_path);
+
+    try sign(allocator, io, &.{ "--private-key", old_key_path, "--manifest", manifest_path, "--archive", archive_path, "--url", "https://example.com/demo-1.2.3.zip", "--target", "macos-aarch64", "--output", output_path });
+    const feed = try std.Io.Dir.cwd().readFileAlloc(io, output_path, allocator, .limited(update_feed.max_envelope_bytes));
+    defer allocator.free(feed);
+    var verified = try update_feed.verifyEnvelope(allocator, feed, "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=");
+    defer verified.deinit(allocator);
+    try std.testing.expectEqualStrings("1.2.3", verified.release.version);
+    try std.testing.expectError(error.InvalidUpdateSignature, update_feed.verifyEnvelope(allocator, feed, "IBLLkMpg6OXY2vZuInLSIz4EhtVX6MZhQe2JIBd9frc="));
+
+    try std.testing.expectError(error.UpdateKeyMismatch, sign(allocator, io, &.{ "--private-key", unrelated_key_path, "--manifest", manifest_path, "--archive", archive_path, "--url", "https://example.com/demo-1.2.3.zip", "--target", "macos-aarch64", "--output", output_path }));
+
+    // A key that does not decode is reported as such, not as a mismatch.
+    try tmp.dir.writeFile(io, .{ .sub_path = "app.json", .data =
+        \\{
+        \\  "id": "com.example.demo",
+        \\  "name": "demo",
+        \\  "version": "1.2.3",
+        \\  "updates": {
+        \\    "feed_url": "https://example.com/releases/{target}/native-update.json",
+        \\    "public_key": "IBLLkMpg6OXY2vZuInLSIz4EhtVX6MZhQe2JIBd9frc=",
+        \\    "public_keys": ["wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=", "not-a-key"]
+        \\  }
+        \\}
+    });
+    try std.testing.expectError(error.InvalidUpdatePublicKey, sign(allocator, io, &.{ "--private-key", old_key_path, "--manifest", manifest_path, "--archive", archive_path, "--url", "https://example.com/demo-1.2.3.zip", "--target", "macos-aarch64", "--output", output_path }));
+}
+
+test "a Windows release signs its installed image and names loopback http only when asked" {
+    const allocator = std.testing.allocator;
+    const io = std.testing.io;
+    var tmp = std.testing.tmpDir(.{});
+    defer tmp.cleanup();
+    const root = try std.fmt.allocPrint(allocator, ".zig-cache/tmp/{s}", .{tmp.sub_path});
+    defer allocator.free(root);
+
+    const key = try Ed25519.KeyPair.generateDeterministic([_]u8{0x51} ** Ed25519.KeyPair.seed_length);
+    const seed = key.secret_key.seed();
+    try tmp.dir.writeFile(io, .{ .sub_path = "release.key", .data = &seed });
+    try tmp.dir.writeFile(io, .{ .sub_path = "app.json", .data =
+        \\{
+        \\  "id": "com.example.demo",
+        \\  "name": "demo",
+        \\  "version": "1.2.3",
+        \\  "updates": {
+        \\    "feed_url": "https://example.com/releases/{target}/native-update.json",
+        \\    "public_key": "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo="
+        \\  }
+        \\}
+    });
+    var config_writer = std.Io.Writer.Allocating.init(allocator);
+    defer config_writer.deinit();
+    try install_config.write(.{ .bundle_id = "com.example.demo", .name = "demo", .display_name = "Demo", .version = "1.2.3", .executable = "demo.exe" }, &config_writer.writer);
+    var executable = [_]u8{0} ** 0x100;
+    executable[0] = 'M';
+    executable[1] = 'Z';
+    std.mem.writeInt(u32, executable[0x3c..0x40], 0x80, .little);
+    @memcpy(executable[0x80..0x84], "PE\x00\x00");
+    std.mem.writeInt(u16, executable[0x84..0x86], 0x8664, .little);
+    const archive = try storedZipAlloc(allocator, &.{
+        .{ .name = install_config.file_name, .data = config_writer.written() },
+        .{ .name = "native-launcher.exe", .data = "launcher" },
+        .{ .name = "bin/demo.exe", .data = &executable },
+    });
+    defer allocator.free(archive);
+    try tmp.dir.writeFile(io, .{ .sub_path = "demo.zip", .data = archive });
+
+    const manifest_path = try std.fmt.allocPrint(allocator, "{s}/app.json", .{root});
+    defer allocator.free(manifest_path);
+    const archive_path = try std.fmt.allocPrint(allocator, "{s}/demo.zip", .{root});
+    defer allocator.free(archive_path);
+    const key_path = try std.fmt.allocPrint(allocator, "{s}/release.key", .{root});
+    defer allocator.free(key_path);
+    const output_path = try std.fmt.allocPrint(allocator, "{s}/native-update.json", .{root});
+    defer allocator.free(output_path);
+    const common = [_][]const u8{ "--private-key", key_path, "--manifest", manifest_path, "--archive", archive_path, "--output", output_path };
+
+    try sign(allocator, io, &(common ++ [_][]const u8{ "--url", "https://example.com/demo-1.2.3.zip", "--target", "windows-x86_64" }));
+    try std.testing.expectError(error.UpdateArchitectureMismatch, sign(allocator, io, &(common ++ [_][]const u8{ "--url", "https://example.com/demo-1.2.3.zip", "--target", "windows-aarch64" })));
+
+    const local_url = "http://127.0.0.1:8080/demo-1.2.3.zip";
+    try std.testing.expectError(error.InvalidArchiveUrl, sign(allocator, io, &(common ++ [_][]const u8{ "--url", local_url, "--target", "windows-x86_64" })));
+    try sign(allocator, io, &(common ++ [_][]const u8{ "--url", local_url, "--target", "windows-x86_64", "--allow-loopback-http" }));
+    const feed = try std.Io.Dir.cwd().readFileAlloc(io, output_path, allocator, .limited(update_feed.max_envelope_bytes));
+    defer allocator.free(feed);
+    try std.testing.expectError(error.InvalidUpdatePayload, update_feed.verifyEnvelope(allocator, feed, "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo="));
+    var verified = try update_feed.verifyEnvelopeWithPolicy(allocator, feed, "wFDFY3pE+oYp//PMzOIwDLNipj2Z2V/FQUUmb0MyRFo=", .{ .allow_loopback_http = true });
+    defer verified.deinit(allocator);
+    try std.testing.expectEqualStrings(local_url, verified.release.archive_url);
+}

package/src/tooling/windows_installer.zig

@@ -0,0 +1,245 @@
+//! `native package --target windows --installer`: turns the Windows
+//! artifact directory into a per-user setup program.
+//!
+//! The artifact directory becomes the install image: it gains
+//! `native-install.json` (the install configuration) and
+//! `native-launcher.exe` (the launcher the setup program copies to the
+//! stable `<root>\<name>.exe`). setup.exe is the launcher program with the
+//! configuration and a ZIP of the image appended, followed by a trailer
+//! carrying their SHA-256 (src/windows_install/payload.zig).
+
+const std = @import("std");
+const manifest_tool = @import("manifest.zig");
+const package = @import("package.zig");
+const zip_writer = @import("zip_writer.zig");
+const install_config = @import("windows_install_config");
+const setup_payload = @import("windows_install_payload");
+
+pub const launcher_file_in_image = "native-launcher.exe";
+pub const launcher_x86_64 = @embedFile("windows_launcher_x86_64");
+pub const launcher_aarch64 = @embedFile("windows_launcher_aarch64");
+
+pub const Arch = enum {
+    x86_64,
+    aarch64,
+
+    pub fn launcher(self: Arch) []const u8 {
+        return switch (self) {
+            .x86_64 => launcher_x86_64,
+            .aarch64 => launcher_aarch64,
+        };
+    }
+};
+
+pub const Options = struct {
+    /// The Windows artifact directory `native package` just staged.
+    artifact_dir: []const u8,
+    metadata: manifest_tool.Metadata,
+    /// The app executable's file name in `bin\`.
+    executable: []const u8,
+    arch: Arch,
+    output_path: []const u8,
+};
+
+/// The setup program's file name: `<name>-<version>-windows-<arch>-setup.exe`.
+pub fn setupFileName(allocator: std.mem.Allocator, metadata: manifest_tool.Metadata, arch: Arch) ![]const u8 {
+    return std.fmt.allocPrint(allocator, "{s}-{s}-windows-{s}-setup.exe", .{ metadata.name, metadata.version, @tagName(arch) });
+}
+
+/// The update archive's file name: `<name>-<version>-windows-<arch>-update.zip`.
+pub fn updateArchiveFileName(allocator: std.mem.Allocator, metadata: manifest_tool.Metadata, arch: Arch) ![]const u8 {
+    return std.fmt.allocPrint(allocator, "{s}-{s}-windows-{s}-update.zip", .{ metadata.name, metadata.version, @tagName(arch) });
+}
+
+pub fn createSetup(allocator: std.mem.Allocator, io: std.Io, options: Options) !void {
+    var arena_state = std.heap.ArenaAllocator.init(allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const image = try buildImage(arena, io, options);
+
+    const program = options.arch.launcher();
+    const trailer = setup_payload.encode(.{
+        .config_offset = program.len,
+        .config_size = image.config.len,
+        .zip_offset = program.len + image.config.len,
+        .zip_size = image.zip.len,
+        .sha256 = setup_payload.digest(image.config, image.zip),
+    });
+    try writeAtomically(io, options.output_path, &.{ program, image.config, image.zip, &trailer });
+}
+
+/// The ZIP of the install image the updater downloads: the same image a
+/// setup program carries, signed into a feed by `native update sign`.
+pub fn createUpdateArchive(allocator: std.mem.Allocator, io: std.Io, options: Options) !void {
+    var arena_state = std.heap.ArenaAllocator.init(allocator);
+    defer arena_state.deinit();
+    const image = try buildImage(arena_state.allocator(), io, options);
+    try writeAtomically(io, options.output_path, &.{image.zip});
+}
+
+const Image = struct {
+    config: []const u8,
+    zip: []const u8,
+};
+
+/// Adds the install configuration and launcher to the artifact directory
+/// and zips it, without the portable registration script.
+fn buildImage(arena: std.mem.Allocator, io: std.Io, options: Options) !Image {
+    var artifact = try std.Io.Dir.cwd().openDir(io, options.artifact_dir, .{});
+    defer artifact.close(io);
+    const has_icon = if (artifact.access(io, "app-icon.ico", .{})) |_| true else |_| false;
+    const config = try installConfig(arena, options.metadata, options.executable, has_icon);
+    try install_config.validate(config);
+
+    var config_writer: std.Io.Writer.Allocating = .init(arena);
+    try install_config.write(config, &config_writer.writer);
+    const config_bytes = config_writer.written();
+    try artifact.writeFile(io, .{ .sub_path = install_config.file_name, .data = config_bytes });
+    try artifact.writeFile(io, .{ .sub_path = launcher_file_in_image, .data = options.arch.launcher() });
+
+    const collected = try zip_writer.collectDirectory(arena, io, options.artifact_dir);
+    var image: std.ArrayList(zip_writer.Entry) = .empty;
+    for (collected) |entry| {
+        // The portable artifact's registration script points at bin\; an
+        // installed app registers through the setup program instead.
+        if (std.mem.startsWith(u8, entry.name, "install/")) continue;
+        try image.append(arena, entry);
+    }
+    var zip: std.Io.Writer.Allocating = .init(arena);
+    try zip_writer.write(arena, &zip.writer, image.items);
+    return .{ .config = config_bytes, .zip = zip.written() };
+}
+
+fn writeAtomically(io: std.Io, path: []const u8, parts: []const []const u8) !void {
+    if (std.fs.path.dirname(path)) |parent| try std.Io.Dir.cwd().createDirPath(io, parent);
+    var atomic = try std.Io.Dir.cwd().createFileAtomic(io, path, .{ .make_path = true, .replace = true });
+    defer atomic.deinit(io);
+    var buffer: [64 * 1024]u8 = undefined;
+    var writer = atomic.file.writer(io, &buffer);
+    for (parts) |part| try writer.interface.writeAll(part);
+    try writer.interface.flush();
+    try atomic.replace(io);
+}
+
+/// The install configuration for an app: its identity, executable and
+/// icon, and the HKCU\Software\Classes values its file associations and
+/// URL schemes need, pointing at the installed launcher so a pending
+/// version switch also applies when a document or link opens the app.
+pub fn installConfig(allocator: std.mem.Allocator, metadata: manifest_tool.Metadata, executable: []const u8, has_icon: bool) !install_config.InstallConfig {
+    var registry: std.ArrayList(install_config.RegistryValue) = .empty;
+    var cleanup: std.ArrayList(install_config.RegistryCleanup) = .empty;
+    const open_command = "\"" ++ install_config.launcher_placeholder ++ "\" \"%1\"";
+    const document_icon = if (has_icon) install_config.install_placeholder ++ "\\app\\app-icon.ico" else install_config.launcher_placeholder;
+
+    for (metadata.file_associations) |association| {
+        const prog_id = try package.windowsProgId(allocator, metadata, association);
+        const prog_key = try std.fmt.allocPrint(allocator, "Software\\Classes\\{s}", .{prog_id});
+        for (association.extensions) |extension| {
+            const extension_key = try std.fmt.allocPrint(allocator, "Software\\Classes\\.{s}", .{package.trimExtensionDot(extension)});
+            try registry.append(allocator, .{ .key = extension_key, .value = prog_id });
+            try cleanup.append(allocator, .{ .key = extension_key, .name = "", .if_value = prog_id });
+        }
+        try registry.append(allocator, .{ .key = prog_key, .value = association.name });
+        try registry.append(allocator, .{ .key = prog_key, .name = "FriendlyTypeName", .value = association.name });
+        try registry.append(allocator, .{ .key = try std.fmt.allocPrint(allocator, "{s}\\DefaultIcon", .{prog_key}), .value = document_icon });
+        try registry.append(allocator, .{ .key = try std.fmt.allocPrint(allocator, "{s}\\shell\\open\\command", .{prog_key}), .value = open_command });
+        try cleanup.append(allocator, .{ .key = prog_key });
+    }
+    for (metadata.url_schemes) |url_scheme| {
+        const scheme_key = try std.fmt.allocPrint(allocator, "Software\\Classes\\{s}", .{url_scheme.scheme});
+        try registry.append(allocator, .{ .key = scheme_key, .value = try std.fmt.allocPrint(allocator, "URL:{s}", .{url_scheme.scheme}) });
+        try registry.append(allocator, .{ .key = scheme_key, .name = "URL Protocol", .value = "" });
+        try registry.append(allocator, .{ .key = try std.fmt.allocPrint(allocator, "{s}\\shell\\open\\command", .{scheme_key}), .value = open_command });
+        try cleanup.append(allocator, .{ .key = scheme_key });
+    }
+
+    return .{
+        .bundle_id = metadata.id,
+        .name = metadata.name,
+        .display_name = metadata.displayName(),
+        .version = metadata.version,
+        .executable = executable,
+        .icon = if (has_icon) "app-icon.ico" else "",
+        .registry = try registry.toOwnedSlice(allocator),
+        .registry_cleanup = try cleanup.toOwnedSlice(allocator),
+    };
+}
+
+test "an app's associations and URL schemes register through the installed launcher" {
+    var arena_state = std.heap.ArenaAllocator.init(std.testing.allocator);
+    defer arena_state.deinit();
+    const arena = arena_state.allocator();
+    const associations = [_]manifest_tool.FileAssociationMetadata{.{ .name = "Markdown", .extensions = &.{"md"} }};
+    const schemes = [_]manifest_tool.UrlSchemeMetadata{.{ .scheme = "acme-notes" }};
+    const metadata: manifest_tool.Metadata = .{
+        .id = "dev.example.notes",
+        .name = "notes",
+        .display_name = "Acme Notes",
+        .version = "1.2.3",
+        .file_associations = &associations,
+        .url_schemes = &schemes,
+    };
+    const config = try installConfig(arena, metadata, "notes.exe", true);
+    try install_config.validate(config);
+    try std.testing.expectEqualStrings("Acme Notes", config.display_name);
+    try std.testing.expectEqualStrings("app-icon.ico", config.icon);
+    try std.testing.expectEqualStrings("Software\\Classes\\.md", config.registry[0].key);
+    try std.testing.expectEqualStrings("dev.example.notes.Markdown", config.registry[0].value);
+    try std.testing.expectEqualStrings("\"{launcher}\" \"%1\"", config.registry[4].value);
+    try std.testing.expectEqualStrings("Software\\Classes\\acme-notes\\shell\\open\\command", config.registry[7].key);
+    // The extension's default value goes only while it still names this
+    // app; the app's own ProgID and scheme keys go whole.
+    try std.testing.expectEqualStrings("dev.example.notes.Markdown", config.registry_cleanup[0].if_value.?);
+    try std.testing.expect(config.registry_cleanup[1].name == null);
+}
+
+test "setup.exe carries the launcher, its configuration and the install image" {
+    const allocator = std.testing.allocator;
+    const io = std.testing.io;
+    var cwd = std.Io.Dir.cwd();
+    const root = ".zig-cache/test-windows-setup";
+    try cwd.deleteTree(io, root);
+    defer cwd.deleteTree(io, root) catch {};
+    try cwd.createDirPath(io, root ++ "/artifact/bin");
+    try cwd.createDirPath(io, root ++ "/artifact/install");
+    try cwd.writeFile(io, .{ .sub_path = root ++ "/artifact/bin/notes.exe", .data = "app" });
+    try cwd.writeFile(io, .{ .sub_path = root ++ "/artifact/install/register-file-types.ps1", .data = "script" });
+    try cwd.writeFile(io, .{ .sub_path = root ++ "/artifact/app-icon.ico", .data = "icon" });
+
+    const metadata: manifest_tool.Metadata = .{ .id = "dev.example.notes", .name = "notes", .version = "1.2.3" };
+    try createSetup(allocator, io, .{ .artifact_dir = root ++ "/artifact", .metadata = metadata, .executable = "notes.exe", .arch = .x86_64, .output_path = root ++ "/notes-setup.exe" });
+
+    const setup = try cwd.readFileAlloc(io, root ++ "/notes-setup.exe", allocator, .unlimited);
+    defer allocator.free(setup);
+    try std.testing.expect(std.mem.startsWith(u8, setup, launcher_x86_64));
+    const trailer = setup_payload.find(setup[setup.len - setup_payload.trailer_len ..], setup.len).?;
+    try std.testing.expectEqual(@as(u64, launcher_x86_64.len), trailer.config_offset);
+    const config_bytes = setup[@intCast(trailer.config_offset)..][0..@intCast(trailer.config_size)];
+    const zip_bytes = setup[@intCast(trailer.zip_offset)..][0..@intCast(trailer.zip_size)];
+    try std.testing.expectEqualSlices(u8, &trailer.sha256, &setup_payload.digest(config_bytes, zip_bytes));
+    var parsed = try install_config.parse(allocator, config_bytes);
+    defer parsed.deinit();
+    try std.testing.expectEqualStrings("notes", parsed.value.name);
+
+    try cwd.writeFile(io, .{ .sub_path = root ++ "/image.zip", .data = zip_bytes });
+    try cwd.createDirPath(io, root ++ "/extracted");
+    var extracted = try cwd.openDir(io, root ++ "/extracted", .{});
+    defer extracted.close(io);
+    var archive = try cwd.openFile(io, root ++ "/image.zip", .{});
+    defer archive.close(io);
+    var buffer: [4096]u8 = undefined;
+    var reader = archive.reader(io, &buffer);
+    try std.zip.extract(extracted, &reader, .{});
+    const launcher = try extracted.readFileAlloc(io, launcher_file_in_image, allocator, .unlimited);
+    defer allocator.free(launcher);
+    try std.testing.expectEqualSlices(u8, launcher_x86_64, launcher);
+    try std.testing.expectError(error.FileNotFound, extracted.access(io, "install/register-file-types.ps1", .{}));
+    try extracted.access(io, "bin/notes.exe", .{});
+    try extracted.access(io, install_config.file_name, .{});
+
+    // The updater downloads the very image the setup program carries.
+    try createUpdateArchive(allocator, io, .{ .artifact_dir = root ++ "/artifact", .metadata = metadata, .executable = "notes.exe", .arch = .x86_64, .output_path = root ++ "/notes-update.zip" });
+    const update_archive = try cwd.readFileAlloc(io, root ++ "/notes-update.zip", allocator, .unlimited);
+    defer allocator.free(update_archive);
+    try std.testing.expectEqualSlices(u8, zip_bytes, update_archive);
+}