Template Registry Submission Workflow & Validation Requirements

[matt-goldman]

Summary

This issue tracks the planned implementation of a submission and validation workflow for the Blake Site Template Registry.

The goal is to make it easier for the community to share templates while adding automated checks to ensure a baseline of quality, reduce risk, and provide a clear trust signal to users who consume templates from the registry.

This process will not provide a security guarantee, but it will help improve confidence that registered templates are functional, meet minimum standards, and have undergone basic automated review.

---

Background

The blake new command supports two ways of creating a site:

1. From the Blake Registry

   blake new --template docs

   Pulls a known template from the official registry.

2. From any Git repository

   blake new --url https://github.com/someone/their-template

   Allows maximum flexibility, but comes with the same risk profile as installing a NuGet package: templates and their plugins can execute arbitrary code during bake.

Currently, arbitrary URL templates are not sandboxed or validated. The registry will add a lightweight vetting process for officially listed templates.

---

Risks & Disclaimer

• Code execution: Templates (and included plugins) can run arbitrary code at bake time.
• Elevated privileges: Running Blake from an elevated prompt increases potential impact.
• No absolute security: Even with checks, templates are not guaranteed safe. This will be made clear in the docs.

Users should only consume templates from sources they trust.

---

Planned Registry Workflow

Submission

• Contributors open a PR adding their template entry to TemplateRegistry.json.

• A PR template guides them to provide:

  • id (unique, kebab-case)
  • name
  • shortName
  • description
  • repoUrl
  • Any tags/categories

Automated Validation (CI)

1. Metadata Checks

   • JSON schema validation
   • Uniqueness of id, name, shortName

2. Quality Gates (block on fail)

   • Clone repo and run blake new -u <url>
   • Inject known sample content and run blake bake
   • Assert .generated contains expected output
   • dotnet build succeeds (if applicable)
   • Fail if unhandled exceptions or LogError events occur during bake

3. Sandboxed Bake Environment

   • Non-root user
   • No outbound network access (--network=none)
   • Read-only mount for repo, separate writable output dir
   • CPU/memory/time limits
   • Block if template attempts to write outside allowed paths or fails due to missing network during bake

4. Static Heuristics (warn, not block unless severe)

   • Detect potentially dangerous APIs (via regex/Roslyn):

     • Process.Start, P/Invoke, unsafe blocks
     • Registry access
     • Shell invocation (cmd.exe, bash, etc.)

   • Warn on:

     • HttpClient or other network classes (may be legit at runtime)
     • Vulnerable packages (dotnet list package --include-transitive --vulnerable)
     • Large binaries or executables checked in
     • Console.WriteLine usage in bake-time code (encourage ILogger)

5. Result Reporting

   • CI posts a PR comment summarizing pass/fail results and any warnings
   • Apply labels (verified, needs-review, security-warnings)

---

Versioning & Revalidation

• Store versions[] for each template with:

  • ref (tag or branch)
  • commit
  • validatedAt
  • toolVersion
  • status (verified/failed/revoked)

• defaultRef defines which version blake new --template uses.

• CLI warns if using an unvalidated version (--latest or --url).

• Cron Workflow:

  • Scan for new tags or branch updates.
  • Validate and update versions[] on success.
  • On failure, open an issue with details.

---

Deliverables

• PR template for submissions
• GitHub Actions workflow for validation
• Documentation updates for contributors & users

---

Tasks for Implementation

1. Review the complete requirements list above
2. Decide what checks are practical and worth implementing initially
3. Define sub-tasks/milestones for phased delivery.
4. Define the minimum passing criteria for registry inclusion
5. Determine whether to:
   • Implement all validation steps directly in GitHub Actions YAML, or
   • Build a dedicated .NET console tool (containerized) that runs the checks, with CI simply invoking it
6. Implement the CI workflow and PR template
7. Document the process and limitations clearly

---

Security Posture Statement

The registry workflow aims to:

• Guarantee that listed templates bake, build, and meet minimum quality standards
• Provide trust signals through basic automated checks
• Reduce but not eliminate risk of malicious templates

This is comparable to the trust model for NuGet packages and other plugin-based tools.

No guarantee of security is provided.