[CmdPal] Add OAuth sign-in sample and authentication spec

Phase 4 of the built-in Command Palette authentication feature.

Sample (SamplePagesExtension):
- SampleOAuthPage: entry page that offers a demo sign-in and shows a
  graceful message when the host does not support authorization.
- OAuthSignInCommand: runs Authorization Code + PKCE via the Toolkit
  OAuthClient (secretless public client, loopback redirect, Duende public
  demo defaults), optionally persists with CredentialManagerTokenStore,
  then calls ExtensionHost.GoToPageAsync to navigate to the signed-in page.
- SampleSignedInPage: landing page rendering non-sensitive session facts
  only (never the raw token).
- Registered the entry page in SamplesListPage.

Docs:
- src/modules/cmdpal/doc/authentication.md: feature spec covering the
  host-broker vs Toolkit split, a mermaid sequence diagram, the SDK
  contract, capability detection, the security model, token-storage
  guidance, and a bring-your-own-provider GitHub example.

The sample is illustrative. Running it needs a real identity provider and
an interactive browser sign-in, so the live flow was not runtime verified.

Co-authored-by: Copilot App <[email protected]>
Copilot-Session: 2ee31cb3-848f-43ba-ac48-f4e4485baa33

Author: michaeljolley

src/modules/cmdpal/doc/authentication.md

@@ -0,0 +1,245 @@
+# Command Palette authentication
+
+Command Palette can broker interactive OAuth sign-in for extensions. The host owns
+the risky, shared parts of the redirect (opening the browser, allocating and
+hosting the `redirect_uri`, generating and validating `state`, capturing the
+redirect, and re-foregrounding the palette). The extension owns the parts that
+must stay private to it (PKCE, the token exchange, and any token storage). Command
+Palette never sees or stores third-party tokens.
+
+This document describes what shipped across the built-in auth work: the host
+broker, the SDK contract, and the `Microsoft.CommandPalette.Extensions.Toolkit`
+helpers that most extensions should use.
+
+## Overview and motivation
+
+Extensions frequently need to call an authenticated API. Before this feature each
+extension had to stand up its own loopback listener or register a custom URI
+scheme, handle `state`, and re-focus the palette after the browser round trip.
+That is easy to get subtly wrong in ways that are security relevant.
+
+The built-in flow gives every extension a single, hardened redirect broker:
+
+- The host opens the system browser, allocates the `redirect_uri`, injects a
+  cryptographically random `state`, captures the redirect, validates `state`, and
+  returns the captured query parameters to the extension that started the flow.
+- The extension keeps the PKCE verifier and performs the token exchange in its own
+  process. The host only ever handles the front-channel redirect, never the tokens.
+
+## Architecture
+
+There are two cooperating pieces.
+
+1. Host broker (`IExtensionHost2.RequestAuthorizationAsync`). Runs inside Command
+   Palette. It opens the browser, hosts the `redirect_uri`, routes `state`,
+   captures the redirect, and re-foregrounds the palette. It hands back an
+   `IAuthorizationResult` with the exact `redirect_uri` it used and the captured
+   response parameters (with `state` already validated and stripped).
+2. Toolkit `OAuthClient`. Runs inside the extension process. It generates the PKCE
+   verifier and challenge, builds the authorization parameters, calls the host
+   broker, and then exchanges the returned code at the provider token endpoint. It
+   returns an `OAuthToken`.
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant Ext as Extension (OAuthClient)
+    participant Host as Command Palette host (IExtensionHost2)
+    participant Browser as System browser
+    participant Idp as Identity provider
+
+    Ext->>Ext: Generate PKCE verifier and S256 challenge
+    Ext->>Host: RequestAuthorizationAsync(request)
+    Note right of Host: Host allocates redirect_uri<br/>and a random state
+    Host->>Browser: Open authorization endpoint<br/>(client_id, scope, code_challenge, state, redirect_uri)
+    Browser->>Idp: User authenticates and consents
+    Idp-->>Browser: Redirect to redirect_uri?code=...&state=...
+    Browser-->>Host: Redirect captured
+    Host->>Host: Validate state, strip it, re-foreground palette
+    Host-->>Ext: IAuthorizationResult (RedirectUri, code, ...)
+    Ext->>Idp: POST token endpoint<br/>(code, code_verifier, redirect_uri, client_id)
+    Idp-->>Ext: access_token (and optional refresh_token, id_token)
+    Ext->>Ext: Optionally persist via ITokenStore
+    Ext->>Host: GoToPageAsync(signedInPage, Push)
+    Host-->>Ext: Navigates the palette to the signed-in page
+```
+
+## SDK contract
+
+The contract lives in `Microsoft.CommandPalette.Extensions.idl` and is surfaced to
+extensions through the Toolkit.
+
+### `IExtensionHost2`
+
+`IExtensionHost2` extends `IExtensionHost`. A host that implements it supports both
+authorization and host-driven navigation.
+
+- `IAsyncOperation<IAuthorizationResult> RequestAuthorizationAsync(IAuthorizationRequest request)`
+  runs the interactive flow. The returned operation is cancelable.
+- `IAsyncAction GoToPageAsync(ICommand page, NavigationMode navigationMode)`
+  navigates the palette to one of the extension's live page objects. This is how a
+  sign-in command sends the user to a signed-in landing page.
+
+### `IAuthorizationRequest`
+
+What the extension supplies to start a flow:
+
+- `DisplayName`: friendly name shown in the "waiting to sign in" status.
+- `AuthorizationEndpoint`: the provider authorize URL.
+- `Parameters`: query parameters appended to the authorize URL. Do not include
+  `redirect_uri` or `state`; the host injects both.
+- `RedirectKind`: `AuthorizationRedirectKind.Loopback` or `CustomScheme`.
+- `TimeoutSeconds`: how long to wait for the redirect. `0` means the host default
+  (60 seconds). The host caps this at 300 seconds.
+
+### `IAuthorizationResult`
+
+What the host hands back:
+
+- `IsSuccessful`: whether the redirect was captured.
+- `RedirectUri`: the exact `redirect_uri` the host used. RFC 6749 requires this to
+  be sent to the token endpoint during code exchange, so `OAuthClient` forwards it.
+- `ResponseParameters`: the captured query parameters (for example `code`). The
+  host has already validated and removed `state`.
+- `Error`: populated when `IsSuccessful` is false (provider error, timeout, user
+  cancellation, or a broker failure).
+
+### `AuthorizationRedirectKind`
+
+- `Loopback` (`0`): `http://127.0.0.1:{ephemeral-port}/`, RFC 8252 loopback
+  redirection. This has the broadest provider support and is the default.
+- `CustomScheme` (`1`): `x-cmdpal://auth/callback`, using Command Palette's
+  registered protocol. It auto-foregrounds the palette, but only works with
+  providers that allow custom-scheme redirect URIs.
+
+### `NavigationMode`
+
+Used by `GoToPageAsync`:
+
+- `Push`: push the target page onto the navigation stack (the default).
+- `GoBack`: go back one page, then navigate to the target page.
+- `GoHome`: go back to the home page, then navigate to the target page.
+
+## Capability detection
+
+Not every installed Command Palette is new enough to broker auth. The Toolkit
+exposes two static flags on `ExtensionHost`:
+
+- `ExtensionHost.SupportsAuthorization`
+- `ExtensionHost.SupportsNavigation`
+
+Both are true only when the connected host implements `IExtensionHost2`. Check the
+relevant flag before offering a sign-in action. If you call
+`ExtensionHost.RequestAuthorizationAsync` or `ExtensionHost.GoToPageAsync` against
+an older host, the Toolkit throws `NotSupportedException`. Prefer the capability
+check so you can show a graceful message instead of surfacing an exception.
+
+```csharp
+if (!ExtensionHost.SupportsAuthorization)
+{
+    // Show a "sign-in is not available, please update" message.
+    return;
+}
+```
+
+## Security model
+
+The broker is designed so that a mistake in an extension cannot leak tokens through
+the host, and so that the front-channel redirect is hard to spoof.
+
+- PKCE is required. `OAuthClient` always sends `code_challenge` with
+  `code_challenge_method=S256`. The verifier never leaves the extension process.
+- Public clients only. The sample and the recommended pattern use no client secret.
+  Do not ship a secret in an extension; treat every extension as a public client.
+- `state` is host-owned, random, and single use. The host generates it, matches it
+  on the redirect, and strips it before returning, so extensions never handle it.
+- `redirect_uri` binding. The host returns the exact `redirect_uri` it used and the
+  extension must send that same value to the token endpoint (RFC 6749). `OAuthClient`
+  does this for you.
+- Loopback is bound to `127.0.0.1` only. The host listens on the loopback interface
+  with an ephemeral port, per RFC 8252.
+- No token storage in the host. Command Palette only brokers the front-channel
+  redirect. Tokens are exchanged and, if desired, stored entirely inside the
+  extension process.
+- Timeout caps. `TimeoutSeconds` defaults to 60 seconds and the host caps it at 300
+  seconds, so a stuck flow cannot wait forever.
+
+Do not log or display the authorization code, the access or refresh token, or the
+PKCE verifier. Surface only generic status on failure.
+
+## Token storage guidance
+
+Persisting tokens is optional and always happens inside the extension process. The
+Toolkit provides:
+
+- `ITokenStore`: a small `Retrieve` / `Save` / `Remove` abstraction keyed by a
+  string.
+- `CredentialManagerTokenStore`: an `ITokenStore` backed by the Windows Credential
+  Manager (`PasswordVault`). Tokens are encrypted at rest per user and require the
+  extension to run as a packaged app, which Command Palette extensions do. Use a
+  distinct namespace per provider or account so keys do not collide.
+
+Caveat: `PasswordVault` limits the size of a stored secret to a few kilobytes. That
+is fine for typical access and refresh tokens, but very large JWTs can exceed it, so
+guard `Save` in a try/catch and treat storage as best effort.
+
+`OAuthToken.IsExpired(skew)` helps you decide when to refresh. Use
+`OAuthClient.RefreshAsync(refreshToken)` when the provider issued a refresh token
+(request the `offline_access` scope if the provider needs it).
+
+## Bring your own provider
+
+The sample defaults to the Duende IdentityServer public demo because it is a
+secretless, PKCE-friendly test provider. To target your own provider, register a
+public (native or desktop) OAuth client and swap the endpoints, client id, and
+scopes.
+
+### GitHub example
+
+GitHub supports the Authorization Code flow and works well with the loopback
+redirect.
+
+1. Create an OAuth app at GitHub Developer settings. GitHub requires a registered
+   callback URL and does not support custom-scheme redirect URIs, so use
+   `AuthorizationRedirectKind.Loopback`. Register a loopback callback such as
+   `http://127.0.0.1/` (GitHub matches on the host and path, and the broker uses an
+   ephemeral port).
+2. Configure the client:
+
+   ```csharp
+   var github = new OAuthClient
+   {
+       ClientId = "<your Client ID>",
+       AuthorizationEndpoint = "https://github.com/login/oauth/authorize",
+       TokenEndpoint = "https://github.com/login/oauth/access_token",
+       Scopes = ["read:user"],
+       RedirectKind = AuthorizationRedirectKind.Loopback,
+       DisplayName = "My extension",
+   };
+
+   var token = await github.AuthorizeAsync();
+   ```
+
+GitHub's token endpoint defaults to a form-encoded response; `OAuthClient` sends
+`Accept: application/json` so it receives JSON. Note that GitHub personal OAuth apps
+do not issue refresh tokens by default. If you need refresh tokens, use a GitHub App
+with expiring user tokens, which follows the same Authorization Code shape.
+
+Confirm your provider's exact endpoints, supported redirect types, and scope names
+from its own documentation before shipping.
+
+## Try the sample
+
+`SamplePagesExtension` includes a runnable illustration under
+`Samples` -> `Sample: OAuth sign-in`. It:
+
+1. Checks `ExtensionHost.SupportsAuthorization` and shows a graceful message on
+   older hosts.
+2. Runs `OAuthClient.AuthorizeAsync` against the Duende public demo.
+3. Optionally persists the token with `CredentialManagerTokenStore`.
+4. Calls `ExtensionHost.GoToPageAsync` to navigate to a signed-in landing page that
+   shows non-sensitive session facts only.
+
+The sample is illustrative. Running it opens a real browser and needs an
+interactive sign-in against a real identity provider, so it cannot be exercised
+headlessly.

src/modules/cmdpal/ext/SamplePagesExtension/Pages/OAuthSignInCommand.cs

@@ -0,0 +1,114 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Threading.Tasks;
+using Microsoft.CommandPalette.Extensions;
+using Microsoft.CommandPalette.Extensions.Toolkit;
+
+namespace SamplePagesExtension;
+
+/// <summary>
+/// Demonstrates the built-in Command Palette authorization flow. On invoke it
+/// runs an OAuth 2.0 Authorization Code + PKCE sign-in through the host redirect
+/// broker (via the Toolkit <see cref="OAuthClient"/>), optionally persists the
+/// token in the Windows Credential Manager, and then asks the host to navigate to
+/// a signed-in landing page.
+/// </summary>
+/// <remarks>
+/// This sample is illustrative. Running it requires a real identity provider and
+/// an interactive browser sign-in, so it cannot be exercised headlessly. The
+/// defaults below target the Duende IdentityServer public demo, which is a
+/// well-known, secretless, PKCE-friendly test provider. Swap the constants for
+/// your own registered public client to bring your own provider.
+/// </remarks>
+internal sealed partial class OAuthSignInCommand : InvokableCommand
+{
+    // Demo identity provider values. These are safe to ship because the flow uses
+    // PKCE with a public client (there is no client secret). Replace them with your
+    // own registered client to target a different provider.
+    private const string DemoClientId = "interactive.public";
+    private const string DemoAuthorizationEndpoint = "https://demo.duendesoftware.com/connect/authorize";
+    private const string DemoTokenEndpoint = "https://demo.duendesoftware.com/connect/token";
+    private const string DemoScopes = "openid profile";
+
+    // A distinct namespace so the optional token store does not collide with other
+    // extensions that also persist tokens.
+    private const string TokenStoreNamespace = "SamplePagesExtension.OAuthSample";
+    private const string TokenStoreKey = "demo.duende";
+
+    public OAuthSignInCommand()
+    {
+        Name = "Sign in";
+        Icon = new IconInfo("\uE8FA"); // Permissions
+    }
+
+    public override ICommandResult Invoke()
+    {
+        // Older Command Palette hosts do not implement the authorization broker.
+        // Fail politely instead of throwing NotSupportedException at the user.
+        if (!ExtensionHost.SupportsAuthorization)
+        {
+            return CommandResult.ShowToast(
+                "This build of Command Palette does not support sign-in. Update Command Palette to try the built-in authorization flow.");
+        }
+
+        // The interactive flow waits for a browser round trip, so run it off the
+        // invoke thread. On success the host drives navigation to the signed-in
+        // page; on failure we surface a short status toast.
+        _ = SignInAsync();
+
+        // Keep the entry page open while the browser sign-in happens.
+        return CommandResult.KeepOpen();
+    }
+
+    private static async Task SignInAsync()
+    {
+        try
+        {
+            var client = new OAuthClient
+            {
+                ClientId = DemoClientId,
+                AuthorizationEndpoint = DemoAuthorizationEndpoint,
+                TokenEndpoint = DemoTokenEndpoint,
+                Scopes = DemoScopes.Split(' ', StringSplitOptions.RemoveEmptyEntries),
+                RedirectKind = AuthorizationRedirectKind.Loopback,
+                DisplayName = "Command Palette OAuth sample",
+            };
+
+            // Runs PKCE generation, the host-brokered redirect, and the token
+            // exchange. Everything sensitive stays inside this extension process.
+            var token = await client.AuthorizeAsync().ConfigureAwait(false);
+
+            TryPersist(token);
+
+            // Phase 3 host-driven navigation: move Command Palette to a signed-in
+            // landing page that shows non-sensitive facts about the session.
+            await ExtensionHost.GoToPageAsync(new SampleSignedInPage(token), NavigationMode.Push).ConfigureAwait(false);
+        }
+        catch (Exception ex)
+        {
+            // Never surface the authorization code, token, or PKCE verifier. Keep
+            // the user-facing message generic and only log the exception type.
+            new ToastStatusMessage("Sign-in did not complete. See the Command Palette logs for details.").Show();
+            ExtensionHost.LogMessage($"OAuth sample sign-in failed: {ex.GetType().Name}");
+        }
+    }
+
+    private static void TryPersist(OAuthToken token)
+    {
+        // Persisting the token is optional. Guard it so a storage failure (for
+        // example an oversized token that exceeds the vault limit) does not break
+        // the demo.
+        try
+        {
+            var store = new CredentialManagerTokenStore(TokenStoreNamespace);
+            store.Save(TokenStoreKey, token);
+        }
+        catch (Exception ex)
+        {
+            ExtensionHost.LogMessage($"OAuth sample could not persist the token: {ex.GetType().Name}");
+        }
+    }
+}