MrTrust/docs/agent-target-integration.md

# Agent Target Integration Runbook

Use this file when you are an agent modifying another Windows project to support MrTrust.

## Non-Negotiable Goal

Modify the target project so that, after a user has installed trust with `MrTrust.exe`, the target project's MrSphay-signed Windows release artifacts start and validate normally.

Do not modify Windows security policy, Defender, SmartScreen, UAC, or certificate stores silently. MrTrust must remain visible, optional, and reversible.

## Inputs To Read First

1. Read `mrtrust.integration.json`.
2. Read `docs/integration-prompt.md`.
3. Inspect the target project for:
   - build commands
   - release artifact paths
   - installer technology
   - existing signing steps
   - user-facing docs
   - CI workflows

If the target project already has equivalent trust or signing integration, update it instead of duplicating it.

## Required Target Project Changes

Apply every item that fits the target project:

1. Add a user-facing MrTrust entry point.
   - If the project has an installer, add an optional action named `Open MrTrust` or `Trust MrSphay signed apps`.
   - If the project has an app settings/about/help screen, add a button or menu item that launches `MrTrust.exe`.
   - If the project has no UI or installer, add release documentation linking to or bundling `MrTrust.exe`.

2. Bundle or link the standalone executable.
   - Preferred bundled path: `MrTrust\MrTrust.exe`.
   - Source repository: `https://git.wilkensxl.de/MrSphay/MrTrust`.
   - Release page: `https://git.wilkensxl.de/MrSphay/MrTrust/releases`.
   - Do not require users to run `MrTrust.ps1`.
   - Do not copy MrTrust source scripts into user-facing release output unless the target project explicitly ships source.

3. Add signing for Windows artifacts.
   - Sign `.exe`, `.msi`, `.dll`, `.ps1`, `.psm1`, `.psd1`, and `.cat` release artifacts.
   - Use the public thumbprint from `mrtrust.integration.json`.
   - Only run signing where private signing material is securely available.
   - Do not commit `.pfx`, private keys, passwords, tokens, or signing secrets.
   - On the available `ubuntu-latest` Gitea runners, use `osslsigncode` with PFX secrets for `.exe`, `.dll`, `.msi`, and `.cat`.
   - PowerShell script signing (`.ps1`, `.psm1`, `.psd1`) still requires a Windows signing environment. If no Windows runner exists, document that limitation instead of blocking PE/MSI signing.

4. Add verification.
   - Verify the target project still builds.
   - Verify the release output contains the app artifacts and either `MrTrust.exe` or clear MrTrust download instructions.
   - Verify signing status where the OS/tooling is available.
   - Verify no private signing material is tracked or present in release output.

## Default Commands

Open MrTrust from a bundled release:

```powershell
.\MrTrust\MrTrust.exe
```

Sign one artifact from a Windows release runner:

```powershell
.\MrTrust\MrTrust.exe sign -Path .\dist\App.exe -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
```

Sign a release directory:

```powershell
.\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
```

Check a signature:

```powershell
Get-AuthenticodeSignature .\dist\App.exe | Format-List Status,SignerCertificate,StatusMessage
```

Sign a release directory on an Ubuntu Gitea runner:

```bash
bash ./MrTrust/scripts/Sign-MrTrustProjectLinux.sh ./dist
```

## Installer Patterns

### Inno Setup

Bundle `MrTrust.exe` and add an optional task or post-install action:

```ini
[Files]
Source: "MrTrust\MrTrust.exe"; DestDir: "{app}\MrTrust"; Flags: ignoreversion

[Run]
Filename: "{app}\MrTrust\MrTrust.exe"; Description: "Open MrTrust"; Flags: postinstall skipifsilent nowait
```

### NSIS

```nsis
SetOutPath "$INSTDIR\MrTrust"
File "MrTrust\MrTrust.exe"
CreateShortcut "$SMPROGRAMS\$StartMenuFolder\Open MrTrust.lnk" "$INSTDIR\MrTrust\MrTrust.exe"
```

### WiX

Install `MrTrust.exe` as a regular file under an application `MrTrust` folder and expose a Start Menu shortcut or installer UI action. Do not run it silently during install.

### Electron Builder

Add `MrTrust\MrTrust.exe` to `extraResources`, then add a Help/About action that launches the copied executable with the platform shell API. Keep the action user-initiated.

### Portable ZIP

Place `MrTrust.exe` next to the app under:

```text
MrTrust\MrTrust.exe
```

Document that users should run it once before launching signed MrSphay apps if Windows does not yet trust the publisher.

## CI Signing Patterns

### Gitea Actions On Ubuntu Runner

Use this when only `ubuntu-latest`, `ubuntu-24.04`, or `ubuntu-22.04` runners are available.

Required Gitea secrets:

```text
MRTRUST_CODESIGN_PFX_BASE64
MRTRUST_CODESIGN_PFX_PASSWORD
```

Create `MRTRUST_CODESIGN_PFX_BASE64` locally from the private `.pfx`:

```powershell
[Convert]::ToBase64String([IO.File]::ReadAllBytes(".\private\MrSphay-CodeSigning.pfx")) | Set-Clipboard
```

Then paste the clipboard value into the Gitea secret. Do not commit the `.pfx` or the base64 value.

Ubuntu workflow step:

```yaml
- name: Install signing tool
  shell: bash
  run: |
    sudo apt-get update
    sudo apt-get install -y osslsigncode

- name: Sign Windows artifacts
  shell: bash
  env:
    MRTRUST_CODESIGN_PFX_BASE64: ${{ secrets.MRTRUST_CODESIGN_PFX_BASE64 }}
    MRTRUST_CODESIGN_PFX_PASSWORD: ${{ secrets.MRTRUST_CODESIGN_PFX_PASSWORD }}
  run: |
    bash ./MrTrust/scripts/Sign-MrTrustProjectLinux.sh ./dist
```

This signs `.exe`, `.dll`, `.msi`, and `.cat` artifacts. It does not sign PowerShell script files.

### Gitea Actions On Windows Runner

```yaml
- name: Sign Windows artifacts
  shell: powershell
  run: |
    .\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
```

Use this only on a runner where the matching private code-signing certificate is installed in `Cert:\CurrentUser\My` or `Cert:\LocalMachine\My`.

### Local Secure Release Machine

```powershell
.\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
```

Run this after build and before packaging.

## Autonomy Rules

Make reasonable target-project-specific choices without asking the user when:

- artifact paths are discoverable from existing build scripts
- installer technology is obvious from repository files
- there is already a docs or release notes location
- CI already has a Windows release job you can extend

Stop and ask the user only when:

- signing requires a private certificate that is not present and no secret mechanism exists
- the target project has multiple conflicting release systems and no primary release path is identifiable
- a requested change would silently alter trust or weaken security policy

## Completion Checklist

- Target project has a visible MrTrust user path.
- Target project links to or bundles standalone `MrTrust.exe`.
- Supported Windows release artifacts are signed or the blocker is explicitly documented.
- User docs explain install and remove trust.
- No private signing material is committed.
- Target project build/release verification ran, or the exact blocker is documented.