MrTrust/README.md

# MrTrust

MrTrust is the trust setup tool for MrSphay Windows software.

Normal users run `MrTrust.exe` once, review the shown certificate details, and explicitly approve installing the public MrSphay trust certificates. After that, Windows can validate MrSphay apps that are signed with the matching code-signing certificate.

MrTrust does not disable Microsoft Defender, SmartScreen, UAC, firewall rules, or company security policies.

## Download

Latest release page:

```text
https://git.wilkensxl.de/MrSphay/MrTrust/releases
```

Download the newest `MrTrust-<version>.zip`, extract it, and start:

```text
MrTrust.exe
```

The executable is standalone for normal users. It embeds the public certificates and the scripts it needs at runtime.

## For Users

Use the GUI buttons:

- `Install trust` installs MrSphay public trust certificates.
- `Remove trust` removes them again.
- `Refresh` checks the current trust state.

Default installation scope:

```text
Root certificate -> Cert:\CurrentUser\Root
Code-signing certificate -> Cert:\CurrentUser\TrustedPublisher
```

This means trust is installed only for the current Windows user.

For all users on the PC, run `MrTrust.exe` as Administrator and choose the all-users option in the GUI.

## What MrTrust Does

MrTrust installs public certificates that let Windows validate software signed by MrSphay.

The expected flow is:

1. A MrSphay app is signed during its release build.
2. The user runs `MrTrust.exe` once and confirms the trust installation.
3. Windows can validate the signature chain for signed MrSphay apps on that PC.

## What MrTrust Does Not Do

- It does not make unsigned programs trusted.
- It does not bypass Defender or SmartScreen.
- It does not remove UAC prompts from apps that need administrator rights.
- It does not silently install certificates.
- It does not install private signing keys on user machines.

## Public Certificate Values

These values are public and can be used by agents or documentation:

```text
Publisher:
MrSphay

Root certificate thumbprint:
39F7458E6E2C1126E93E6A1F228196006B174DF2

Code-signing certificate thumbprint:
A024A89200469F099EC4A172B4F96F6428AFD41B
```

The same values are stored in:

```text
assets/certificates/thumbprints.txt
mrtrust.integration.json
```

## For Developers

Local maintainer commands:

```powershell
.\MrTrust.ps1 gui
.\MrTrust.ps1 install
.\MrTrust.ps1 uninstall
```

Create or refresh local certificates:

```powershell
.\scripts\New-MrTrustCertificate.ps1
```

Build a release ZIP locally:

```powershell
.\scripts\New-MrTrustRelease.ps1 -Version 0.1.3
```

Sign an artifact locally on Windows:

```powershell
.\MrTrust.ps1 sign `
  -Path "C:\Path\To\App.exe" `
  -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B
```

Private signing material belongs only in `private/`, Bitwarden, or Gitea secrets. Never commit `.pfx` files, private keys, passwords, or Base64-encoded signing material.

## Gitea Secrets For Target Projects

For another project to sign Windows release artifacts on an Ubuntu Gitea runner, add these repository secrets to that target project:

```text
MRTRUST_CODESIGN_PFX_BASE64
MRTRUST_CODESIGN_PFX_PASSWORD
```

Optional timestamp override:

```text
MRTRUST_TIMESTAMP_URL
```

The values for the first two secrets should be kept in Bitwarden. They are private signing credentials.

The helper script for Ubuntu runners is:

```text
scripts/Sign-MrTrustProjectLinux.sh
```

It signs supported Windows artifacts with `osslsigncode`:

```text
.exe
.msi
.dll
.cat
```

PowerShell scripts should be signed on Windows, not Ubuntu.

## Using MrTrust In Another Project

Give another agent this repository URL and the target Windows project:

```text
https://git.wilkensxl.de/MrSphay/MrTrust
```

Tell the agent to read these files:

```text
mrtrust.integration.json
docs/agent-target-integration.md
docs/integration-prompt.md
```

The agent should modify the target project so that:

- Windows release artifacts are signed.
- The project links to or bundles `MrTrust.exe`.
- Users have a visible optional trust setup path.
- Trust installation remains explicit and reversible.
- No private signing material is committed or shipped.

Both sides are required:

- MrTrust side: user installs the public trust certificates once.
- Target project side: release artifacts are signed with the MrSphay code-signing certificate.

If the target project is not signed, MrTrust cannot make it trusted.

## Current Build

The Gitea workflow builds `MrTrust.exe` on `ubuntu-latest` with .NET Windows cross-targeting, packages `MrTrust-0.1.3.zip`, uploads it as a workflow artifact, and attaches the ZIP to the Gitea release on `main` pushes.

Manual `workflow_dispatch` runs build artifacts but do not attach release assets, to avoid duplicate release uploads.

## Security Notes

MrTrust is intentionally transparent:

- The GUI shows the trust state.
- Installing trust requires user confirmation.
- Removing trust is available in the same tool.
- The public certificates are embedded in the executable.
- Private signing material is never needed on user machines.

For broad public distribution without SmartScreen reputation delays, a recognized commercial code-signing certificate is still the cleanest option.