This document outlines why the manifest was designed this way.

The manifest serves a couple purposes:

  • Generating the mod list
  • Powering a mod manager and/or auto-updater

Main Design Goals

  • Central source of truth for all community-reviewed mods
  • Machine-readable (human-readable versions can be automatically generated by a machine)
  • Secure

The Problem

The problem is outdated mods, and the work involved in keeping them updated. Why it’s a problem:

  • Outdated versions may be broken
  • It’s not obvious when you’re running an outdated version
  • It’s a decent amount of manual work to update a single mod. Multiply that by every mod you use when you return after taking a break from the game.
  • Mods shouldn’t be rolling their own auto-updaters
    • Security concerns
    • Non-uniform experience
    • Doing it all from one mod manager simply makes more sense

The Solution

We make a mod manager that can automatically install and update mods. Easier said than done, though. This will definitely take time to build well, because the requirements to make this are a bit more than what it would initially seem. The VRChat Modding Group has a great example of what this could look like, and for them it was years and tens of thousands of users before they had it put together. This mod manager will need some API of available mods, which is what we’re designing here.

Proposed design:

  1. A single-endpoint “API” that provides a JSON manifest of known good mods
    • This will simply be a JSON file hosted in a github repo
    • Mod devs can PR in metadata about their new mod releases
    • Members of the community will be able to review and approve PRs, and once enough trustworthy approvals are collected we can merge the PR.
    • Only PRs with a certain number of approvals will be mergeable. Ideally, I want at least 2 approvals, but if the community is sleepy maybe 1 will suffice.
    • PR authors are forbidden from self-approving their own mods
  2. A mod manager (auto-updater GUI client)
    • Fetches the manifest and uses it to install and update mods
    • Validates mod integrity clientside

Security

The security concerns about auto-updaters are huge.

  • Mods are coming from dozens of different users, who are relatively unknown and don’t have any sort of trust built up. This presents a pretty large risk:
    • Any one of these modders might have their credentials compromised
    • A malicious actor could hide in the crowd of non-malicious modders
    • A malicious actor could remain anonymous, which wouldn’t be unusual for a modder
  • We need a mechanism to mark a previously distributed mod as having a security vulnerability
  • Having a mod review process shifts the trust issue from the mod devs to the reviewers
    • Corruption issues? Solved via transparency.
      • We must publicly record ALL mod reviews, who specifically approved/denied the mod, and rejection reasons if applicable
  • An auto-updater further increases risk, because now you’re automatically grabbing and executing binaries
    • The auto-updater itself has an attack surface.
      • If it doesn’t use TLS it’s vulnerable to MITM
      • If it downloads binaries from an untrusted source there’s all sorts of nefarious things that could happen
      • If it loads assemblies to inspect them it might accidentally execute them
    • As the auto-updater has potential security pitfalls and attack surfaces, you want to only have one. If every mod has its own auto-updater that’s just an auditing nightmare.
  • Github artifacts are NOT immutable, meaning a fixed URL does not guarantee a fixed file. Therefore we MUST verify artifacts clientside.
    • Checking against a SHA-256 hash in the manifest is a secure way of doing this

At minimum, we have to trust:

  • The auto-updater
    • Client
      • Maintainer
    • API
      • Maintainer
      • Host (github)
    • artifact hashing algorithm (SHA-256)
  • Mod reviewers
    • various community members
    • trusted community members with merge permissions

Why use GitHub?

  • git’s commit log is well suited to our goal of keeping manifest history public
  • GitHub’s PR feature solves a couple of problems:
    • It keeps the review process transparent
    • It is specifically designed for maintainers to review community submissions to a text file
  • GitHub provides an easy way for us to host our json file at no cost

Implementation

The manifest is hosted on GitHub.

Mods can have various flags, which can be used to indicate, outdated, broken, or insecure mods.

The mod review process is outlined here.

The manifest schema is outlined here.