akamai-edgegrid 3.1.2

package/README.md

@@ -0,0 +1,210 @@
+# EdgeGrid for Node.js
+
+[![Build Status](https://travis-ci.org/akamai/AkamaiOPEN-edgegrid-node.svg?branch=master)](https://travis-ci.org/akamai/AkamaiOPEN-edgegrid-node)
+
+This library implements an Authentication handler for the Akamai EdgeGrid Authentication scheme in Node.js. 
+
+It’s Akamai’s current and officially supported version of AkamaiOPEN EdgeGrid for Node.js. 
+You can find the most up-to-date package in [NPM](https://www.npmjs.com/package/akamai-edgegrid) under `akamai-edgegrid`.
+
+> __IMPORTANT:__ Akamai will not maintain the `edgegrid` package in NPM going forward.
+
+## Installation
+
+`npm install --save akamai-edgegrid`
+
+## Example
+
+### Credentials
+
+To use Akamai APIs you must first register and authorize a set of credentials through [Control Center](https://control.akamai.com). You can find more information on creating and authorizing credentials at [Authenticate with EdgeGrid](https://developer.akamai.com/getting-started/edgegrid).
+
+### .edgerc authentication
+
+The preferred method of using the library involves providing the path to an `.edgerc` file. This file contains the authentication credentials used to sign your requests.
+
+> __NOTE__: Requests to the API are signed with a timestamp and are executed immediately.
+
+```javascript
+var EdgeGrid = require('akamai-edgegrid');
+
+var data = 'bodyData';
+
+// Supply the path to your .edgerc file and name
+// of the section with authorization to the client
+// you are calling (default section is 'default')
+var eg = new EdgeGrid({
+  path: '/path/to/.edgerc',
+  section: 'section-name'
+});
+
+eg.auth({
+  path: '/diagnostic-tools/v1/locations',
+  method: 'GET',
+  headers: {},
+  body: data
+});
+
+eg.send(function(error, response, body) {
+  console.log(body);
+});
+```
+
+An `.edgerc` file contains sections for each of your API client credentials and is usually hosted in your home directory:
+
+```plaintext
+[default]
+host = akaa-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net/
+client_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
+client_secret = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+access_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
+max-body = 131072
+
+[section-name]
+host = akaa-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.luna.akamaiapis.net/
+client_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
+client_secret = XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+access_token = akab-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX
+max-body = 131072
+```
+
+### Manual authentication
+
+You can also authenticate manually by hard coding your credential values and passing them to the EdgeGrid client:
+
+```javascript
+var clientToken = "akab-client-token-xxx-xxxxxxxxxxxxxxxx",
+    clientSecret = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx=",
+    accessToken = "akab-access-token-xxx-xxxxxxxxxxxxxxxx",
+    baseUri = "https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/";
+
+var eg = new EdgeGrid(clientToken, clientSecret, accessToken, baseUri);
+```
+
+### Chaining
+
+You can also chain calls using the `akamai-edgegrid` like in this example:
+
+```javascript
+...
+eg.auth({
+  path: '/papi/v1/groups',
+  method: 'GET',
+  headers: {},
+}).send(function (error, response, body) {
+  console.log(body);
+});
+```
+### Headers
+
+Headers for the request must be supplied in an object as name-value pairs. You do not need to supply form-data headers or content lengths - that will cause authentication headers on the API.
+
+```javascript
+eg.auth({
+  path: '/papi/v1/groups',
+  method: 'GET',
+  headers: {
+    'Accept': "application/json"
+  }
+});
+```
+
+### Body data
+
+The request `body` can be provided as either an object or as a POST data formed string.
+
+
+```javascript
+// Object
+eg.auth({
+    path: '/papi/v1/cpcodes?contractId=ctr_1234&groupId=grp_1234',
+    method: 'POST',
+    body: {
+        cpcodeName: "test-cpcode",
+        productId: "prd_Site_Accel"
+    }
+});
+```
+  
+### Query string parameters
+
+Query string parameters must be supplied in an object as name-value pairs and 
+passed to the `auth` method under the `qs` property.
+
+```javascript
+eg.auth({
+    path: '/papi/v1/cpcodes',
+    method: 'POST',
+    headers: {},
+    qs: {
+        contractId: "ctr_1234",
+        groupId: "grp_1234",
+    },
+    body: data
+})
+
+// Produces request URL similar to:
+// https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/papi/v1/cpcodes?contractId=ctr_1234&groupId=grp_1234
+```
+
+### Debug
+
+With EdgeGrid you can enable debugging either as part of the EdgeGrid instantiation object
+or by setting the `EG_VERBOSE` environment variable. When enabled, EdgeGrid provides 
+additional information about the request that's helpful for debugging.
+
+Here's an EdgeGrid example:
+
+```javascript
+// Set debug via EdgeGrid property
+var eg = new EdgeGrid({
+  path: edgercPath,
+  section: sectionName,
+  debug: true
+});
+```
+
+And here's an example for a command-line argument:
+
+```bash
+// Set debug via environment variable
+$ export EG_VERBOSE=true
+$ node src/main.js
+
+Starting Request {
+  url: 'https://akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net/papi/v1/groups',
+  method: 'get',
+  data: '',
+  headers: {
+    common: { Accept: 'application/json, text/plain, */*' },
+    delete: {},
+...
+Response: {
+  status: 200,
+  statusText: 'OK',
+  headers: {
+    server: 'nginx',
+    'content-type': 'application/json;charset=UTF-8',
+...
+}
+```
+
+## Reporting issues
+
+To report a problem or make a suggestion, create a new [GitHub issue](https://github.com/akamai/AkamaiOPEN-edgegrid-node/issues).
+
+## License
+
+Copyright 2021 Akamai Technologies, Inc. All rights reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/index.js

@@ -0,0 +1,2 @@
+const EdgeGrid = require('./src/api.js');
+module.exports = EdgeGrid;

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "akamai-edgegrid",
+  "version": "3.1.2",
+  "description": "Authentication handler for the Akamai OPEN EdgeGrid Authentication scheme in Node.js",
+  "main": "index.js",
+  "scripts": {
+    "test": "EDGEGRID_ENV=test ./node_modules/.bin/mocha $(find test -name '*.js')"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/akamai-open/AkamaiOPEN-edgegrid-node.git"
+  },
+  "keywords": [
+    "akamai",
+    "open",
+    "api",
+    "edgegrid"
+  ],
+  "author": "Jonathan Bennett",
+  "contributors": [
+    "Darius Kazemi",
+    "Mike Ball",
+    "Kyle Tyacke"
+  ],
+  "license": "Apache-2.0",
+  "dependencies": {
+    "axios": "^0.21.4",
+    "log4js": "^0.6.14",
+    "moment": "^2.22.2",
+    "uuid": "^3.0.0"
+  },
+  "devDependencies": {
+    "mocha": "^9.0.1",
+    "nock": "^10.0.1"
+  }
+}

package/src/api.js

@@ -0,0 +1,163 @@
+// Copyright 2014 Akamai Technologies, Inc. All Rights Reserved
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const axios = require('axios'),
+    auth = require('./auth'),
+    edgerc = require('./edgerc'),
+    helpers = require('./helpers'),
+    logger = require('./logger');
+
+const EdgeGrid = function (client_token, client_secret, access_token, host, debug) {
+    // accepting an object containing a path to .edgerc and a config section
+    if (typeof arguments[0] === 'object') {
+        let edgercPath = arguments[0];
+        this._setConfigFromObj(edgercPath);
+    } else {
+        this._setConfigFromStrings(client_token, client_secret, access_token, host);
+    }
+    if (process.env.EG_VERBOSE || debug || (typeof arguments[0] === 'object' && arguments[0].debug)) {
+        axios.interceptors.request.use(request => {
+            console.log('Starting Request', request);
+            return request;
+        });
+        axios.interceptors.response.use(response => {
+            console.log('Response:', response);
+            return response;
+        });
+    }
+};
+
+/**
+ * Builds the request using the properties of the local config Object.
+ *
+ * @param  {Object} req The request Object. Can optionally contain a
+ *                      'headersToSign' property: An ordered list header names
+ *                      that will be included in the signature. This will be
+ *                      provided by specific APIs.
+ * @return EdgeGrid object (self)
+ */
+EdgeGrid.prototype.auth = function (req) {
+    let headers = {
+        'Content-Type': "application/json"
+    };
+    if (process.env['AKAMAI_CLI'] && process.env['AKAMAI_CLI_VERSION']) {
+        headers['User-Agent'] = (headers['User-Agent'] ? headers['User-Agent'] + " " : "") + `AkamaiCLI/${process.env['AKAMAI_CLI_VERSION']}`;
+    }
+    if (process.env['AKAMAI_CLI_COMMAND'] && process.env['AKAMAI_CLI_COMMAND_VERSION']) {
+        headers['User-Agent'] = (headers['User-Agent'] ? headers['User-Agent'] + " " : "") + `AkamaiCLI-${process.env['AKAMAI_CLI_COMMAND']}/${process.env['AKAMAI_CLI_COMMAND_VERSION']}`;
+    }
+    req = helpers.extend(req, {
+        baseURL: this.config.host,
+        url: req.path,
+        method: 'GET',
+        headers: headers,
+        maxRedirects: 0,
+        body: ''
+    });
+
+    let isTarball = req.body instanceof Uint8Array && req.headers['Content-Type'] === 'application/gzip';
+
+    // Convert body object to properly formatted string
+    if (req.body) {
+        if (typeof (req.body) == 'object' && !isTarball) {
+            req.body = JSON.stringify(req.body);
+        }
+    }
+    // this assignment is done in order to assert backwards compatibility of this library - a `body` field is accepted in this library, whereas axios expects the request body to be in `data` field
+    req.data = req.body;
+
+    this.request = auth.generateAuth(
+        req,
+        this.config.client_token,
+        this.config.client_secret,
+        this.config.access_token,
+        this.config.host
+    );
+    return this;
+};
+
+EdgeGrid.prototype.send = function (callback) {
+    axios(this.request).then(response => {
+        callback(null, response, JSON.stringify(response.data));
+    }).catch(error => {
+        // handling redirects has to be handled in catch (with maxRedirects set to 0) because axios does not allow modifying headers between redirects
+        if (error.response && helpers.isRedirect(error.response.status)) {
+            this._handleRedirect(error.response, callback);
+            return;
+        }
+        callback(error);
+    });
+
+    return this;
+};
+
+EdgeGrid.prototype._handleRedirect = function (resp, callback) {
+    const parsedUrl = new URL(resp.headers['location']);
+
+    resp.headers['authorization'] = undefined;
+    this.request.url = undefined;
+    this.request.path = parsedUrl.pathname + parsedUrl.search;
+
+    this.auth(this.request);
+    this.send(callback);
+};
+
+/**
+ * Creates a config object from a set of parameters.
+ *
+ * @param {String} client_token    The client token
+ * @param {String} client_secret   The client secret
+ * @param {String} access_token    The access token
+ * @param {String} host            The host
+ */
+EdgeGrid.prototype._setConfigFromStrings = function (client_token, client_secret, access_token, host) {
+    if (!validatedArgs([client_token, client_secret, access_token, host])) {
+        throw new Error('Insufficient Akamai credentials');
+    }
+
+    this.config = {
+        client_token: client_token,
+        client_secret: client_secret,
+        access_token: access_token,
+        host: host.indexOf('https://') > -1 ? host : 'https://' + host
+    };
+};
+
+function validatedArgs(args) {
+    const expected = [
+        'client_token', 'client_secret', 'access_token', 'host'
+    ];
+    let valid = true;
+
+    expected.forEach(function (arg, i) {
+        if (!args[i]) {
+            logger.error('No defined ' + arg);
+            valid = false;
+        }
+    });
+
+    return valid;
+}
+
+/**
+ * Creates a config     Object from the section of a defined .edgerc file.
+ *
+ * @param {Object} obj  An Object containing a path and section property that
+ *                      define the .edgerc section to use to create the Object.
+ */
+EdgeGrid.prototype._setConfigFromObj = function (obj) {
+    this.config = edgerc(obj.path, obj.section);
+};
+
+module.exports = EdgeGrid;

package/src/auth.js

@@ -0,0 +1,75 @@
+// Copyright 2014 Akamai Technologies, Inc. All Rights Reserved
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const uuid = require('uuid'),
+    helpers = require('./helpers'),
+    logger = require('./logger'),
+    url = require('url');
+
+function makeAuthHeader(request, clientToken, accessToken, clientSecret, timestamp, nonce, maxBody) {
+    const keyValuePairs = {
+        client_token: clientToken,
+        access_token: accessToken,
+        timestamp: timestamp,
+        nonce: nonce
+    };
+    let joinedPairs = '',
+        authHeader,
+        signedAuthHeader,
+        key;
+
+    for (key in keyValuePairs) {
+        joinedPairs += key + '=' + keyValuePairs[key] + ';';
+    }
+
+    authHeader = 'EG1-HMAC-SHA256 ' + joinedPairs;
+
+    logger.info('Unsigned authorization header: ' + authHeader + '\n');
+
+    signedAuthHeader = authHeader + 'signature=' + helpers.signRequest(request, timestamp, clientSecret, authHeader, maxBody);
+
+    logger.info('Signed authorization header: ' + signedAuthHeader + '\n');
+
+    return signedAuthHeader;
+}
+
+function makeURL(host, path, queryStringObj) {
+    const parsed = new URL(path, host);
+    if (queryStringObj) {
+        const queryFromObject = new url.URLSearchParams();
+        for (const key of Object.keys(queryStringObj)) {
+            queryFromObject.append(key, queryStringObj[key]);
+        }
+        parsed.search = queryFromObject.toString();
+    }
+
+    return url.format(parsed);
+}
+
+module.exports = {
+    generateAuth: function (request, clientToken, clientSecret, accessToken, host, maxBody, guid, timestamp) {
+        maxBody = maxBody || 131072;
+        guid = guid || uuid.v4();
+        timestamp = timestamp || helpers.createTimestamp();
+
+        if (!request.hasOwnProperty('headers')) {
+            request.headers = {};
+        }
+
+        request.url = makeURL(host, request.path, request.qs);
+        request.headers.Authorization = makeAuthHeader(request, clientToken, accessToken, clientSecret, timestamp, guid, maxBody);
+
+        return request;
+    }
+};

package/src/edgerc.js

@@ -0,0 +1,139 @@
+// Copyright 2014 Akamai Technologies, Inc. All Rights Reserved
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+const fs = require('fs'),
+    logger = require('./logger'),
+    helpers = require('./helpers');
+
+function getSection(lines, sectionName) {
+    const match = /^\s*\[(.*)]/,
+        section = [];
+
+    lines.some(function (line, i) {
+        const lineMatch = line.match(match),
+            isMatch = lineMatch !== null && lineMatch[1] === sectionName;
+
+        if (isMatch) {
+            // go through section until we find a new one
+            lines.slice(i + 1, lines.length).some(function (line) {
+                const isMatch = line.match(match) !== null;
+                if (!isMatch) {
+                    section.push(line);
+                }
+                return isMatch;
+            });
+        }
+        return isMatch;
+    });
+    return section;
+}
+
+function validatedConfig(config) {
+
+    if (!(config.host && config.access_token &&
+        config.client_secret && config.client_token)) {
+        let errorMessage = "";
+        const tokens =
+            ['client_token', 'client_secret', 'access_token', 'host'];
+        tokens.forEach(function (token) {
+            if (!config[token]) {
+                errorMessage += "\nMissing: " + token;
+            }
+        });
+        console.log('Missing part of the configuration:\n' + errorMessage);
+        return {};
+    }
+
+    if (config.host.indexOf('https://') > -1) {
+        return config;
+    }
+
+    config.host = 'https://' + config.host;
+
+    return config;
+}
+
+function buildObj(configs) {
+    const result = {};
+    let index,
+        key,
+        val,
+        parsedValue,
+        isComment;
+
+    configs.forEach(function (config) {
+        config = config.trim();
+        isComment = config.indexOf(";") === 0;
+        index = config.indexOf('=');
+        if (index > -1 && !isComment) {
+            key = config.substr(0, index);
+            val = config.substring(index + 1);
+            // remove inline comments
+            parsedValue = val.replace(/^\s*(['"])((?:\\\1|.)*?)\1\s*(?:;.*)?$/, "$2");
+            if (parsedValue === val) {
+                // the value is not contained in matched quotation marks
+                parsedValue = val.replace(/\s*([^;]+)\s*;?.*$/, "$1");
+            }
+            // Remove trailing slash as if often found in the host property
+            if (parsedValue.endsWith("/")) {
+                parsedValue = parsedValue.substr(0, parsedValue.length - 1);
+            }
+
+            result[key.trim()] = parsedValue;
+        }
+    });
+
+    return validatedConfig(result);
+}
+
+function readEnv(section) {
+    const requiredKeys = ["HOST", "ACCESS_TOKEN", "CLIENT_TOKEN", "CLIENT_SECRET"],
+        prefix = !section || section === "default" ? "AKAMAI_" : "AKAMAI_" + section.toUpperCase() + "_",
+        envConfig = {};
+
+
+    for (const key of requiredKeys) {
+        const varName = prefix + key;
+        if (!process.env[varName]) {
+            logger.debug("Environment variable not set: " + varName);
+            continue;
+        }
+        envConfig[key.toLowerCase()] = process.env[prefix + key];
+    }
+    if (Object.keys(envConfig).length < requiredKeys.length) {
+        return {};
+    }
+    console.log("Using configuration from environment variables");
+    return validatedConfig(envConfig);
+}
+
+module.exports = function (path, conf) {
+    const confSection = conf || 'default',
+        envConf = readEnv(confSection);
+    if (envConf['host']) {
+        return envConf;
+    }
+    if (!path) {
+        throw new Error("Either path to '.edgerc' or environment variables with edgerc configuration has to be provided.");
+    }
+    path = helpers.resolveHome(path);
+    const edgerc = fs.readFileSync(path).toString().split('\n'),
+        confData = getSection(edgerc, confSection);
+
+    if (!confData.length) {
+        throw new Error('An error occurred parsing the .edgerc file. You probably specified an invalid section name.');
+    }
+
+    return buildObj(confData);
+};