Idea: verify matching tags and signed commit status

[lirantal]

Idea for a new marshall

1. Verify that an npm version on the npm registry matches a released tag on the GitHub source code
2. Further follow the released tag details to ensure that it was created as a signed commit

How to do it?

Verify released tag on GitHub

We establish (1) by finding the GitHub tag using this API request:

https://api.github.com/repos/lirantal/dockly/git/ref/tags/v3.21.2

That returns this JSON:

{
  "ref": "refs/tags/v3.21.2",
  "node_id": "MDM6UmVmNzE2Njc0OTg6cmVmcy90YWdzL3YzLjIxLjI=",
  "url": "https://api.github.com/repos/lirantal/dockly/git/refs/tags/v3.21.2",
  "object": {
    "sha": "f0c1c7360ad02d78caccb91fd4816ebee66a712a",
    "type": "commit",
    "url": "https://api.github.com/repos/lirantal/dockly/git/commits/f0c1c7360ad02d78caccb91fd4816ebee66a712a"
  }
}

It's probable that we need to run a few calls with heuristics around the version naming, i.e: with a leading v prefix and without, depending on the conventions of the repository.

Verify signed tag released

From the request above, we can follow the url returned in the object (https://api.github.com/repos/lirantal/dockly/git/commits/f0c1c7360ad02d78caccb91fd4816ebee66a712a) and get more detailed information about this release:

{
  "sha": "f0c1c7360ad02d78caccb91fd4816ebee66a712a",
  "node_id": "MDY6Q29tbWl0NzE2Njc0OTg6ZjBjMWM3MzYwYWQwMmQ3OGNhY2NiOTFmZDQ4MTZlYmVlNjZhNzEyYQ==",
  "url": "https://api.github.com/repos/lirantal/dockly/git/commits/f0c1c7360ad02d78caccb91fd4816ebee66a712a",
  "html_url": "https://github.com/lirantal/dockly/commit/f0c1c7360ad02d78caccb91fd4816ebee66a712a",
  "author": {
    "name": "Liran Tal",
    "email": "liran.tal@gmail.com",
    "date": "2021-06-24T12:42:43Z"
  },
  "committer": {
    "name": "GitHub",
    "email": "noreply@github.com",
    "date": "2021-06-24T12:42:43Z"
  },
  "tree": {
    "sha": "ad8e046a6315d46a19c8a909b72f19be74f6f508",
    "url": "https://api.github.com/repos/lirantal/dockly/git/trees/ad8e046a6315d46a19c8a909b72f19be74f6f508"
  },
  "message": "fix: enforce correct fonts/locales setup in docker (#169)",
  "parents": [
    {
      "sha": "f85fb02cfde14b2ecbaaaca8979d41157bc5ab43",
      "url": "https://api.github.com/repos/lirantal/dockly/git/commits/f85fb02cfde14b2ecbaaaca8979d41157bc5ab43",
      "html_url": "https://github.com/lirantal/dockly/commit/f85fb02cfde14b2ecbaaaca8979d41157bc5ab43"
    }
  ],
  "verification": {
    "verified": true,
    "reason": "valid",
    "signature": "-----BEGIN PGP SIGNATURE-----\n\nwsBcBAABCAAQBQJg1H3DCRBK7hj4Ov3rIwAAb9gIAJyIduEKEds6TjWOIE+L/7sf\nXScIRV5Z7kUNlH5tIxWCBCsM/rlFqp/9VYQxJNxYJaln6suG9dkaciSwtc3dit7Y\nPyWuxXplRAnyDoCRUh14DXFD9+Q/UtkGGClHGUhXLkWwVPiWkI8zU23eK/uD6EWw\nXSsAohGHmYrRbAyiHA1eLJ7jdSBy6T+3frHAinU/jDXqEW1yeyRZph058FWHq/6n\nbOHQ+GjD8gbM/E1jj5Yd+VrP0Oks9olNmCSvntUEibhprcv1TYRnCFPx/sppgUSH\nyfC1cQ88T/lskqcPJ1rdabcTglhfM1F9jxfXeUXNZt9P2aE4WOB9ovMmrrrV/0k=\n=bXen\n-----END PGP SIGNATURE-----\n",
    "payload": "tree ad8e046a6315d46a19c8a909b72f19be74f6f508\nparent f85fb02cfde14b2ecbaaaca8979d41157bc5ab43\nauthor Liran Tal <liran.tal@gmail.com> 1624538563 +0300\ncommitter GitHub <noreply@github.com> 1624538563 +0300\n\nfix: enforce correct fonts/locales setup in docker (#169)\n\n"
  }
}

This payload now provides verification information and other useful information about the author of the release that we can verify against the maintainers of the package and so on.