Dashboard-native binary downloads from buttons and forms

# Dashboard-native binary downloads from buttons and forms

## Summary

Please add a dashboard-native way to download arbitrary binary content from a button or form action without requiring the app developer to expose or navigate to a separate REST API URL.

This is specifically needed for binary payloads such as PFX, PDF, MSG, ZIP, and image files that are generated or authorized inside a dashboard event handler.

## Problem Statement

The current documented `Start-UDDownload` behavior supports `StringData`, `Path`, and `Url`, and the documentation explicitly frames it around text-file downloads. There is no documented `byte[]` or `Stream` parameter for direct binary downloads from a dashboard event.

The documented binary-response path today is to create a PSU endpoint and return `New-PSUApiResponse -Data [byte[]]`. That works for APIs, but it does not solve the dashboard scenario cleanly because the app developer must introduce a separate URL surface and then route the user to it.

## Why This Blocks Secure Binary Attachment Downloads

- Many dashboard flows generate or retrieve attachment bytes only after a button click or form submission.
- In those flows, forcing a separate endpoint adds extra routing, auth handling, URL management, and lifecycle complexity.
- Temp-file workarounds are risky because they introduce file-leakage and cleanup concerns.
- URL or new-tab navigation is a poor fit for form-driven UX when the user simply clicked a button to download a file.
- Some attachments must remain available only within the current authenticated dashboard interaction, not as a separately addressable endpoint.

## Desired User and Developer Experience

When a user clicks a dashboard button or submits a form:

- The browser download should start immediately from that action.
- No visible navigation or extra tab should be required for normal use.
- The exact source bytes must be preserved with no text conversion or encoding changes.
- The developer must be able to set the filename and content type.
- The download should run in the current dashboard auth and session context.
- The feature should work for in-memory byte arrays and stream-backed content.

## Suggested API Shapes

These are only suggestions, not strict design requirements.

### Option A: Extend `Start-UDDownload`

```powershell
Start-UDDownload -Bytes $bytes -FileName 'certificate.pfx' -ContentType 'application/x-pkcs12'
```

### Option B: Stream support

```powershell
Start-UDDownload -Stream $stream -FileName 'report.pdf' -ContentType 'application/pdf'
```

### Option C: Dashboard-native response object

```powershell
New-UDDownloadResponse -Bytes $bytes -FileName 'message.msg' -ContentType 'application/vnd.ms-outlook'
```

Any equivalent dashboard-native abstraction would be acceptable if it avoids the need for a separate API URL.

## Security and Lifecycle Requirements

- Respect existing dashboard authorization, roles, and session context.
- Do not require developers to persist sensitive content to temp files for common cases.
- If PSU must use temp storage internally, the files should be short-lived, isolated, and automatically cleaned up.
- Dispose streams and related resources reliably.
- Preserve browser download gesture requirements so popup blockers or cross-origin behaviors do not interfere unnecessarily.
- Provide documented size limits or server-side safeguards for large payloads.
- Prevent accidental binary corruption caused by string serialization, encoding conversion, or content-type mismatches.

## Acceptance Criteria

- A dashboard button or form action can trigger a download from an in-memory `byte[]` payload.
- The downloaded file matches the original bytes exactly.
- The developer can specify filename and content type.
- Standard use does not require a visible browser navigation or blank tab.
- The feature uses the current dashboard auth context without requiring a separate custom endpoint.
- Sensitive content does not leak through developer-managed temp files.
- Failure cases surface a clear dashboard-side error instead of a silent no-op.
- The supported size and lifecycle constraints are documented.

## Minimal Repro Example

This example uses a placeholder `byte[]` PFX-like payload only to demonstrate the requested dashboard behavior.

```powershell
New-UDButton -Text 'Download PFX' -OnClick {
[byte[]]$pfxBytes = 0..255

Start-UDDownload `
-Bytes $pfxBytes `
-FileName 'example.pfx' `
-ContentType 'application/x-pkcs12'
}
```

Current limitation: there is no documented dashboard-native way to do the above with exact binary bytes, so the developer must instead create a separate endpoint and return `New-PSUApiResponse -Data [byte[]]` from that route.

## Environment

- PSU version:
- PSU edition:
- Hosting mode:
- Browser:
- Operating system:
- Authentication mode:
- Requested by: Copilot
- Date: 2026-08-07

## Not an API Bug

This request is not claiming that PSU endpoint-based binary responses are broken. The enhancement request is for equivalent first-class support inside dashboard button and form interactions so developers do not have to expose or navigate to a separate API route just to download secure binary content.