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:

.\MrTrust\MrTrust.exe

Sign one artifact from a Windows release runner:

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

Sign a release directory:

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

Check a signature:

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

Sign a release directory on an Ubuntu Gitea runner:

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

Installer Patterns

Inno Setup

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

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

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

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:

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:

MRTRUST_CODESIGN_PFX_BASE64
MRTRUST_CODESIGN_PFX_PASSWORD

Create MRTRUST_CODESIGN_PFX_BASE64 locally from the private .pfx:

[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:

- 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

- 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

.\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.