MrSphay/MrTrust
1
0
Fork 0
generated from MrSphay/codex-agent-repository-kit
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Update user-facing README
All checks were successful
Build MrTrust / build (push) Successful in 4m21s
Details

Browse Source
This commit is contained in:
MrSphay
2026-05-16 04:03:06 +02:00
parent e37a0b56c4
commit 63f134e55e
1 changed files with 156 additions and 93 deletions
Download Patch File Download Diff File Expand all files Collapse all files

249
README.md
View File

@@ -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-<version>.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.