From 01148f47037dc2d6eac1f9d5ae66b72bd8e96ce7 Mon Sep 17 00:00:00 2001 From: MrSphay Date: Sat, 16 May 2026 01:46:36 +0200 Subject: [PATCH] Clarify MrTrust target project integration for agents --- AGENTS.md | 2 +- README.md | 21 ++++++++++++++++----- docs/integration-prompt.md | 16 ++++++++++++---- 3 files changed, 29 insertions(+), 10 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4f062ea..7b78abd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -17,7 +17,7 @@ MrTrust manages explicit Windows certificate trust for MrSphay software. - `private/` is ignored and may contain local signing material. - `docs/integration-prompt.md` is the prompt for adding MrTrust to other projects. - `docs/security-model.md` documents the intended behavior and limits. -- `MrTrust.ps1 gui` is the user-facing GUI entry point. +- `MrTrust.exe` is the user-facing standalone trust installer. The PowerShell scripts are source/build internals. ## Verification diff --git a/README.md b/README.md index 2c1d7cd..d092054 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ MrTrust does not bypass Microsoft Defender or SmartScreen. Windows can still sca ## What It Contains -- `MrTrust.ps1 gui` opens a simple Windows interface for installing or removing trust. +- `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. @@ -85,18 +86,28 @@ Code-signing certificate -> Cert:\CurrentUser\TrustedPublisher For all users on the machine, run PowerShell as Administrator: ```powershell -.\MrTrust.ps1 install -Scope LocalMachine +.\MrTrust.exe ``` +Then choose the all-users option in the GUI. + ## Using This Repo With Other Agents -Yes. Give another agent this repository URL and the target Windows project, then paste `docs/integration-prompt.md`. +Yes. Give another agent this repository URL, the target Windows project, and `docs/integration-prompt.md`. + +The agent's job is to modify the target project, not this repository: + +- 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 Both sides have to be wired: - MrTrust side: users install 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 the MrTrust ZIP, but it must not silently change trust. +- 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. @@ -109,4 +120,4 @@ If the target project is not signed, MrTrust cannot make it trusted. ## Recommended Project Integration -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 MrTrust, and a signing step without hiding security changes from the user. +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. diff --git a/docs/integration-prompt.md b/docs/integration-prompt.md index 906e3d5..b20a63f 100644 --- a/docs/integration-prompt.md +++ b/docs/integration-prompt.md @@ -10,22 +10,30 @@ Goal: - The project must not disable Defender, SmartScreen, UAC, or Windows security policy. - All trust changes must be visible and require explicit user confirmation. +Agent contract: +- You are modifying the target Windows project, not MrTrust itself. +- Add MrTrust as a visible, optional trust-onboarding path for users. +- Add or update the target project's release/signing pipeline so produced Windows artifacts are signed. +- Do not mark the task complete after only copying documentation. The target project needs user-facing integration and signing support where applicable. + Implementation requirements: - Add a docs section that explains MrTrust and links to or bundles the MrTrust release ZIP. +- Treat `MrTrust.exe` from the release ZIP as the user-facing integration point. Do not require users to copy or run MrTrust PowerShell source files. - Add a build or release signing step that signs Windows artifacts with the MrSphay code-signing certificate. - Do not commit any .pfx file, private key, certificate password, or signing secret. - If the project has an installer, add an optional "Open MrTrust" action that runs: - powershell.exe -ExecutionPolicy Bypass -File .\MrTrust\MrTrust.ps1 gui + .\MrTrust\MrTrust.exe - Prefer CurrentUser certificate installation by default. - Only offer LocalMachine installation when the user explicitly chooses an all-users install and the process is elevated. -- Add an uninstall path or documentation that runs: - powershell.exe -ExecutionPolicy Bypass -File .\MrTrust\MrTrust.ps1 uninstall +- Add an uninstall path or documentation that opens MrTrust again and tells the user to choose "Remove trust". - Keep the UI wording clear: the user is trusting MrSphay signed software, not bypassing Windows security. - If this project produces an .exe, .msi, .dll, .ps1, .psm1, .psd1, or .cat release artifact, sign it with: - powershell.exe -ExecutionPolicy Bypass -File .\MrTrust\MrTrust.ps1 sign -Path -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B + .\MrTrust\MrTrust.exe sign -Path -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B - Treat the certificate thumbprint as public metadata, but never commit private signing material. +- If the target project needs automated signing, call MrTrust's signing script from CI or a secure local release machine where the private certificate is already installed or supplied through secrets. Do not put private signing material into the target repository or user-facing release ZIP. Verification: +- Confirm the target project's user-facing release contains either a link to the MrTrust release ZIP or a bundled copy of `MrTrust.exe`. - Confirm unsigned builds still show as unsigned. - Confirm signed builds validate after MrTrust installation. - Confirm the MrTrust certificate can be removed again.