secure-link/README.md

Functions to generate and validate resource access tokens.

# secure-link
Paid digital content and user-uploaded content require access control. To implement authorization, it's common to
generate a token, which is appended to the resource's location as a query string parameter. This module provides
functions to generate secure access tokens, which can be used with Nginx, Cloudflare, Fastly or your own application.


## Installation
```sh
npm install secure-link
```

## Usage
### Nginx

To generate a token, pass the resource's location and a secret key to the `generateNginxAccessToken`
function. It optionally accepts a `lifetime` parameter, which will determine the date after which the
token should be considered expired. It must be set in seconds since the epoch. For more information, check
out the [ngx_http_secure_link_module](http://nginx.org/en/docs/http/ngx_http_secure_link_module.html)
documentation.

```javascript
const { generateNginxAccessToken } = require('secure-link');

const timeInSeconds = Math.round(Date.now() / 1000);
const expirationTime = timeInSeconds + 86400;

const options = {
  secret: process.env.SECRET_KEY,
  path: '/secure/statement.pdf',
  lifetime: expirationTime
};

const token = generateNginxAccessToken(options);
```
From there, you can append the token as a query string parameter.
```javascript
const url = `https://cdn.example.com/secure/statement.pdf?token=${token}&expires=${expirationTime}`;
```
To validate the token when a request is received, you can hash the request URL and secret in a
location block. The `secure_link_md5` directive matches the format used by `generateNginxAccessToken`
internally when creating tokens. Replace `secret` with the secret used to create the token to ensure
the hashes are the same.

```nginx
location /secure {
    secure_link $arg_token,$arg_expires;
    secure_link_md5 "$uri$secure_link_expires secret";

    # Token mismatch
    if ($secure_link = "") {
      return 403;
    }

    # Token expired
    if ($secure_link = "0") {
      return 410;
    }

    alias /path/to/directory;
}
```

### Cloudflare

Coming soon...

### Fastly

Coming soon...