JSPM – aws4@0.1.2

Package Exports

aws4

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (aws4) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

aws4

A small utility to sign vanilla node.js http(s) request options using Amazon's AWS Signature Version 4.

It also provides defaults for a number of core AWS headers and request parameters, making it a very easy to query AWS services, or build out a fully-featured AWS library.

Example

var http  = require('http')
  , https = require('https')
  , aws4  = require('aws4')

// given an options object you could pass to http.request
var opts = { host: 'sqs.us-east-1.amazonaws.com', path: '/?Action=ListQueues' }

aws4.sign(opts) // assumes AWS credentials are available in process.env

// opts.headers now contains the signed AWS headers, and is ready for
// use in standard node.js http(s) requests

// eg, pipe the SOAP response from the above SQS request to stdout
http.request(opts, function(res) { res.pipe(process.stdout) }).end()

// you can pass AWS credentials in explicitly
aws4.sign(opts, { accessKeyId: '', secretAccessKey: '' })

// aws4 can infer the host from a service and region
opts = aws4.sign({ service: 'sqs', region: 'us-east-1', path: '/?Action=ListQueues' })

// aws4 can infer the HTTP method if a body is passed in
opts = aws4.sign({ service: 'iam', body: 'Action=ListGroups&Version=2010-05-08' })

// opts.method will now be POST and Content-Type: 'application/x-www-form-urlencoded'
https.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body)

// can specify any custom option or header as per usual
opts = aws4.sign({
  service: 'dynamodb',
  region: 'ap-southeast-2',
  method: 'POST',
  path: '/',
  headers: {
    'Content-Type': 'application/x-amz-json-1.0',
    'X-Amz-Target': 'DynamoDB_20111205.ListTables'
  },
  body: '{}'
})
http.request(opts, function(res) { res.pipe(process.stdout) }).end(opts.body)

// works with all other services that support Signature Version 4

opts = aws4.sign({ service: 'sts', path: '/?Action=GetSessionToken&Version=2011-06-15' })
https.request(opts, function(res) { res.pipe(process.stdout) }).end()

opts = aws4.sign({ service: 'glacier', path: '/-/vaults', headers: { 'X-Amz-Glacier-Version': '2012-06-01' } })
https.request(opts, function(res) { res.pipe(process.stdout) }).end()

opts = aws4.sign({ service: 'cloudsearch', path: '/?Action=DescribeDomains' })
https.request(opts, function(res) { res.pipe(process.stdout) }).end()

API

aws4.sign(requestOptions, [credentials])

This calculates and populates the Authorization header of requestOptions, and any other necessary AWS headers and/or request options. Returns requestOptions as a convenience for chaining.

requestOptions is an object holding the same options that the node.js http.request function takes.

The following properties of requestOptions are used in the signing or populated if they don't already exist:

hostname or host (will 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 be calculated from hostname or host if not given)
region (will be calculated from hostname or host or use 'us-east-1' if not given)
headers['Host'] (will use hostname or host or be calculated if not given)
headers['Content-Type'] (will use 'application/x-www-form-urlencoded' 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) can be specified in one of two ways:

As the second argument, like this:

aws4.sign(requestOptions, {
  secretAccessKey: "<your-secret-access-key>",
  accessKeyId: "<your-access-key-id>"
})

From process.env, such as this:

export AWS_SECRET_ACCESS_KEY="<your-secret-access-key>"
export AWS_ACCESS_KEY_ID="<your-access-key-id>"

(will also use AWS_ACCESS_KEY and AWS_SECRET_KEY if available)

Thanks

Thanks to @jed for his dynamo-client lib where I first committed and subsequently extracted this code.

Also thanks to the official node.js AWS SDK for giving me a start on implementing the v4 signature.