@mpgd/cli 0.47.0 → 0.49.0

package/dist/windows-host/README.md

@@ -0,0 +1,118 @@
+# Microsoft Store native host support
+
+These C# sources ship inside the existing `@mpgd/cli` npm package. No additional
+npm or NuGet package is required. The core targets .NET 8 without SDK or NuGet
+dependencies. The optional WinUI files compile inside your existing Windows
+App SDK / WebView2 host.
+
+```js
+import { getMicrosoftStoreNativeHostSourceDirectory } from '@mpgd/cli/windows-native-tools';
+const sources = getMicrosoftStoreNativeHostSourceDirectory();
+```
+
+The locator returns the installed `dist/windows-host` directory. SDK-dependent
+sources are maintained in `native-plugins/microsoft-store-host/windows` and copied
+there during the CLI build. SDK-independent sources stay in the CLI source tree.
+
+Copy the source tree into a game-owned, ignored build directory. Reference
+`Core/Mpgd.MicrosoftStore.Host.csproj` or link `Core/*.cs` directly; link
+`WinUI/*.cs` only into a Windows host. Keep `bin` and `obj` outside the installed
+npm package. CI builds and exercises these files after packing and installing
+the CLI, without relying on a workspace project reference.
+
+## Attach to a window
+
+On the window's UI thread, initialize WebView2, then attach before navigating:
+
+```csharp
+await webView.EnsureCoreWebView2Async();
+StoreContext store = WindowStoreContext.Create(window);
+var bridge = await WebView2NativeBridge.AttachAsync(
+    webView, new Uri(gameConfiguration.StartUri),
+    gameConfiguration.AllowedItemIds, gameOwnedOperations);
+window.Closed += (_, _) => bridge.Dispose();
+webView.CoreWebView2.Navigate(gameConfiguration.StartUri);
+```
+
+The adapter checks HTTPS host and port, rejects credentials in navigation URLs,
+blocks new windows, disables host objects and devtools, and accepts messages
+from a committed, allowed document as it starts loading, including startup
+requests before the load-complete event. Failed navigation and every accepted navigation
+start invalidates the document. Blocked external navigation keeps the intact
+page's bridge active. Browser or main renderer exit invalidates it; auto-recovered
+GPU, utility and subframe failures and renderer unresponsiveness preserve it.
+Queued operations are cancelled and late replies from the previous document are
+suppressed, including navigation
+back to the same URL. Closure detaches handlers and suppresses responses. Use
+one adapter and operation implementation per window.
+
+Await `AttachAsync` before navigating. It installs a document-created script
+that wraps only the native v1 requests with a random per-document nonce; the
+public TypeScript client and v1 payload remain unchanged. Incoming messages must
+match the live document's nonce after a navigation recheck, so queued messages
+from an old page cannot start checkout after a same-origin reload. Other WebView2
+message protocols are preserved. Disposing removes the script registration.
+
+`WindowStoreContext.Create` initializes the SDK with that window's HWND on its
+UI thread. Keep the context in native code. Initialization does not perform
+login, checkout or grant an entitlement.
+
+## Game-owned operations
+
+Implement `INativeStoreOperations` with typed callbacks for catalog, sign-in,
+purchase listing and checkout. Callbacks begin on the window UI thread and are
+serialized. Observe cancellation whenever the SDK permits it. An SDK operation
+that ignores cancellation retains its serialization lease until it finishes;
+its result is still suppressed after navigation or closure.
+
+The common code parses `mpgd.microsoft-store.native.v1`, enforces message limits,
+allowed products, duplicate IDs and pending-request limits, and serializes only
+the declared bounded result records. Invalid results and unexpected exceptions
+become `NATIVE_OPERATION_FAILED`; exception messages never reach the web page.
+Use `NativeBridgeOperationException` for declared user-cancelled,
+identity-unavailable or store-unavailable errors.
+User cancellation of a purchase callback produces a `not-purchased` result,
+matching the existing web commerce runtime's abort semantics.
+
+The game owns Store IDs and offers, MSAL/WAM account selection, backend endpoints,
+SDK product validation and session issuance. Sign-in returns the game backend's
+short-lived player session, never an SDK access token. Collections IDs, Microsoft
+service tickets and account credentials stay in private native/backend state.
+Client checkout produces evidence; the backend ledger verifies and commits all
+durable grants.
+
+`NativePlayerSession.ExpiresAt` uses Unix epoch milliseconds, with 2 minutes to
+24 hours remaining at serialization, leaving a minute of transport headroom
+above the web client's 1-minute acceptance minimum. It accepts a bounded player ID
+and a whitespace-free token of 32–4096 characters. Games may enforce a lower
+maximum lifetime. Product and purchase results must refer to their allowlist. Purchase
+tokens equal their item ID, matching the existing web client contract; the
+authoritative backend still verifies and commits the purchase.
+
+## Core-only integration
+
+For a custom transport, construct `NativeBridgeHost` with an
+`INativeBridgeDispatcher`. Run queued callbacks on the owning UI thread, prevent
+cancelled queued callbacks from starting, and await started operations until
+they finish. `postResponse` synchronously sends JSON on that thread. Call
+`InvalidateDocument` at every accepted navigation start, `ActivateDocument` only after an
+allowed document commits, invalidate again on load failure, and `Dispose` at
+closure. Invalidate on process failure only when the top-level document exits;
+auto-recovered helper/subframe failures retain it. Lifecycle calls
+and response delivery must share the window UI dispatcher.
+Authenticate each incoming message's document generation before calling the
+host; a source URI alone cannot distinguish queued messages after a same-origin
+reload. The WinUI adapter supplies this transport check automatically.
+
+## Acceptance scope
+
+Contract tests cover two independent game configurations, protocol and product
+rejection, sanitized errors, duplicate/busy requests, cancelled queues, navigation
+generation and closure. Windows CI links the installed package's core and WinUI
+sources into x64/ARM64 MSIX, binds StoreContext to the native window, and exercises
+four methods through WebView2 with fixture callbacks. It also checks requests
+before load completion, real blocked external navigation, and simulated
+recoverable process notification kinds on the live adapter. It does not terminate
+GPU processes. Receipts identify fixture
+results separately. They do not claim real Store login, settled purchases,
+backend grants or Store upload.

package/dist/windows-host/WinUI/DispatcherQueueBridgeDispatcher.cs

@@ -0,0 +1,39 @@
+using Microsoft.UI.Dispatching;
+
+namespace Mpgd.MicrosoftStore.Host;
+
+public sealed class DispatcherQueueBridgeDispatcher(DispatcherQueue queue) : INativeBridgeDispatcher
+{
+    public async Task RunAsync(Func<Task> callback, CancellationToken cancellation)
+    {
+        ArgumentNullException.ThrowIfNull(callback);
+        cancellation.ThrowIfCancellationRequested();
+        if (queue.HasThreadAccess)
+        {
+            await callback();
+            return;
+        }
+        var completion = new TaskCompletionSource(TaskCreationOptions.RunContinuationsAsynchronously);
+        int state = 0; // queued, running, cancelled-before-start
+        using var registration = cancellation.Register(() =>
+        {
+            if (Interlocked.CompareExchange(ref state, 2, 0) == 0)
+                completion.TrySetCanceled(cancellation);
+        });
+        if (!queue.TryEnqueue(async () =>
+        {
+            if (Interlocked.CompareExchange(ref state, 1, 0) != 0) return;
+            try
+            {
+                cancellation.ThrowIfCancellationRequested();
+                await callback();
+                completion.TrySetResult();
+            }
+            catch (OperationCanceledException error) { completion.TrySetCanceled(error.CancellationToken); }
+            catch (Exception error) { completion.TrySetException(error); }
+        })) completion.TrySetException(new InvalidOperationException("The window dispatcher is unavailable."));
+        // After starting, wait for the native operation to finish even if it
+        // ignores cancellation; the host's serialization lease must stay held.
+        await completion.Task.ConfigureAwait(false);
+    }
+}

package/dist/windows-host/WinUI/WebView2DocumentTransport.cs

@@ -0,0 +1,46 @@
+using System.Text.Json;
+
+namespace Mpgd.MicrosoftStore.Host;
+
+// The public v1 request stays unchanged inside a document-scoped envelope.
+internal static class WebView2DocumentTransport
+{
+    internal const string Protocol = "mpgd.microsoft-store.document.v1";
+    internal const string ReadNonceScript = "globalThis.__mpgdMicrosoftStoreDocumentNonce ?? null";
+    internal const string Bootstrap = """
+        (() => {
+            const view = globalThis.chrome?.webview;
+            if (!view) return;
+            const nonce = Array.from(crypto.getRandomValues(new Uint8Array(16)),
+                byte => byte.toString(16).padStart(2, '0')).join('');
+            const post = view.postMessage.bind(view);
+            Object.defineProperty(globalThis, '__mpgdMicrosoftStoreDocumentNonce', { value: nonce });
+            Object.defineProperty(view, 'postMessage', {
+                writable: false, configurable: false,
+                value: message => post(message?.protocol === 'mpgd.microsoft-store.native.v1'
+                    ? { transport: 'mpgd.microsoft-store.document.v1', documentNonce: nonce, request: message }
+                    : message),
+            });
+        })();
+        """;
+
+    internal static bool TryReadRequest(string json, out string nonce, out string request)
+    {
+        nonce = request = "";
+        if (string.IsNullOrEmpty(json) || json.Length > NativeBridgeProtocol.MaximumMessageLength + 512) return false;
+        try
+        {
+            using var document = JsonDocument.Parse(json, new JsonDocumentOptions { MaxDepth = 10 });
+            var root = document.RootElement;
+            if (root.ValueKind != JsonValueKind.Object || root.EnumerateObject().Count() != 3
+                || !root.TryGetProperty("transport", out var transport) || transport.ValueKind != JsonValueKind.String || transport.GetString() != Protocol
+                || !root.TryGetProperty("documentNonce", out var token) || token.ValueKind != JsonValueKind.String
+                || !Guid.TryParseExact(token.GetString(), "N", out _)
+                || !root.TryGetProperty("request", out var payload) || payload.ValueKind != JsonValueKind.Object) return false;
+            nonce = token.GetString()!;
+            request = payload.GetRawText();
+            return request.Length <= NativeBridgeProtocol.MaximumMessageLength;
+        }
+        catch (JsonException) { return false; }
+    }
+}

package/dist/windows-host/WinUI/WebView2NativeBridge.cs

@@ -0,0 +1,185 @@
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.Web.WebView2.Core;
+using System.Text.Json;
+
+namespace Mpgd.MicrosoftStore.Host;
+
+/// <summary>Attach after EnsureCoreWebView2Async, before the first navigation.
+/// Dispose on Window.Closed. Host objects and devtools are disabled.</summary>
+public sealed class WebView2NativeBridge : IDisposable
+{
+    private readonly WebView2 view;
+    private readonly CoreWebView2 core;
+    private readonly NativeBridgeOrigin origin;
+    private readonly NativeBridgeHost host;
+    private readonly Action<Exception>? onTransportError;
+    private ulong navigationId;
+    private bool documentActivated;
+    private bool documentRejected;
+    private bool navigationRejected;
+    private bool navigationCommitted;
+    private string? lastCommittedSource;
+    private bool closed;
+    private string? bootstrapScriptId;
+    private int pendingDocumentChecks;
+
+    private WebView2NativeBridge(WebView2 view, Uri startUri, IEnumerable<string> allowedItemIds,
+        INativeStoreOperations operations, Action<Exception>? onTransportError = null)
+    {
+        ArgumentNullException.ThrowIfNull(view);
+        if (!view.DispatcherQueue.HasThreadAccess)
+            throw new InvalidOperationException("Attach the bridge on the window's UI thread.");
+        this.view = view;
+        core = view.CoreWebView2 ?? throw new InvalidOperationException("Initialize WebView2 before attaching the bridge.");
+        origin = new(startUri);
+        this.onTransportError = onTransportError;
+        host = new(origin, allowedItemIds, operations, new DispatcherQueueBridgeDispatcher(view.DispatcherQueue),
+            response => core.PostWebMessageAsJson(response));
+        core.Settings.AreDevToolsEnabled = false;
+        core.Settings.AreHostObjectsAllowed = false;
+        core.NavigationStarting += NavigationStarting;
+        core.ContentLoading += ContentLoading;
+        core.NavigationCompleted += NavigationCompleted;
+        core.NewWindowRequested += NewWindowRequested;
+        core.WebMessageReceived += WebMessageReceived;
+        core.ProcessFailed += ProcessFailed;
+    }
+
+    public static async Task<WebView2NativeBridge> AttachAsync(WebView2 view, Uri startUri,
+        IEnumerable<string> allowedItemIds, INativeStoreOperations operations, Action<Exception>? onTransportError = null)
+    {
+        var bridge = new WebView2NativeBridge(view, startUri, allowedItemIds, operations, onTransportError);
+        try
+        {
+            // Register before the first navigation so even boot-time requests
+            // carry the nonce of the document that actually posted them.
+            bridge.bootstrapScriptId = await bridge.core.AddScriptToExecuteOnDocumentCreatedAsync(WebView2DocumentTransport.Bootstrap);
+            return bridge;
+        }
+        catch { bridge.Dispose(); throw; }
+    }
+
+    private void NavigationStarting(object? sender, CoreWebView2NavigationStartingEventArgs args)
+    {
+        if (!origin.Allows(args.Uri))
+        {
+            args.Cancel = true;
+            // A cancelled navigation keeps the previous document. A blocked
+            // redirect can follow an allowed start that already revoked it.
+            if (args.NavigationId == navigationId)
+            {
+                navigationRejected = true;
+                if (!documentActivated && lastCommittedSource is not null)
+                    documentActivated = host.ActivateDocument(lastCommittedSource);
+            }
+            return;
+        }
+        navigationId = args.NavigationId;
+        documentActivated = false;
+        documentRejected = false;
+        navigationRejected = false;
+        navigationCommitted = false;
+        host.InvalidateDocument();
+    }
+
+    private void ContentLoading(object? sender, CoreWebView2ContentLoadingEventArgs args)
+    {
+        if (closed || args.NavigationId != navigationId || navigationRejected) return;
+        navigationCommitted = true;
+        documentRejected = args.IsErrorPage;
+        // The new document is committed before its startup scripts can send
+        // messages. Waiting for NavigationCompleted drops valid boot requests.
+        if (!documentRejected) documentActivated = host.ActivateDocument(core.Source);
+        else
+        {
+            documentActivated = false;
+            host.InvalidateDocument();
+        }
+        lastCommittedSource = documentActivated ? core.Source : null;
+    }
+
+    private void NavigationCompleted(object? sender, CoreWebView2NavigationCompletedEventArgs args)
+    {
+        if (closed || args.NavigationId != navigationId || navigationRejected) return;
+        if (!args.IsSuccess)
+        {
+            if (args.WebErrorStatus == CoreWebView2WebErrorStatus.OperationCanceled && documentActivated && !documentRejected)
+                return; // The committed page remains usable after a cancelled load.
+            if (!navigationCommitted && lastCommittedSource is not null)
+            {
+                documentActivated = host.ActivateDocument(lastCommittedSource);
+                return;
+            }
+            documentActivated = false;
+            lastCommittedSource = null;
+            host.InvalidateDocument();
+        }
+        else if (!documentActivated && !documentRejected)
+        {
+            documentActivated = host.ActivateDocument(core.Source);
+            lastCommittedSource = documentActivated ? core.Source : null;
+        }
+    }
+
+    private static void NewWindowRequested(object? sender, CoreWebView2NewWindowRequestedEventArgs args) => args.Handled = true;
+
+    private void ProcessFailed(object? sender, CoreWebView2ProcessFailedEventArgs args) =>
+        HandleProcessFailure(args.ProcessFailedKind);
+
+    internal void HandleProcessFailure(CoreWebView2ProcessFailedKind kind)
+    {
+        // GPU/utility/subframe failures and an unresponsive renderer leave the
+        // top-level document intact or recover without a new navigation.
+        if (closed || kind is not (CoreWebView2ProcessFailedKind.BrowserProcessExited
+            or CoreWebView2ProcessFailedKind.RenderProcessExited)) return;
+        documentActivated = false;
+        lastCommittedSource = null;
+        host.InvalidateDocument();
+    }
+
+    private async void WebMessageReceived(object? sender, CoreWebView2WebMessageReceivedEventArgs args)
+    {
+        if (closed) return;
+        try { await HandleTransportMessageAsync(args.Source, args.WebMessageAsJson); }
+        catch (Exception error) { onTransportError?.Invoke(error); }
+    }
+
+    internal async Task HandleTransportMessageAsync(string source, string json)
+    {
+        if (closed || !documentActivated || !origin.Allows(source) || pendingDocumentChecks >= 64
+            || !WebView2DocumentTransport.TryReadRequest(json, out var nonce, out var request)) return;
+        ulong currentNavigation = navigationId;
+        pendingDocumentChecks++;
+        try
+        {
+            // WebMessageReceived can arrive after a same-origin reload commits.
+            // Read the live document, then recheck navigation before entering
+            // the host. Origin alone cannot authenticate a queued old message.
+            string liveNonce = await core.ExecuteScriptAsync(WebView2DocumentTransport.ReadNonceScript);
+            if (closed || currentNavigation != navigationId || !documentActivated
+                || JsonSerializer.Deserialize<string>(liveNonce) != nonce) return;
+            await host.HandleMessageAsync(source, request);
+        }
+        finally { pendingDocumentChecks--; }
+    }
+
+    public void Dispose()
+    {
+        if (!view.DispatcherQueue.HasThreadAccess)
+            throw new InvalidOperationException("Detach the bridge on the window's UI thread.");
+        if (closed) return;
+        closed = true;
+        host.Dispose();
+        core.NavigationStarting -= NavigationStarting;
+        core.ContentLoading -= ContentLoading;
+        core.NavigationCompleted -= NavigationCompleted;
+        core.NewWindowRequested -= NewWindowRequested;
+        core.WebMessageReceived -= WebMessageReceived;
+        core.ProcessFailed -= ProcessFailed;
+        if (bootstrapScriptId is not null)
+        {
+            try { core.RemoveScriptToExecuteOnDocumentCreated(bootstrapScriptId); }
+            catch (Exception error) when (error is InvalidOperationException or System.Runtime.InteropServices.COMException) { }
+        }
+    }
+}

package/dist/windows-host/WinUI/WindowStoreContext.cs

@@ -0,0 +1,20 @@
+using Microsoft.UI.Xaml;
+using Windows.Services.Store;
+
+namespace Mpgd.MicrosoftStore.Host;
+
+/// <summary>Call on the owning window's UI thread before starting Store UI.</summary>
+public static class WindowStoreContext
+{
+    public static StoreContext Create(Window window)
+    {
+        ArgumentNullException.ThrowIfNull(window);
+        if (!window.DispatcherQueue.HasThreadAccess)
+            throw new InvalidOperationException("StoreContext must be initialized on its window's UI thread.");
+        var handle = WinRT.Interop.WindowNative.GetWindowHandle(window);
+        if (handle == IntPtr.Zero) throw new InvalidOperationException("The native window is not initialized.");
+        var context = StoreContext.GetDefault();
+        WinRT.Interop.InitializeWithWindow.Initialize(context, handle);
+        return context;
+    }
+}

package/dist/windows-native-tools.d.ts

@@ -0,0 +1,4 @@
+/** Locate the PowerShell 5.1 MSIX acceptance module shipped with this CLI. */
+export declare function getMicrosoftStoreNativeAcceptanceModulePath(): string;
+/** Locate the C# core and WinUI integration sources shipped with this CLI. */
+export declare function getMicrosoftStoreNativeHostSourceDirectory(): string;

package/dist/windows-native-tools.js

@@ -0,0 +1,21 @@
+import { statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Locate the PowerShell 5.1 MSIX acceptance module shipped with this CLI. */
+export function getMicrosoftStoreNativeAcceptanceModulePath() {
+    const modulePath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../native-tools/windows-msix/WindowsMsixAcceptance.psm1');
+    if (!statSync(modulePath).isFile()) {
+        throw new Error('The installed CLI is missing its Windows MSIX acceptance module.');
+    }
+    return modulePath;
+}
+/** Locate the C# core and WinUI integration sources shipped with this CLI. */
+export function getMicrosoftStoreNativeHostSourceDirectory() {
+    const sourceDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), './windows-host');
+    for (const file of ['Core/Mpgd.MicrosoftStore.Host.csproj', 'WinUI/WebView2NativeBridge.cs']) {
+        if (!statSync(path.join(sourceDirectory, file)).isFile()) {
+            throw new Error('The installed CLI is missing its Microsoft Store native host sources.');
+        }
+    }
+    return sourceDirectory;
+}