Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/mhart/aws4

Signs and prepares Node.js requests using AWS Signature Version 4
https://github.com/mhart/aws4

Last synced: 6 days ago
JSON representation

Signs and prepares Node.js requests using AWS Signature Version 4

Awesome Lists containing this project

README 

        
aws4

----



A small utility to sign [vanilla Node.js http(s)](https://nodejs.org/api/http.html) request options using Amazon's

[AWS Signature Version 4](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html).



If you want to sign and send AWS requests using [`fetch()`](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API), then check out [aws4fetch](https://github.com/mhart/aws4fetch) – otherwise you can also bundle this library for use [in older browsers](./browser).



The only AWS service I know of that *doesn't* support v4 is

[SimpleDB](https://docs.aws.amazon.com/AmazonSimpleDB/latest/DeveloperGuide/SDB_API.html)

(it only supports [AWS Signature Version 2](https://github.com/mhart/aws2)).



It also provides defaults for a number of core AWS headers and

request parameters, making it very easy to query AWS services, or

build out a fully-featured AWS library.



Example

-------



```javascript

var https = require('https')

var aws4  = require('aws4')



// to illustrate usage, we'll create a utility function to request and pipe to stdout

function request(opts) { https.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body || '') }



// aws4 will sign an options object as you'd pass to http.request, with an AWS service and region

var opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object', service: 's3', region: 'us-west-1' }



// aws4.sign() will sign and modify these options, ready to pass to http.request

aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })



// or it can get credentials from process.env.AWS_ACCESS_KEY_ID, etc

aws4.sign(opts)



// for most AWS services, aws4 can figure out the service and region if you pass a host

opts = { host: 'my-bucket.s3.us-west-1.amazonaws.com', path: '/my-object' }



// usually it will add/modify request headers, but you can also sign the query:

opts = { host: 'my-bucket.s3.amazonaws.com', path: '/?X-Amz-Expires=12345', signQuery: true }



// and for services with simple hosts, aws4 can infer the host from service and region:

opts = { service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' }



// and if you're using us-east-1, it's the default:

opts = { service: 'sqs', path: '/?Action=ListQueues' }



aws4.sign(opts)

console.log(opts)

/*

{

  host: 'sqs.us-east-1.amazonaws.com',

  path: '/?Action=ListQueues',

  headers: {

    Host: 'sqs.us-east-1.amazonaws.com',

    'X-Amz-Date': '20121226T061030Z',

    Authorization: 'AWS4-HMAC-SHA256 Credential=ABCDEF/20121226/us-east-1/sqs/aws4_request, ...'

  }

}

*/



// we can now use this to query AWS

request(opts)

/*



...

*/



// aws4 can infer the HTTP method if a body is passed in

// method will be POST and Content-Type: 'application/x-www-form-urlencoded; charset=utf-8'

request(aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' }))

/*



...

*/



// you can specify any custom option or header as per usual

request(aws4.sign({

  service: 'dynamodb',

  region: 'ap-southeast-2',

  method: 'POST',

  path: '/',

  headers: {

    'Content-Type': 'application/x-amz-json-1.0',

    'X-Amz-Target': 'DynamoDB_20120810.ListTables'

  },

  body: '{}'

}))

/*

{"TableNames":[]}

...

*/



// you can also specify extra headers to ignore during signing

request(aws4.sign({

  host: '07tjusf2h91cunochc.us-east-1.aoss.amazonaws.com',

  method: 'PUT',

  path: '/my-index',

  body: '{"mappings":{}}',

  headers: {

    'Content-Type': 'application/json',

    'X-Amz-Content-Sha256': 'UNSIGNED-PAYLOAD'

  },

  extraHeadersToIgnore: {

    'content-length': true

  }

}))



// and headers to include that would normally be ignored

request(aws4.sign({

  service: 'mycustomservice',

  path: '/whatever',

  headers: {

    'Range': 'bytes=200-1000, 2000-6576, 19000-'

  },

  extraHeadersToInclude: {

    'range': true

  }

}))



// The raw RequestSigner can be used to generate CodeCommit Git passwords

var signer = new aws4.RequestSigner({

  service: 'codecommit',

  host: 'git-codecommit.us-east-1.amazonaws.com',

  method: 'GIT',

  path: '/v1/repos/MyAwesomeRepo',

})

var password = signer.getDateTime() + 'Z' + signer.signature()



// see example.js for examples with other services

```



API

---



### aws4.sign(requestOptions, [credentials])



Calculates and populates any necessary AWS headers and/or request

options on `requestOptions`. Returns `requestOptions` as a convenience for chaining.



`requestOptions` is an object holding the same options that the Node.js

[http.request](https://nodejs.org/docs/latest/api/http.html#http_http_request_options_callback)

function takes.



The following properties of `requestOptions` are used in the signing or

populated if they don't already exist:



- `hostname` or `host` (will try to be determined from `service` and `region` if not given)

- `method` (will use `'GET'` if not given or `'POST'` if there is a `body`)

- `path` (will use `'/'` if not given)

- `body` (will use `''` if not given)

- `service` (will try to be calculated from `hostname` or `host` if not given)

- `region` (will try to be calculated from `hostname` or `host` or use `'us-east-1'` if not given)

- `signQuery` (to sign the query instead of adding an `Authorization` header, defaults to false)

- `extraHeadersToIgnore` (an object with lowercase header keys to ignore when signing, eg `{ 'content-length': true }`)

- `extraHeadersToInclude` (an object with lowercase header keys to include when signing, overriding any ignores)

- `headers['Host']` (will use `hostname` or `host` or be calculated if not given)

- `headers['Content-Type']` (will use `'application/x-www-form-urlencoded; charset=utf-8'`

  if not given and there is a `body`)

- `headers['Date']` (used to calculate the signature date if given, otherwise `new Date` is used)



Your AWS credentials (which can be found in your

[AWS console](https://portal.aws.amazon.com/gp/aws/securityCredentials))

can be specified in one of two ways:



- As the second argument, like this:



```javascript

aws4.sign(requestOptions, {

  secretAccessKey: "",

  accessKeyId: "",

  sessionToken: ""

})

```



- From `process.env`, such as this:



```

export AWS_ACCESS_KEY_ID=""

export AWS_SECRET_ACCESS_KEY=""

export AWS_SESSION_TOKEN=""

```



(will also use `AWS_ACCESS_KEY` and `AWS_SECRET_KEY` if available)



The `sessionToken` property and `AWS_SESSION_TOKEN` environment variable are optional for signing

with [IAM STS temporary credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html).



Installation

------------



With [npm](https://www.npmjs.com/) do:



```

npm install aws4

```



Can also be used [in the browser](./browser).



Thanks

------



Thanks to [@jed](https://github.com/jed) for his

[dynamo-client](https://github.com/jed/dynamo-client) lib where I first

committed and subsequently extracted this code.



Also thanks to the

[official Node.js AWS SDK](https://github.com/aws/aws-sdk-js) for giving

me a start on implementing the v4 signature.