141 lines
2.6 KiB
Markdown
141 lines
2.6 KiB
Markdown
# 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](#post-api-auth)) you simply include it in the `Authorization` header of your request as a base-64 encoded string, i.e.
|
|
|
|
```
|
|
Authorization: base64(token)
|
|
```
|
|
|
|
### GET /api/publicKey
|
|
|
|
The [public key](https://en.wikipedia.org/wiki/Public-key_cryptography) unpkg uses to encrypt authentication tokens, as JSON. You can also find the key as plain text [on GitHub](https://github.com/unpkg/unpkg.com/blob/master/secret_key.pub).
|
|
|
|
This can be useful to verify a token was issued by unpkg.
|
|
|
|
Required scope: none
|
|
|
|
Query parameters: none
|
|
|
|
Example:
|
|
|
|
```log
|
|
> curl "https://unpkg.com/api/publicKey"
|
|
{
|
|
"publicKey": "..."
|
|
}
|
|
```
|
|
|
|
### POST /api/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/api/auth"
|
|
{
|
|
"token": "..."
|
|
}
|
|
```
|
|
|
|
Please reach out to @mjackson if you need a token with additional scopes.
|
|
|
|
### GET /api/auth
|
|
|
|
Verifies and returns the payload contained in the given auth token.
|
|
|
|
Required scope: none
|
|
|
|
Query parameters: none
|
|
|
|
Example:
|
|
|
|
```log
|
|
> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" "https://unpkg.com/api/auth"
|
|
{
|
|
"jti": "...",
|
|
"iss": "https://unpkg.com",
|
|
"iat": ...,
|
|
"scopes": { ... }
|
|
}
|
|
```
|
|
|
|
# Blacklist
|
|
|
|
To protect unpkg users and prevent abuse, unpkg manages a blacklist of npm packages that are known to contain harmful code.
|
|
|
|
### GET /api/blacklist
|
|
|
|
Returns a list of all packages that are currently blacklisted.
|
|
|
|
Required scope: `blacklist.read`
|
|
|
|
Query parameters: none
|
|
|
|
Example:
|
|
|
|
```log
|
|
> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" "https://unpkg.com/api/blacklist"
|
|
{
|
|
"blacklist": [ ... ]
|
|
}
|
|
```
|
|
|
|
### POST /api/blacklist
|
|
|
|
Adds a package to the blacklist.
|
|
|
|
Required scope: `blacklist.add`
|
|
|
|
Body parameters:
|
|
|
|
* `packageName` - The package to add to the blacklist (required)
|
|
|
|
Example:
|
|
|
|
```log
|
|
> curl -H "Authorization: $BASE_64_ENCODED_TOKEN" -d '{"packageName":"bad-package"}' "https://unpkg.com/api/blacklist"
|
|
{
|
|
"ok": true
|
|
}
|
|
```
|
|
|
|
### DELETE /api/blacklist
|
|
|
|
Removes a package from the blacklist.
|
|
|
|
Required scope: `blacklist.remove`
|
|
|
|
Body parameters:
|
|
|
|
* `packageName` - The package to remove from the blacklist (required)
|
|
|
|
Example:
|
|
|
|
```log
|
|
> curl -X DELETE -H "Authorization: $BASE_64_ENCODED_TOKEN" -d '{"packageName":"bad-package"}' "https://unpkg.com/api/blacklist"
|
|
{
|
|
"ok": true
|
|
}
|
|
```
|
|
|
|
# Stats
|
|
|
|
### GET /api/stats
|
|
|
|
TODO
|