Audit application installations

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 - Fixed #16 - New users were causing an error in findPromotions
 - Fixed #20 - Added full JSDoc coverage across the code
+- Fixed #23 - Added auditing of application installations
 
 ## 0.1.0
 

README.md

@@ -124,6 +124,47 @@ does have the side effect that, if an internal username is connected to multiple
 GitHub usernames, as demonstrated above, all of those GitHub usernames will be
 made admins of the org.
 
+### [[applications]]
+
+Each `[[applications]]` section represents one org-level application
+installation. These entries are used to ensure that no applications get added to
+or removed from the org unexpectedly. You can also ensure that they only have
+the permissions you are expecting, and receive the events you are expecting.
+
+Similar to the `[[teams]]` above, applications are specified as an [array of
+tables]. In addition, the applications use a sub-table for the permissions,
+making a single application specification look like the following:
+
+```toml
+[[applications]]
+appId = 42
+appSlug = "infinite-improbability-drive"
+repositorySelection = "selected"
+events = ["issues", "discussion", "pull_request"]
+
+[applications.permissions]
+# This applies to the application directly above, infinite-improbability-drive
+checks = "read"
+issues = "read"
+metadata = "read"
+deployments = "write"
+```
+
+Given the flexibility of TOML, you can also specify the `permissions` table
+in-line, depending on your preference. That would look like this:
+
+```toml
+[[applications]]
+appId = 42
+appSlug = "infinite-improbability-drive"
+repositorySelection = "selected"
+events = ["issues", "discussion", "pull_request"]
+permissions = {checks = "read", issues = "read", metadata = "read", deployments = "write"}
+```
+
+Both of the above are wholly equivalent; it's simply a matter of preference
+which way you would like to specify them.
+
 ## Development
 
 ### Running Tests

example.toml

@@ -19,3 +19,16 @@ name = "Heart of Gold Crew"
 default_org_role = "ADMIN"
 privacy = "SECRET"
 members = ["mandroid", "tmcmillan", "zbeeblebrox"]
+
+[[applications]]
+appId = 42
+appSlug = "infinite-improbability-drive"
+repositorySelection = "selected"
+events = ["issues", "discussion", "pull_request"]
+
+[applications.permissions]
+# This applies to the application directly above, infinite-improbability-drive
+checks = "read"
+issues = "read"
+metadata = "read"
+deployments = "write"

package.json

@@ -32,6 +32,7 @@
     "eslint-plugin-mocha": "^6.3.0",
     "eslint-plugin-node": "^11.1.0",
     "mocha": "^8.2.1",
+    "nock": "^13.0.7",
     "nyc": "^15.1.0",
     "sinon": "^9.2.4"
   },

src/lib/loaders.js

@@ -3,6 +3,7 @@
 
 const fs = require('fs').promises;
 const { graphql } = require('@octokit/graphql');
+const { request } = require('@octokit/request');
 const TOML = require('@iarna/toml');
 const typedefs = require('./typedefs');
 
@@ -94,12 +95,39 @@ async function retrieveOrgInfo(orgName, token) {
     // eslint-disable-next-line id-length
     requiresTwoFactorAuthentication: organization.requiresTwoFactorAuthentication,
     twitterUsername: organization.twitterUsername,
-    websiteUrl: organization.websiteUrl
+    websiteUrl: organization.websiteUrl,
+    applications: await retrieveOrgApplications(orgName, token)
   };
   console.log(`${Object.keys(result.members).length} total members retrieved.`);
   return result;
 }
 
+/**
+ * Retrieve a list of all applications installed to the requested org
+ *
+ * @param {string} orgName - The login name of the org to retrieve applications for
+ * @param {string} token - A personal access token for interacting with the API
+ * @returns {typedefs.AppSet} - A list of all applications installed on the organization
+ */
+async function retrieveOrgApplications(orgName, token) {
+  const response = await request('GET /orgs/{org}/installations', {
+    headers: { authorization: `token ${token}` },
+    org: orgName
+  });
+  const result = response.data.installations.reduce((apps, app) => {
+    apps.push({
+      appId: app.app_id,
+      appSlug: app.app_slug,
+      repositorySelection: app.repository_selection,
+      permissions: app.permissions,
+      events: app.events
+    });
+    return apps;
+  }, []);
+  console.log(`Loaded ${result.length} application installations for ${orgName}.`);
+  return result;
+}
+
 /**
  * Load an org's expected configuration from a TOML config file
  *
@@ -132,4 +160,4 @@ async function loadMembershipConfig(fileName) {
   return config;
 }
 
-module.exports = { retrieveOrgInfo, loadMembershipConfig };
+module.exports = { retrieveOrgInfo, retrieveOrgApplications, loadMembershipConfig };

src/lib/typedefs.js

@@ -14,6 +14,23 @@
  * @typedef {object.<string, MemberRecord>} MemberSet
  */
 
+/**
+ * A normalized application installation record retrieved from the GitHub REST API
+ *
+ * @typedef {object} AppRecord
+ * @property {number} appId - The global database identifier for the application
+ * @property {string} appSlug - A unique slug for identifying the application
+ * @property {string} repositorySelection - Whether this is installed for "all" or "selected" repositories
+ * @property {object.<string, string>} permissions - The set of permissions granted to this application
+ * @property {Array.<string>} events - A list of events that are received by this application
+ */
+
+/**
+ * A set of application installation records retrieved from the GitHub REST API
+ *
+ * @typedef {Array.<AppRecord>} AppSet
+ */
+
 /**
  * A normalized org record retrieved from the GitHub GraphQL API
  *

test/loaders.spec.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const assume = require('assume');
+const fs = require('fs').promises;
+const loaders = require('../src/lib/loaders');
+const nock = require('nock');
+const path = require('path');
+const sinon = require('sinon');
+
+
+describe('Loaders', function () {
+
+  before(function () {
+    sinon.stub(console, 'log');
+  });
+
+  after(function () {
+    sinon.restore();
+  });
+
+  describe('retrieveOrgApplications', function () {
+    let scope;
+
+    before(async function () {
+      const response = JSON.parse(await fs.readFile(path.resolve(__dirname, 'responses/installations.json')));
+      scope = nock(
+        'https://api.github.com/',
+        { reqheaders: { authorization: 'token 12345' } }
+      ).get('/orgs/foo/installations').reply(200, response).persist();
+    });
+
+    after(function () {
+      nock.cleanAll();
+    });
+
+    it('calls the proper REST endpoint', async function () {
+      await loaders.retrieveOrgApplications('foo', '12345');
+      scope.done();
+    });
+
+    it('returns only the relevant information', async function () {
+      const apps = await loaders.retrieveOrgApplications('foo', '12345');
+
+      assume(apps).eqls([
+        {
+          appId: 12,
+          appSlug: 'heart-of-gold',
+          repositorySelection: 'all',
+          permissions: {
+            foo: 'read',
+            bar: 'write',
+            baz: 'read'
+          },
+          events: ['push', 'release']
+        },
+        {
+          appId: 13,
+          appSlug: 'infinite-improbability-drive',
+          repositorySelection: 'selected',
+          permissions: {
+            foo: 'write',
+            bar: 'read',
+            baz: 'write'
+          },
+          events: ['issue', 'discussion', 'pull_request']
+        }
+      ]);
+    });
+  });
+});