diff --git a/AGENTS.md b/AGENTS.md index 7b78abd..45c57df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,8 @@ MrTrust manages explicit Windows certificate trust for MrSphay software. - `assets/certificates/` contains public certificates only. - `private/` is ignored and may contain local signing material. - `docs/integration-prompt.md` is the prompt for adding MrTrust to other projects. +- `docs/agent-target-integration.md` is the autonomous runbook for agents modifying target projects. +- `mrtrust.integration.json` is the machine-readable integration contract. - `docs/security-model.md` documents the intended behavior and limits. - `MrTrust.exe` is the user-facing standalone trust installer. The PowerShell scripts are source/build internals. diff --git a/CHANGELOG.md b/CHANGELOG.md index 3305846..b02fbe0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # Changelog +## Unreleased + +- Added an autonomous target-project integration runbook for agents. +- Added `mrtrust.integration.json` as a machine-readable integration contract. +- Updated agent-facing documentation to prefer the standalone `MrTrust.exe` integration path. + ## 0.1.1 - Added a custom MrTrust application icon and embedded it into the launcher. diff --git a/README.md b/README.md index d092054..29d2832 100644 --- a/README.md +++ b/README.md @@ -21,6 +21,8 @@ MrTrust does not bypass Microsoft Defender or SmartScreen. Windows can still sca - `scripts/Sign-MrTrustProject.ps1` signs `.exe`, `.msi`, `.ps1`, and other Authenticode-compatible files. - `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 @@ -95,6 +97,12 @@ Then choose the all-users option in the GUI. Yes. Give another agent this repository URL, the target Windows project, and `docs/integration-prompt.md`. +For autonomous work, the agent should read these files in order: + +1. `mrtrust.integration.json` +2. `docs/agent-target-integration.md` +3. `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 @@ -121,3 +129,5 @@ 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 the standalone `MrTrust.exe`, and a signing step without hiding security changes from the user. + +For agents that can inspect files autonomously, `docs/agent-target-integration.md` gives the decision tree, installer patterns, signing commands, and completion checklist. diff --git a/docs/agent-target-integration.md b/docs/agent-target-integration.md new file mode 100644 index 0000000..2b164a8 --- /dev/null +++ b/docs/agent-target-integration.md @@ -0,0 +1,162 @@ +# 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. + +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: + +```powershell +.\MrTrust\MrTrust.exe +``` + +Sign one artifact from a Windows release runner: + +```powershell +.\MrTrust\MrTrust.exe sign -Path .\dist\App.exe -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B +``` + +Sign a release directory: + +```powershell +.\MrTrust\MrTrust.exe sign -Path .\dist -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B +``` + +Check a signature: + +```powershell +Get-AuthenticodeSignature .\dist\App.exe | Format-List Status,SignerCertificate,StatusMessage +``` + +## Installer Patterns + +### Inno Setup + +Bundle `MrTrust.exe` and add an optional task or post-install action: + +```ini +[Files] +Source: "MrTrust\MrTrust.exe"; DestDir: "{app}\MrTrust"; Flags: ignoreversion + +[Run] +Filename: "{app}\MrTrust\MrTrust.exe"; Description: "Open MrTrust"; Flags: postinstall skipifsilent nowait +``` + +### NSIS + +```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: + +```text +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 Windows Runner + +```yaml +- 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 + +```powershell +.\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. diff --git a/docs/integration-prompt.md b/docs/integration-prompt.md index b20a63f..670dd62 100644 --- a/docs/integration-prompt.md +++ b/docs/integration-prompt.md @@ -2,6 +2,10 @@ Use this prompt in another Windows project when you want Codex or another agent to add MrTrust support. +Before changing the target project, read: +- `mrtrust.integration.json` +- `docs/agent-target-integration.md` + ```text Integrate MrTrust support into this Windows project. @@ -12,6 +16,7 @@ Goal: Agent contract: - You are modifying the target Windows project, not MrTrust itself. +- Use `mrtrust.integration.json` and `docs/agent-target-integration.md` as the authoritative integration contract. - 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. diff --git a/manifest.json b/manifest.json index 707b30f..89989bb 100644 --- a/manifest.json +++ b/manifest.json @@ -1,7 +1,16 @@ { "name": "codex-agent-repository-kit", - "version": "1.0.5", + "version": "1.0.6", "description": "Universal repository baseline for Codex-assisted projects.", + "mrtrustIntegration": { + "contract": "mrtrust.integration.json", + "agentRunbook": "docs/agent-target-integration.md", + "prompt": "docs/integration-prompt.md", + "standaloneExecutable": "MrTrust.exe", + "publicThumbprint": "A024A89200469F099EC4A172B4F96F6428AFD41B", + "sourceRepository": "https://git.wilkensxl.de/MrSphay/MrTrust", + "releasePage": "https://git.wilkensxl.de/MrSphay/MrTrust/releases" + }, "agentResponsibilities": [ "Read manifest.json before copying files.", "Use copyMap target paths unless the repository already has an equivalent convention.", diff --git a/manifest.schema.json b/manifest.schema.json index 2af585a..4e19d87 100644 --- a/manifest.schema.json +++ b/manifest.schema.json @@ -13,6 +13,34 @@ "description": { "type": "string" }, + "mrtrustIntegration": { + "type": "object", + "required": ["contract", "agentRunbook", "prompt", "standaloneExecutable", "publicThumbprint"], + "properties": { + "contract": { + "type": "string" + }, + "agentRunbook": { + "type": "string" + }, + "prompt": { + "type": "string" + }, + "standaloneExecutable": { + "type": "string" + }, + "publicThumbprint": { + "type": "string" + }, + "sourceRepository": { + "type": "string" + }, + "releasePage": { + "type": "string" + } + }, + "additionalProperties": true + }, "agentResponsibilities": { "type": "array", "items": { diff --git a/mrtrust.integration.json b/mrtrust.integration.json new file mode 100644 index 0000000..ee03f86 --- /dev/null +++ b/mrtrust.integration.json @@ -0,0 +1,59 @@ +{ + "schemaVersion": 1, + "name": "MrTrust", + "purpose": "Add explicit MrSphay trust onboarding and signing support to Windows target projects.", + "sourceRepository": "https://git.wilkensxl.de/MrSphay/MrTrust", + "releasePage": "https://git.wilkensxl.de/MrSphay/MrTrust/releases", + "userFacingReleaseArtifact": { + "fileName": "MrTrust.exe", + "releaseZipNamePattern": "MrTrust-.zip", + "recommendedBundledPath": "MrTrust\\MrTrust.exe", + "distribution": "Bundle this file directly or link to the MrTrust release ZIP.", + "launchCommand": ".\\MrTrust\\MrTrust.exe", + "removeTrustInstruction": "Open MrTrust and choose Remove trust." + }, + "certificate": { + "publisher": "MrSphay", + "publicThumbprint": "A024A89200469F099EC4A172B4F96F6428AFD41B", + "defaultTrustScope": "CurrentUser", + "allUsersTrustScope": "LocalMachine", + "privateMaterialPolicy": "Never commit .pfx files, private keys, passwords, tokens, or signing secrets." + }, + "signing": { + "supportedExtensions": [ + ".exe", + ".msi", + ".dll", + ".ps1", + ".psm1", + ".psd1", + ".cat" + ], + "preferredCommand": ".\\MrTrust\\MrTrust.exe sign -Path -CertificateThumbprint A024A89200469F099EC4A172B4F96F6428AFD41B", + "ciGuidance": "Run signing only on a trusted Windows release runner or secure local release machine where the private certificate is already installed or supplied through secrets.", + "unsignedBehavior": "Unsigned builds should remain unsigned. MrTrust only makes correctly signed MrSphay artifacts validate after the user has installed trust." + }, + "targetProjectAgentContract": { + "modifyTargetProject": true, + "requiredOutcomes": [ + "Expose a visible optional Open MrTrust or trust setup path.", + "Link to or bundle the standalone MrTrust.exe.", + "Sign Windows release artifacts when the target project produces supported artifact types.", + "Document how users install and remove MrTrust trust.", + "Verify no private signing material is present in the target repository or release artifacts." + ], + "forbiddenOutcomes": [ + "Do not silently install certificates.", + "Do not bypass Defender, SmartScreen, UAC, firewall, or Windows security policy.", + "Do not claim MrTrust makes unsigned software trusted.", + "Do not commit private signing material." + ], + "fallbackWhenNoInstallerExists": [ + "Add release documentation that links to or bundles MrTrust.exe.", + "Add a release signing step for supported Windows artifacts.", + "Add verification notes explaining that the app starts normally after the user installs MrTrust and the artifact signature validates." + ] + }, + "agentRunbook": "docs/agent-target-integration.md", + "prompt": "docs/integration-prompt.md" +}