A small utility to sign vanilla Node.js http(s) request options using Amazon's AWS Signature Version 4.
If you want to sign and send AWS requests in a modern browser, or an environment like Cloudflare Workers, then check out aws4fetch – otherwise you can also bundle this library for use in older browsers.
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
var https =require('https')var aws4 =require('aws4')// to illustrate usage, we'll create a utility function to request and pipe to stdoutfunctionrequest(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 regionvar 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.requestaws4.sign(opts, { accessKeyId:'', secretAccessKey:'' })// or it can get credentials from process.env.AWS_ACCESS_KEY_ID, etcaws4.sign(opts)// for most AWS services, aws4 can figure out the service and region if you pass a hostopts = { 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 AWSrequest(opts)/*<?xml version="1.0"?><ListQueuesResponse xmlns="https://queue.amazonaws.com/doc/2012-11-05/">...*/// 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' }))/*<ListGroupsResponse xmlns="https://iam.amazonaws.com/doc/2010-05-08/">...*/// you can specify any custom option or header as per usualrequest(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":[]}...*/// The raw RequestSigner can be used to generate CodeCommit Git passwordsvar signer =newaws4.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 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)
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) can be specified in one of two ways: