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

Add MrTrust GUI and Gitea release build
Some checks failed
Build MrTrust / build-windows (push) Has been cancelled
Details

Browse Source
This commit is contained in:
MrSphay
2026-05-15 23:47:10 +02:00
parent 7d4e9759e6
commit b58b6358f4
20 changed files with 1179 additions and 403 deletions
Download Patch File Download Diff File Expand all files Collapse all files

389
README.md
View File

@@ -1,368 +1,123 @@
# Codex Agent Repository Kit
# MrTrust
Reusable setup kit for new or existing repositories that should be easy for Codex agents, humans, and CI workflows to maintain.
MrTrust is a small Windows trust-onboarding kit for MrSphay software.
This README is for humans. Agent-facing rules live in `AGENTS.md`, `agent-quickstart.md`, `new-repository.md`, and `existing-project.md`.
It is designed for this workflow:
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
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.
## What This Kit Adds
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.
- `AGENTS.md` and `.codex/project.md` for agent context.
- Optional Gitea workflows for build, security scan, cleanup, dependency check, release dry run, and template compliance.
- Release, security, handoff, changelog, and contribution templates.
- README blueprint templates for projects that want generated README output.
- Stack notes for Node, Electron, Python, Docker, and static-site projects.
## What It Contains
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
- `MrTrust.ps1 gui` opens a simple Windows interface for installing or removing trust.
- `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/New-MrTrustRelease.ps1` builds a distributable ZIP package.
- `docs/integration-prompt.md` is a prompt you can paste into other Windows projects.
## Recommended New Repository Setup
## Quick Start For MrSphay
1. Create the repository in Gitea.
2. Clone it locally with SSH.
3. Copy this kit into the repository with Codex or manually from `files/`.
4. Replace placeholders with real project values.
5. Add repository secrets for CI publishing.
6. Commit and push the baseline.
7. Let the Gitea workflows report any missing setup.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## SSH Setup
Generate a key if you do not already have one:
Create the certificates:
```powershell
ssh-keygen -t ed25519 -C "you@example.com"
.\scripts\New-MrTrustCertificate.ps1
```
Start the SSH agent and add the key:
This writes:
- 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
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519
.\MrTrust.ps1 install
```
Show the public key:
Open the GUI:
```powershell
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub
.\MrTrust.ps1 gui
```
Add that public key in Gitea:
```text
Profile -> Settings -> SSH / GPG Keys -> Add Key
```
Clone with SSH:
```bash
git clone ssh://git@git.wilkensxl.de:2222/OWNER/REPOSITORY.git
cd REPOSITORY
```
Optional SSH config:
```text
Host git.wilkensxl.de
HostName git.wilkensxl.de
User git
Port 2222
IdentityFile ~/.ssh/id_ed25519
```
With that config, this shorter clone URL also works:
```bash
git clone git@git.wilkensxl.de:OWNER/REPOSITORY.git
```
Verify the remote:
```bash
git remote -v
git status --short
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Applying The Kit With Codex
For a new repository, start Codex in the target repository and use:
```text
Use the Codex Agent Repository Kit.
Read manifest.json, then use new-repository.md.
Create the smallest useful baseline for this repository.
Replace placeholders with real values from this repository.
Keep commands truthful and do not invent scripts that cannot run.
Do not create a release.
```
For an existing repository:
```text
Use the Codex Agent Repository Kit.
Read manifest.json, then use existing-project.md.
Retrofit the baseline without replacing existing project structure or README knowledge.
Preserve current CI behavior and project style.
Do not create a release.
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Manual Copy Map
Use `manifest.json` as the source of truth. Common targets:
| Template | Target |
| --- | --- |
| `files/AGENTS.md` | `AGENTS.md` |
| `files/project.md` | `.codex/project.md` |
| `files/build-gitea.yml` | `.gitea/workflows/build.yml` |
| `files/security-scan-gitea.yml` | `.gitea/workflows/security-scan.yml` |
| `files/repo-cleanup-gitea.yml` | `.gitea/workflows/repo-cleanup.yml` |
| `files/dependency-check-gitea.yml` | `.gitea/workflows/dependency-check.yml` |
| `files/release-dry-run-gitea.yml` | `.gitea/workflows/release-dry-run.yml` |
| `files/template-compliance-gitea.yml` | `.gitea/workflows/template-compliance.yml` |
| `files/SECURITY.md` | `SECURITY.md` |
| `files/CHANGELOG.md` | `CHANGELOG.md` |
| `files/CONTRIBUTING.md` | `CONTRIBUTING.md` |
| `files/release-checklist.md` | `docs/release-checklist.md` |
| `files/security-review.md` | `docs/security-review.md` |
| `files/agent-handoff.md` | `docs/agent-handoff.md` |
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Required Placeholder Values
Replace or remove all placeholders before considering a repository ready:
```text
PROJECT_NAME
PROJECT_DESCRIPTION
REPOSITORY_OWNER
REPOSITORY_NAME
PACKAGE_NAME
ARTIFACT_NAME
ARTIFACT_OUTPUT_DIRECTORY
AUTHOR_NAME
PROJECT_STACK
DOWNLOAD_URL
CI_URL
RELEASES_URL
BUILD_COMMAND
TEST_COMMAND
LINT_COMMAND
AUDIT_COMMAND
README_COMMAND
INSTALL_COMMAND
DEV_COMMAND
PACKAGE_MANAGER
PROJECT_VERSION
COMMIT_OR_VERSION
```
If a value does not apply, remove that section instead of leaving fake data. If a value is genuinely unknown, mark it as `PENDING`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Token Overview
Use separate tokens for separate jobs.
| Token | Location | Purpose |
| --- | --- | --- |
| `REGISTRY_TOKEN` | Repository secret | CI package publishing from Gitea Actions |
| `GITEA_TOKEN` | Local environment or repository secret | Gitea API access for issues, releases, workflow polling, and repository metadata |
Repository secrets are available to workflows. They are not visible to local Codex sessions. Local Codex API actions need a local environment variable.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Gitea Token Permissions
For both tokens, choose this repository access level:
```text
Repository and Organization Access: All (public, private, and limited)
```
Use separate tokens where possible. A package-only token should not be able to create issues or releases.
### REGISTRY_TOKEN Permissions
Use this token as a repository secret for package publishing from Gitea Actions:
```text
package: Read and Write
repository: Read
user: Read
activitypub: No Access
admin: No Access
issue: No Access
misc: No Access
notification: No Access
organization: No Access
```
These permissions cover generic package uploads while still allowing the workflow to read repository metadata.
### GITEA_TOKEN Permissions
Use this token locally on the PC for Codex API actions, or as a repository secret only when workflows need issue, release, or workflow API access:
```text
issue: Read and Write
package: Read
repository: Read and Write
user: Read
activitypub: No Access
admin: No Access
misc: No Access
notification: No Access
organization: No Access
```
These permissions cover creating and reading issues, creating and reading releases, reading repository metadata, and polling workflow runs where the Gitea API allows it. `package: Read` is enough for API checks; use `package: Read and Write` only if this same token must publish packages.
Use a dedicated bot or automation user when possible.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Setting Local Tokens
Set a local token for Codex or shell-based API work.
Current PowerShell session:
Sign another project build:
```powershell
$env:GITEA_TOKEN = "paste-token-here"
.\MrTrust.ps1 sign `
-Path "C:\Path\To\App.exe" `
-PfxPath ".\private\MrSphay-CodeSigning.pfx"
```
Persist for the current Windows user:
Remove the trust certificate:
```powershell
setx GITEA_TOKEN "paste-token-here"
.\MrTrust.ps1 uninstall
```
Open a new terminal after `setx`.
Test repository API access:
Build a user-facing ZIP release:
```powershell
$headers = @{ Authorization = "token $env:GITEA_TOKEN" }
Invoke-RestMethod `
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME" `
-Headers $headers
.\scripts\New-MrTrustRelease.ps1 -Version 0.1.0
```
Test issue access:
The Gitea workflow `.gitea/workflows/build.yml` builds the same ZIP on a Windows runner and uploads it as an artifact.
If the Windows runner has the private signing certificate installed, set `MRTRUST_SIGNING_THUMBPRINT` to sign the launcher during the build.
## User Installation
For normal users, distribute MrTrust with the public certificate file:
```text
assets\certificates\MrSphay-LocalTrust-Root.cer
assets\certificates\MrSphay-CodeSigning.cer
```
The user runs:
```powershell
Invoke-RestMethod `
-Uri "https://git.wilkensxl.de/api/v1/repos/REPOSITORY_OWNER/REPOSITORY_NAME/issues?state=open&limit=1" `
-Headers $headers
.\MrTrust.ps1 gui
```
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Setting Repository Secrets
In Gitea:
By default, MrTrust installs trust only for the current Windows user:
```text
Repository -> Settings -> Actions -> Secrets -> Add Secret
Root certificate -> Cert:\CurrentUser\Root
Code-signing certificate -> Cert:\CurrentUser\TrustedPublisher
```
Add:
For all users on the machine, run PowerShell as Administrator:
```text
REGISTRY_TOKEN
```powershell
.\MrTrust.ps1 install -Scope LocalMachine
```
Use a token with package write access. If you want workflows to create releases or issues too, add a separate secret:
## Using This Repo With Other Agents
```text
GITEA_TOKEN
```
Yes. Give another agent this repository URL and the target Windows project, then paste `docs/integration-prompt.md`.
Keep package publishing and release or issue automation separate when possible. It makes permission reviews easier.
Both sides have to be wired:
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
- 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.
## Package Publishing
If the target project is not signed, MrTrust cannot make it trusted.
`files/build-gitea.yml` can publish generic packages when `REGISTRY_TOKEN` is available.
## Important Limits
The workflow:
- 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.
- builds project artifacts,
- copies them to URL-safe filenames,
- uploads immutable versioned packages,
- updates a stable `latest` package path.
## Recommended Project Integration
The workflow uses:
```text
GITHUB_SERVER_URL
GITHUB_REPOSITORY_OWNER
GITHUB_REPOSITORY
REGISTRY_TOKEN
```
When those values are unavailable, replace `REPOSITORY_OWNER`, `REPOSITORY_NAME`, and related placeholders before use. The default Gitea server is `https://git.wilkensxl.de`.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Agent Follow-up Issues
Agents should create focused tracker issues for real follow-up work that is outside the current scope or can be handled independently by humans or other agents.
An issue should include:
- observed problem,
- impact,
- affected files or commands,
- suggested next steps,
- verification already performed.
Agents must not create issues for vague reminders, duplicate work, or tasks they can safely finish immediately. Sensitive details belong in private channels or `docs/agent-handoff.md`, not public issues.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Release Checklist For A New Repo
Before the first release of a target project:
1. Ensure `AGENTS.md` and `.codex/project.md` match the real project.
2. Replace all placeholders or mark genuinely unknown values as `PENDING`.
3. Configure `REGISTRY_TOKEN` if packages are published.
4. Configure `GITEA_TOKEN` only if workflows need issue or release API access.
5. Verify SSH push access.
6. Run lint, test, build, and audit commands that exist.
7. Run `git diff --check`.
8. Confirm release artifacts do not include Codex kit metadata unless explicitly wanted.
9. Push and poll workflows to success or document the blocker.
<p align="center"><img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="-----------------------------------------------------" width="100%"></p>
## Updating The Kit In A Project
When this kit changes, update target repositories conservatively:
```bash
git status --short
git pull --ff-only
```
Then ask Codex:
```text
Update this repository's Codex Agent Repository Kit files from the latest kit.
Preserve project-specific README content, commands, release rules, and workflow customizations.
Do not overwrite unrelated changes.
```
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.