Package Exports
- aws-sigv4-fetch
Readme
aws-sigv4-fetch
A small wrapper around the fetch API to automatically sign HTTP requests with AWS Signature Version 4 (SigV4) authentication, built with the official AWS SDK.
[!TIP] If you are using other HTTP libraries like Axios, Ky, Got, or any other HTTP library, consider using the
aws-sigv4-signpackage to sign requests.
Install
npm install --save aws-sigv4-fetchESM and CommonJS
This package ships with ES Module and CommonJS support. That means you can import or require the package in your project depending on your module format.
// ESM
import { createSignedFetcher } from 'aws-sigv4-fetch';
// CommonJS
const { createSignedFetcher } = require('aws-sigv4-fetch');Usage
This package exports a createSignedFetcher function that returns a fetch function to automatically sign HTTP requests with AWS Signature V4 authentication.
The returned function has the same signature as the default fetch function and can be used as a drop-in replacement.
import { createSignedFetcher, SignedFetcherOptions } from 'aws-sigv4-fetch';
const options: SignedFetcherOptions = {
service: 'lambda', // required
region: 'eu-west-1', // optional (defaults to 'us-east-1')
credentials: { // optional (defaults to credentials from environment)
accessKeyId: '...',
secretAccessKey: '...',
}
fetch: fetch, // optional (defaults to native fetch)
};
const signedFetch = createSignedFetcher(options);
const url = 'https://mylambda.lambda-url.eu-west-1.on.aws/';
// signedFetch(input: string)
const response = await signedFetch(url);
// signedFetch(input: URL)
const response = await signedFetch(new URL(url));
// signedFetch(input: Request)
const response = await signedFetch(new Request(url));
// signedFetch(input: string, init?: RequestInit)
const response = await signedFetch(url,
{
method: 'POST',
body: JSON.stringify({ a: 1 }),
headers: { 'Content-Type': 'application/json' }
},
options
);Options
The createSignedFetcher function accepts the following options:
| Parameter | Type | Default | Description |
|---|---|---|---|
service |
string |
Required | The service is required and must match the AWS service you are signing requests for. If it doesn't match, the request will fail with an error like: Credential should be scoped to correct service: 'service'. |
region |
string |
us-east-1 |
The region is optional and defaults to us-east-1 if not provided. Some services like IAM are global and don't require a region. |
credentials |
object |
Read from environment | The credentials is optional. If not provided, the credentials will be retrieved from the environment by the package @aws-sdk/credential-provider-node. |
fetch |
fetch |
Native fetch |
The fetch function is optional. If not provided, the native fetch function will be used. |
Fetch
The fetch function is optional. If not provided, the fetch function from the environment will be used. Native fetch is supported in Node.js >= v18. If you are running in an environment where native fetch is not available, the fetch function must be polyfilled or provided as an argument to createSignedFetcher. This allows to use the same fetch function that is already used in your application. There are several ways to do this:
Native fetch
If native fetch is available, you don't have to pass it as option to createSignedFetcher.
// native fetch is available and doesn't have to be passed as option
const signedFetch = createSignedFetcher({
service: 'lambda',
region: 'eu-west-1'
});Polyfill fetch
Install a fetch package like cross-fetch and import it as polyfill. The fetch function will be available globally after importing the polyfill.
import 'cross-fetch/polyfill';
// fetch was imported globally and doesn't have to be passed as option
const signedFetch = createSignedFetcher({
service: 'iam',
region: 'eu-west-1'
});Pass fetch as an argument
Install a fetch package like cross-fetch and import it as ponyfill. The fetch function will be available locally after importing the ponyfill. Pass the fetch function as an argument to createSignedFetcher:
import fetch from 'cross-fetch';
// fetch was imported locally and must be passed as option
const signedFetch = createSignedFetcher({
service: 'iam',
region: 'eu-west-1',
fetch: fetch
});Examples
API Gateway
const signedFetch = createSignedFetcher({ service: 'execute-api', region: 'eu-west-1' });
const response = await signedFetch('https://myapi.execute-api.eu-west-1.amazonaws.com/my-stage/my-resource');Lambda Function URL
const signedFetch = createSignedFetcher({ service: 'lambda', region: 'eu-west-1' });
const response = await signedFetch(new URL('https://mylambda.lambda-url.eu-west-1.on.aws/'));AppSync
const signedFetch = createSignedFetcher({ service: 'appsync', region: 'eu-west-1' });
const response = await signedFetch('https://mygraphqlapi.appsync-api.eu-west-1.amazonaws.com/graphql', {
method: 'POST',
body: JSON.stringify({ a: 1 }),
headers: {'Content-Type': 'application/json'}
});Automatically sign GraphQL Requests with graphql-request
If you are using graphql-request as GraphQL library, you can use the createSignedFetcher function to create a signed fetch function and pass it to the fetch option of the GraphQLClient:
import { createSignedFetcher } from 'aws-sigv4-fetch';
import { GraphQLClient } from 'graphql-request';
const query = `
mutation CreateItem($input: CreateItemInput!) {
createItem(input: $input) {
id
createdAt
updatedAt
name
}
}
`;
const variables = {
input: {
name,
},
};
const client = new GraphQLClient('https://mygraphqlapi.appsync-api.eu-west-1.amazonaws.com/graphql', {
fetch: createSignedFetcher({ service: 'appsync', region: 'eu-west-1' }),
});
const result = await client.request(query, variables);License
MIT