From 63f134e55e0c4ceb1b1fd10f6eb97dcc9358bd4f Mon Sep 17 00:00:00 2001 From: MrSphay Date: Sat, 16 May 2026 04:03:06 +0200 Subject: [PATCH] Update user-facing README --- README.md | 249 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 156 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index b75786a..9d2349c 100644 --- a/README.md +++ b/README.md @@ -1,134 +1,197 @@ # MrTrust -MrTrust is a small Windows trust-onboarding kit for MrSphay software. +MrTrust is the trust setup tool for MrSphay Windows software. -It is designed for this workflow: +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. -1. MrSphay creates a private code-signing certificate once. -2. MrSphay publishes only the public trust certificate with MrTrust. -3. A user runs MrTrust once and explicitly approves installing that public certificate. -4. MrSphay projects signed with the matching certificate chain are shown as trusted on that PC. +MrTrust does not disable Microsoft Defender, SmartScreen, UAC, firewall rules, or company security policies. -MrTrust does not bypass Microsoft Defender or SmartScreen. Windows can still scan, quarantine, or warn about suspicious files. This project only manages normal Windows certificate trust with visible user consent. +## Download -## What It Contains +Latest release page: -- `MrTrust.exe` opens a standalone Windows interface for installing or removing trust. -- `MrTrust.ps1` and `scripts/` are source and maintainer tools for building, signing, and local development. -- `scripts/New-MrTrustCertificate.ps1` creates a local root certificate and a code-signing certificate for the publisher. -- `scripts/Install-MrTrust.ps1` installs the public trust certificate for the current user or the local machine. -- `scripts/Uninstall-MrTrust.ps1` removes the MrTrust certificate again. -- `scripts/Sign-MrTrustProject.ps1` signs `.exe`, `.msi`, `.ps1`, and other Authenticode-compatible files. -- `scripts/Sign-MrTrustProjectLinux.sh` signs Windows PE/MSI/CAT artifacts on Ubuntu Gitea runners with `osslsigncode`. -- `scripts/New-MrTrustRelease.ps1` builds a distributable ZIP package. -- `docs/integration-prompt.md` is a prompt you can paste into other Windows projects. -- `docs/agent-target-integration.md` is the autonomous target-project integration runbook for agents. -- `mrtrust.integration.json` is the machine-readable integration contract. -- `MrTrust.exe` is standalone for normal users. It embeds the public certificates and runtime scripts. - -## Quick Start For MrSphay - -Create the certificates: - -```powershell -.\scripts\New-MrTrustCertificate.ps1 +```text +https://git.wilkensxl.de/MrSphay/MrTrust/releases ``` -This writes: +Download the newest `MrTrust-.zip`, extract it, and start: -- public certificates to `assets\certificates\` -- private signing material to `private\` - -The `private\` directory is ignored by git. Do not publish `.pfx` files or passwords. - -Install the public trust certificate on your own PC: - -```powershell -.\MrTrust.ps1 install +```text +MrTrust.exe ``` -Open the GUI: +The executable is standalone for normal users. It embeds the public certificates and the scripts it needs at runtime. -```powershell -.\MrTrust.ps1 gui -``` +## For Users -Sign another project build: +Use the GUI buttons: -```powershell -.\MrTrust.ps1 sign ` - -Path "C:\Path\To\App.exe" ` - -PfxPath ".\private\MrSphay-CodeSigning.pfx" -``` +- `Install trust` installs MrSphay public trust certificates. +- `Remove trust` removes them again. +- `Refresh` checks the current trust state. -Remove the trust certificate: - -```powershell -.\MrTrust.ps1 uninstall -``` - -Build a user-facing ZIP release: - -```powershell -.\scripts\New-MrTrustRelease.ps1 -Version 0.1.3 -``` - -The Gitea workflow `.gitea/workflows/build.yml` builds the Windows launcher EXE on an `ubuntu-latest` runner with .NET Windows cross-targeting, then uploads the ZIP as an artifact. - -## User Installation - -For normal users, distribute `MrTrust.exe`. The executable embeds the public certificate files and opens the GUI by default. - -By default, MrTrust installs trust only for the current Windows user: +Default installation scope: ```text Root certificate -> Cert:\CurrentUser\Root Code-signing certificate -> Cert:\CurrentUser\TrustedPublisher ``` -For all users on the machine, run PowerShell as Administrator: +This means trust is installed only for the current Windows user. -```powershell -.\MrTrust.exe +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 ``` -Then choose the all-users option in the GUI. +The same values are stored in: -## Using This Repo With Other Agents +```text +assets/certificates/thumbprints.txt +mrtrust.integration.json +``` -Yes. Give another agent this repository URL, the target Windows project, and `docs/integration-prompt.md`. +## For Developers -For autonomous work, the agent should read these files in order: +Local maintainer commands: -1. `mrtrust.integration.json` -2. `docs/agent-target-integration.md` -3. `docs/integration-prompt.md` +```powershell +.\MrTrust.ps1 gui +.\MrTrust.ps1 install +.\MrTrust.ps1 uninstall +``` -The agent's job is to modify the target project, not this repository: +Create or refresh local certificates: -- expose a visible "Open MrTrust" or trust setup path for users -- link to or bundle the standalone `MrTrust.exe` -- sign Windows release artifacts with the MrSphay code-signing certificate -- keep trust installation explicit, reversible, and user-confirmed -- keep private signing material out of the target repository and release artifacts +```powershell +.\scripts\New-MrTrustCertificate.ps1 +``` -Both sides have to be wired: +Build a release ZIP locally: -- MrTrust side: users install the public trust certificates once. +```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. -- Installer side, optional: the target app can offer "Open MrTrust" or bundle `MrTrust.exe`, but it must not silently change trust. If the target project is not signed, MrTrust cannot make it trusted. -## Important Limits +## Current Build -- This only helps for programs signed with the matching MrSphay certificate chain. -- It does not make unsigned programs trusted. -- It does not disable Defender, SmartScreen, UAC, or enterprise policies. -- Public distribution without warnings is still best handled with a recognized commercial code-signing certificate. +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. -## Recommended Project Integration +Manual `workflow_dispatch` runs build artifacts but do not attach release assets, to avoid duplicate release uploads. -Use `docs/integration-prompt.md` in another Windows project. The prompt tells Codex or another assistant to add a visible trust check, a link or bundled copy of the standalone `MrTrust.exe`, and a signing step without hiding security changes from the user. +## Security Notes -For agents that can inspect files autonomously, `docs/agent-target-integration.md` gives the decision tree, installer patterns, signing commands, and completion checklist. +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.