WallpaperAgent

Problem

Updating a wallpaper on one computer is simple. Updating desktop and lock-screen content across managed Windows endpoints is a software-distribution problem.

The solution must support multiple users, survive restarts, apply changes without rebuilding the Intune package, keep publishing credentials off endpoints, validate remote content, avoid partially activated releases, and preserve the current working state when the network or publishing process fails.

A single script running in one security context cannot satisfy every requirement safely. Machine-level downloads and shared state require elevated access, while desktop and lock-screen changes belong to the signed-in user’s profile.

Solution

WallpaperAgent separates three responsibilities:

1. an external publishing process writes images and a versioned manifest to a content repository or HTTPS origin;
2. a machine task running as SYSTEM downloads and validates candidate content;
3. an interactive-user task applies only the validated assets to the current profile.

The agent code and the visual content have independent lifecycles. A new campaign can be published by adding the assets and updating manifest.json, without rebuilding or redistributing the .intunewin package.

Endpoints receive no repository write credential. They use anonymous or controlled read-only HTTPS access, while publishing credentials remain only on the authorized publishing service.

Manifest and validation contract

The versioned manifest describes one combined release containing desktop and lock-screen assets. Each asset declares a leaf file name, absolute HTTPS URL, version, and SHA-256 digest.

Before a candidate release can become active, the updater validates:

• manifest size, JSON structure, schema version, and required fields;
• release and asset versions;
• absolute HTTPS URLs;
• file names that contain no directory paths;
• an allowlist of .jpg, .jpeg, and .png extensions;
• configured maximum file sizes;
• SHA-256 format and calculated digest;
• successful image decoding and non-zero dimensions.

HTTPS protects the transport. SHA-256 identifies the exact bytes expected by the publisher. Image decoding confirms that a file with an accepted name and digest can actually be processed as an image.

Atomic promotion and failure safety

Candidate assets are downloaded to uniquely named temporary files. They are moved into their final locations only after all validation succeeds.

The machine’s current.json is updated atomically after both desktop and lock-screen assets are available. This prevents a mixed release in which one asset belongs to an older campaign.

When a network request fails, the manifest is malformed, a hash is incorrect, an image is corrupted, or an asset is missing, the candidate release is rejected. The previous validated release and its files remain available.

Failure information is recorded in status and rotating logs; the updater does not clear the working state simply because a new release failed.

Privilege separation

The update task runs as SYSTEM and owns downloads, validation, shared assets, machine state, registry detection values, installation files, and scheduled-task definitions.

The apply task runs in the interactive user’s context and owns desktop settings under HKCU, the Windows Runtime lock-screen operation, per-user state under %LOCALAPPDATA%, and correction of manual visual changes.

Standard users receive read and execute access to validated assets but cannot replace the agent, scripts, or shared state. Named mutexes and scheduled-task IgnoreNew settings prevent overlapping executions.

Intune packaging and detection

The repository includes a build script that creates a clean package workspace, generates version-aware detection logic, and can invoke the Microsoft Win32 Content Prep Tool.

The custom detection script verifies the registered product identity and version, installation path, required scripts and module, both scheduled tasks, and that neither task is disabled.

This separates installation state from content state: Intune confirms the expected agent version, machine status reports the latest update result, and per-user state records application to the current profile.

Diagnostics and lifecycle

The project includes installation tests, remote-manifest validation, installed-state validation, diagnostic collection, upgrade support, and uninstallation with -WhatIf.

Downloaded assets are preserved by default during uninstall because Windows may continue referencing their paths. Full cleanup remains available through an explicit option.

Current state

The public repository contains the updater and apply workers, configuration and helper module, installer, uninstaller, tests, diagnostics, package builder, Intune detection, security policy, changelog, and bilingual architecture, configuration, manifest, and deployment documentation.

Organization-specific publishing endpoints, credentials, repository identities, and internal policy details remain outside version control.

What it demonstrates

WallpaperAgent demonstrates secure endpoint content delivery rather than a simple wallpaper script. Code and content are separated, endpoints have read-only access, remote files are treated as untrusted until validated, activation is atomic, privileges are divided by responsibility, and failed updates preserve the last working release.