README.md

@@ -10,9 +10,29 @@ contributions.
 
 ## Setup
 
+### Ethereum wallet
+
 You will need an Ethereum wallet for your bot, so it can interact with the
 Ethereum smart contracts. `npm run create-wallet` will do the job for you.
 
+The wallet must be funded with enough ETH to interact with the contracts.
+
+### Contract permissions
+
+The bot wallet needs the following Aragon contract permissions to interact
+with [kredits-contracts]:
+
+1. `ADD_CONTRIBUTION_ROLE` on the `Contribution` contract
+2. `MANAGE_CONTRIBUTORS_ROLE` on the `Contributor` contract
+
+These permissions can be configured using the [Aragon
+CLI](https://hack.aragon.org/docs/cli-intro.html) (see [kredits-contracts].
+
+    aragon dao acl grant [DAO address] [contribution app address] ADD_CONTRIBUTION_ROLE [bot wallet address]
+    aragon dao acl grant [DAO address] [contributor app address] MANAGE_CONTRIBUTORS_ROLE [bot wallet address]
+
+To get the `Contribution` and `Contributor` app addresses use `aragon dao apps`.
+
 ## Configuration
 
 As usual in Hubot, you can add all config as environment variables.
@@ -26,7 +46,9 @@ As usual in Hubot, you can add all config as environment variables.
 | `KREDITS_PROVIDER_URL` | Ethereum JSON-RPC URL (default: `http://localhost:7545`) |
 | `KREDITS_WEB_URL` | URL of the Kredits Web app (default: `https://kredits.kosmos.org`) |
 | `KREDITS_DAO_ADDRESS` | DAO Kernel address |
-| `SESSION_SECRET` | Secret used to sign the Session ID |
+| `KREDITS_SESSION_SECRET` | Secret used by [grant](https://www.npmjs.com/package/grant) to sign the session ID |
+| `KREDITS_GRANT_HOST` | Host used by [grant](https://www.npmjs.com/package/grant) to generate OAuth redirect URLs (default: `localhost:8888`) |
+| `KREDITS_GRANT_PROTOCOL` | Protocol (http or https) used by [grant](https://www.npmjs.com/package/grant") to generate the OAuth redirect URLs (default: "http") |
 
 ## Integrations
 
@@ -37,6 +59,12 @@ which carry a kredits label: `kredits-1`, `kredits-2`, `kredits-3` for small,
 medium and large contributions. If there are multiple people assigned, it will
 issue contribution tokens for all of them.
 
+If `KREDITS_GITHUB_KEY` and `KREDITS_GITHUB_SECRET` are set, the bot will also
+expose OAuth endpoints to authenticate new contributors and register new
+contributor profiles on the smart contract. For this feature, a [GitHub OAuth
+app] is required and the [OAuth grant config variables](#Configuration) must be
+set.
+
 #### Setup
 
 Point a GitHub organization webhook to the following URL:
@@ -48,6 +76,8 @@ Point a GitHub organization webhook to the following URL:
 | Key | Description |
 | --- | --- |
 | `KREDITS_GITHUB_REPO_BLACKLIST` | Repos which you do not want to issue kredits for. Format: `orgname/reponame`, e.g. `67P/test-one-two` |
+| `KREDITS_GITHUB_KEY` | Key of the [GitHub OAuth app] used to authenticate contributors |
+| `KREDITS_GITHUB_SECRET` | Secret of the [GitHub OAuth app] used to authenticate contributors |
 
 ### Gitea
 
@@ -83,3 +113,6 @@ wiki's API on its own.
 | Key | Description |
 | --- | --- |
 | `KREDITS_MEDIAWIKI_URL` | Your wiki URL, e.g. `https://wiki.kosmos.org/` |
+
+[kredits-contracts]: https://github.com/67P/kredits-contracts
+[GitHub OAuth app]: https://developer.github.com/apps/about-apps/#about-oauth-apps

integrations/github.js

@@ -181,23 +181,23 @@ module.exports = async function(robot, kredits) {
   // GitHub signup
   //
 
-  if (process.env.GITHUB_KEY && process.env.GITHUB_SECRET) {
+  if (process.env.KREDITS_GITHUB_KEY && process.env.KREDITS_GITHUB_SECRET) {
     const grantConfig = {
       defaults: {
-        protocol: (process.env.GRANT_PROTOCOL || "http"),
+        protocol: (process.env.KREDITS_GRANT_PROTOCOL || "http"),
-        host: (process.env.GRANT_HOST || 'localhost:8888'),
+        host: (process.env.KREDITS_GRANT_HOST || 'localhost:8888'),
         transport: 'session',
         response: 'tokens',
         path: '/kredits/signup'
       },
       github: {
-        key: process.env.GITHUB_KEY,
+        key: process.env.KREDITS_GITHUB_KEY,
-        secret: process.env.GITHUB_SECRET,
+        secret: process.env.KREDITS_GITHUB_SECRET,
         callback: '/kredits/signup/github'
       }
     };
 
-    robot.router.use(session({ secret: process.env.SESSION_SECRET || 'grant' }));
+    robot.router.use(session({ secret: process.env.KREDITS_SESSION_SECRET || 'grant' }));
     robot.router.use('/kredits/signup', grant(grantConfig));
 
     robot.router.get('/kredits/signup/github', async (req, res) => {
@@ -266,6 +266,6 @@ module.exports = async function(robot, kredits) {
       }
     });
   } else {
-    robot.logger.warning('[hubot-kredits] No GITHUB_KEY and GITHUB_SECRET configured for OAuth signup');
+    robot.logger.warning('[hubot-kredits] No KREDITS_GITHUB_KEY and KREDITS_GITHUB_SECRET configured for OAuth signup');
   }
 };