Add API docs

.gitignore

@@ -21,3 +21,4 @@ dump.rdb
 
 # keys
 private.key
+/tokens

docs/api.md

@@ -0,0 +1,131 @@
+# Authentication
+
+Some API methods require an authentication token. This token is a [JSON web token](https://en.wikipedia.org/wiki/JSON_Web_Token) that contains a list of "scopes" (i.e. permissions).
+
+Once you obtain an API token (see below) you can pass it to the server in one of two ways:
+
+  - For GET/HEAD requests, use the `?token` query parameter
+  - For all other requests, use the `{token}` parameter as part of the JSON in the request body
+
+### POST /\_auth
+
+Creates and returns a new auth token. By default, auth tokens have the following scopes:
+
+```json
+{
+  "blacklist": {
+    "read": true
+  }
+}
+```
+
+Required scope: none
+
+Body parameters: none
+
+Example:
+
+```log
+> curl -X POST "https://unpkg.com/_auth"
+{
+  "token": "eyJhbGciOiJS..."
+}
+```
+
+### GET /\_auth
+
+Verifies and returns the payload contained in the given auth token.
+
+Required scope: none
+
+Query parameters:
+
+  - `token` - The auth token to verify and decode
+
+Example:
+
+```log
+> curl "https://unpkg.com/_auth?token=$TOKEN"
+{
+  "jti": "...",
+  "iss": "https://unpkg.com",
+  "iat": ...,
+  "scopes": { ... }
+}
+```
+
+### GET /\_publicKey
+
+The [public key](https://en.wikipedia.org/wiki/Public-key_cryptography) unpkg uses to encrypt authentication tokens, in plain text. You can also find the key [on GitHub](https://github.com/unpkg/unpkg/blob/master/public.key).
+
+This can be useful to verify a token was issued by unpkg.
+
+Required scope: none
+
+Query parameters: none
+
+# Blacklist
+
+To protect unpkg users and prevent abuse, unpkg manages a blacklist of npm packages that are known to contain harmful code.
+
+### GET /\_blacklist
+
+Returns a list of all packages that are currently blacklisted.
+
+Required scope: `blacklist.read`
+
+Query parameters: none
+
+Example:
+
+```log
+> curl "https://unpkg.com/_blacklist?token=$TOKEN"
+{
+  "blacklist": [ ... ]
+}
+```
+
+### POST /\_blacklist
+
+Adds a package to the blacklist.
+
+Required scope: `blacklist.add`
+
+Body parameters:
+
+  - `token` - The auth token
+  - `packageName` - The package to add to the blacklist
+
+Example:
+
+```log
+> curl https://unpkg.com/_blacklist -d '{"token": "$TOKEN", "packageName": "bad-package"}'
+{
+  "ok": true
+}
+```
+
+### DELETE /\_blacklist/:packageName
+
+Removes a package from the blacklist.
+
+Required scope: `blacklist.remove`
+
+Body parameters:
+
+  - `token` - The auth token
+
+Example:
+
+```log
+> curl -X DELETE https://unpkg.com/_blacklist/bad-package -d '{"token": "$TOKEN"}'
+{
+  "ok": true
+}
+```
+
+# Stats
+
+### GET /\_stats
+
+TODO

scripts/add-blacklist.js

@@ -1,120 +0,0 @@
-const BlacklistAPI = require('../server/BlacklistAPI')
-
-const blacklist = [
-  'goodjsproject',
-  'thisoneisevil',
-  '03087dd164d4722425d74e095ff30bc2',
-  'sf1b195d16f3f3c695888e7cde1b20978f',
-  'sfd6e5f9f15adcc48d2fcb380e5aab44e5',
-  'sfd1f03b91ff97ff303bb69254ec3a4fd3',
-  'sf12fefe1d7b5bbe4d5661ff1bf6ea47bb',
-  'sfabae91ef175b31df2d7e77ed948206f7',
-  'sf149006f0b0c1c7e50e81181d9f5eba2d',
-  'sfe6bd27516125ae460d5c2e63feb70c97',
-  'sf09f01e9b87c212046c002a26f5117e87',
-  'sf77de34c6c6f180be3a03226cee219442',
-  'sf00e7081dec64c8557a40a79749e79d6c',
-  'sfb2c291b5ce9ee8cbc0ed4f9e7ab7c3d1',
-  'sf25d1f870f3355f4b02c34e65e451a8ef',
-  'sf18d48571145efc20316195ae19cf7aeb',
-  'sf694f2c2280ca2943d482059797ea1c97',
-  'sf2f8a5346ecda7e03f803b398dd40b869',
-  'sfaeebc97309de527e56215588f9c23dd3',
-  'sf2976f560d7ec7f8b63d7adca6728aed2',
-  'sf67de3bc862ca765e8cb9a72cf3453230',
-  'sfe906b050b2f380096de1c090dafdbb29',
-  'sfc98c62f745bac6d5f04c6e97e8294cec',
-  'sf979c8da13b915e5eaa5d84373a7c4a9b',
-  'sf6039ffb1c35d521773e4dcba7abf446c',
-  'sfb2adb7312558f6dde15d99619ee7da27',
-  'sfcba23f36564e58894e7aeebda67d3682',
-  'sfe0786b97c862c7485d9cec1b912bc634',
-  'sf024cf5fc99edfb929828b09084a9b6af',
-  'sf7d6d35c4dc2d6be739993cf054b00d35',
-  'sf78d0d2fbe897c94458a4822d624c969a',
-  'sf2b1bbe2c61f6f90cda322a61338003af',
-  'sff6a953f5f9960c2a1c907e186778d42f',
-  'sf748f0c277591c02438e9c325a8cb4ff5',
-  'sf606d995c90fd7c9fe17529a4697e4eb6',
-  'sf695459fe0eb159619268fdf542d3bb25',
-  'sf262b2b03ae6881a72365e05451b303ee',
-  'sf8a8a260ab891ae90eae8155548683053',
-  'sf9a307b3da7bfdcbb043c43857310d35b',
-  'sf3e5834662f7c780cbb60ee5740622d12',
-  'sff3a09cde265bde00a96ec01536a97029',
-  'sf364acb7b43655b3496aa65c7d6bb561a',
-  'sf89b5b735e7ba3bdfa52e7ae65026f9aa',
-  'sfca1c0beaf0309c9c322adddaa1cbd40b',
-  'sfef72db8254fe8714860d52da25b25fcc',
-  'sff3114fad67cd8b012706478c4b9fed39',
-  'sf1f60afa19f0a841aed6481bfcd91631c',
-  'sf785d637bd20673dbf2213f77e3df1cba',
-  'sf6142d76572f10a23113135dbee19dcf3',
-  'sf37544977bf1874afa4d4e9e282f2bf4a',
-  'sf0a49054aeba63d7f829eb3d02f0ad942',
-  'sfcce0358fa72b83d85569c22e715a920e',
-  'sf13890e52703bd39f71fb3815e555f0b7',
-  'sfe00cc3e9fec6974a4c1131bdb0ce5ee6',
-  'sf1343e7a08fa0ff25b6d215a3532bde13',
-  'sff4f6781701d8edd0e7909201c356d7c9',
-  'sf3d6dca96e72a14ecaed6ea97549fc088',
-  'sfaec6e7e100bfadbc4cf244adf277da15',
-  'sfa1b8f9052a194f3e9791769ce4cb352f',
-  'sf8cfdc43795d38e3d6ba6a57aae334c29',
-  'sf4606344a64d98d96120d5532b57b2a8b',
-  'sf7bdb20e4d622f6569f3e8503138c859d',
-  'sf0f4536523bf44a482a6bf466707c135e',
-  'sfc4a5204967899f098e8c6486cc60af7d',
-  'sf646dffa91307c680266d8e855b36f0be',
-  'sfa68a6cbd527e17f7e55b574b6a5a53ae',
-  'sff677d3897a4a7090aecfd5e13a6fc90b',
-  'sfbd0ffe85dc79f626ccb492a78aeda94f',
-  'sf37fe85de86dd3973db690594ae8b7bfc',
-  'sf54e90e7565b48823679af97d05189af4',
-  'sfb4ecfd026f1962076f3004cadc11931a',
-  'sfdb26212339dc18d5dd794fa800d4e5a6',
-  'sf4fdb84f60bad69846dd9fc9e2328a4f9',
-  'sfcfc008ec1b2a6daf70571b7480ba6aa3',
-  'sf1566a39461daff958cf2e4291ef13381',
-  'sf8a2b7d68f1c7c7f34381dc1a198465b4',
-  'sf3931b37c61d5b34186ca58f889d48047',
-  'sf109ad06b86e6be8f0c3e94d5e4893f47',
-  'sffefe6195a8b014a1cc7d9cf2449d1b50',
-  'sf85bacaf85076693e911b948b2c02535a',
-  'sf340a5f85afd785510da83f9cabf15726',
-  'sffee5fae47344c13e9d7c6db0bb403b76',
-  'sf4ec8bfe49e5a941b82bd07927f198b5d',
-  'sf2b10045997d4f1f120a5393be267cd52',
-  'sf14d2825be098ee2f80ead23cb181b8e4',
-  'sfc1c052ab23baf866cc73b3c585c65503',
-  'sfed9d0c920ecc6694c82ae859c1699758',
-  'sf15c3851aa68992e9b80ec11211e401bc',
-  'sf9c16721aff8f5ebb4fe7731a409eb622',
-  'sfc65f86a6d8598a4171dec7f4c99fc856',
-  'sf9b9ab3f53b6a705d772ca41a233be838',
-  'sf0d200aa244146e0054f93c7f98c134c8',
-  'sf3d9b13c2b94dea2a11a697d11f3312a8',
-  'sfdf5195f21fffc06298b7c0b4f6bcb9ba',
-  'sff25c5beafcd6f66bc2cc21e84f8aec85',
-  'copyfish-npm-2-8-5',
-  '54e90e7565b48823679af97d05189af4',
-  '15c3851aa68992e9b80ec11211e401bc',
-  '4fdb84f60bad69846dd9fc9e2328a4f9',
-  '14d2825be098ee2f80ead23cb181b8e4',
-  '024cf5fc99edfb929828b09084a9b6af',
-  '8a2b7d68f1c7c7f34381dc1a198465b4',
-  '7bdb20e4d622f6569f3e8503138c859d',
-  '694f2c2280ca2943d482059797ea1c97',
-  'b2c291b5ce9ee8cbc0ed4f9e7ab7c3d1',
-  '9b9ab3f53b6a705d772ca41a233be838',
-  'df5195f21fffc06298b7c0b4f6bcb9ba',
-  'fefe6195a8b014a1cc7d9cf2449d1b50',
-  'fee5fae47344c13e9d7c6db0bb403b76',
-  '2976f560d7ec7f8b63d7adca6728aed2',
-  'd6e5f9f15adcc48d2fcb380e5aab44e5',
-  'c98c62f745bac6d5f04c6e97e8294cec',
-  'abae91ef175b31df2d7e77ed948206f7',
-  '09f01e9b87c212046c002a26f5117e87'
-]
-
-blacklist.forEach(BlacklistAPI.addPackage)

scripts/create-token.js

@@ -1,6 +1,10 @@
 const AuthAPI = require('../server/AuthAPI')
 
-const scopes = {}
+const scopes = {
+  blacklist: {
+    read: true
+  }
+}
 
 AuthAPI.createToken(scopes).then(
   token => {

server/actions/createAuth.js

@@ -1,13 +1,13 @@
 const AuthAPI = require('../AuthAPI')
 
-const DefaultScopes = {
+const defaultScopes = {
   blacklist: {
     read: true
   }
 }
 
 function createAuth(req, res) {
-  AuthAPI.createToken(DefaultScopes).then(
+  AuthAPI.createToken(defaultScopes).then(
     token => {
       res.send({ token })
     },