Add API docs

mjackson · mjackson · commit ba6fb43aa4e1 · 2017-11-11T23:33:24.000-08:00
diff --git a/.gitignore b/.gitignore
@@ -21,3 +21,4 @@ dump.rdb
 
 # keys
 private.key
+/tokens
diff --git a/docs/api.md b/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
diff --git a/scripts/add-blacklist.js b/scripts/add-blacklist.js
diff --git a/scripts/create-token.js b/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 => {
diff --git a/server/actions/createAuth.js b/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 })
     },

Original file line number	Diff line number	Diff line change
`@@ -21,3 +21,4 @@ dump.rdb`
`21`	`21`
`22`	`22`	`# keys`
`23`	`23`	`private.key`
	`24`	`+/tokens`
Original file line number	Diff line number	Diff line change
`@@ -1,13 +1,13 @@`
`1`	`1`	`const AuthAPI = require('../AuthAPI')`
`2`	`2`
`3`		`-const DefaultScopes = {`
	`3`	`+const defaultScopes = {`
`4`	`4`	`blacklist: {`
`5`	`5`	`read: true`
`6`	`6`	`}`
`7`	`7`	`}`
`8`	`8`
`9`	`9`	`function createAuth(req, res) {`
`10`		`- AuthAPI.createToken(DefaultScopes).then(`
	`10`	`+ AuthAPI.createToken(defaultScopes).then(`
`11`	`11`	`token => {`
`12`	`12`	`res.send({ token })`
`13`	`13`	`},`