aws-sigv4-sign
v2.0.2
Published
SignatureV4 sign function implemented with the official AWS SDK
Maintainers
Readme
This library signs HTTP requests with AWS Signature Version 4 and returns a standard Request carrying the signed headers, ready to hand to any HTTP client. Signing is done by @smithy/signature-v4, the same signer the AWS SDK uses, so signatures are computed exactly the way AWS expects.
Why?
Most AWS services (API Gateway, Lambda Function URLs, AppSync, IAM, OpenSearch) can be locked behind IAM authentication. Once they are, an unsigned request is rejected with 403 Forbidden, because every request must carry an Authorization header derived from your credentials, the request itself, and the current time. However, you may not want to:
- Adopt a service-specific SDK client: pulling in
@aws-sdk/client-*just to call your own HTTP endpoint is a lot of dependency for one request - Hand-roll the signature: SigV4 covers the method, URL, query string, headers and body, and getting the canonical form wrong fails with an opaque
403 - Change HTTP client: you already use Axios, Ky, Got or
node:https, and signing should not dictate that choice
This library computes the signature and gives you back plain headers, leaving the transport entirely up to you.
[!TIP] Using the
fetchAPI? Useaws-sigv4-fetch, which wraps this library in a drop-infetchreplacement that signs every request for you.
Installation
npm install aws-sigv4-signRequires Node.js >= 20. Ships both ES Module and CommonJS builds with bundled TypeScript declarations, so no @types/* package is needed.
// ESM
import { signRequest } from 'aws-sigv4-sign';
// CommonJS
const { signRequest } = require('aws-sigv4-sign');Usage
signRequest mirrors the fetch argument shape and appends a required options object. The input can be a string, a URL or a Request, with an optional RequestInit in between.
import { signRequest } from 'aws-sigv4-sign';
const signedRequest = await signRequest('https://mylambda.lambda-url.eu-west-1.on.aws/', {
service: 'lambda',
region: 'eu-west-1',
});
const response = await fetch(signedRequest);Reading the signed headers
The returned Request carries the signing headers on its headers property. Convert them to a plain object to pass them to a client that does not accept a Request.
const signedRequest = await signRequest(url, { service: 'lambda', region: 'eu-west-1' });
const headers = Object.fromEntries(signedRequest.headers.entries());
headers.authorization; // AWS4-HMAC-SHA256 Credential=.../20250101/eu-west-1/lambda/aws4_request, SignedHeaders=..., Signature=...
headers.host; // mylambda.lambda-url.eu-west-1.on.aws
headers['x-amz-date']; // 20250101T000000Z
headers['x-amz-content-sha256']; // hex-encoded SHA-256 of the body
headers['x-amz-security-token']; // only when the credentials include a session tokenSending with any HTTP client
Every client works the same way: sign, read the headers, send. Pass signedRequest.url rather than the original input, so the URL that was signed is the URL that is sent.
const signedRequest = await signRequest(url, { service: 'lambda', region: 'eu-west-1' });
const headers = Object.fromEntries(signedRequest.headers.entries());
// Axios
import axios from 'axios';
await axios(signedRequest.url, { headers });
// Ky
import ky from 'ky';
await ky.get(signedRequest.url, { headers });
// Got
import got from 'got';
await got(signedRequest.url, { headers });
// node:https
import { request } from 'node:https';
request(signedRequest.url, { headers }, (res) => {
/* ... */
}).end();Sending a body
The body is part of the signature, so it has to be passed to signRequest in the RequestInit and sent unchanged. With a body, the options move to the third argument.
const signedRequest = await signRequest(
'https://mylambda.lambda-url.eu-west-1.on.aws/',
{
method: 'POST',
body: JSON.stringify({ a: 1 }),
headers: { 'Content-Type': 'application/json' },
},
{ service: 'lambda', region: 'eu-west-1' },
);Service and region
service is required and must match the AWS service you are calling. A mismatch fails with Credential should be scoped to correct service: 'service'. region is optional and defaults to us-east-1.
Common values:
| Target | service |
| -------------------------------- | ------------- |
| API Gateway (REST and HTTP APIs) | execute-api |
| Lambda Function URL | lambda |
| AppSync | appsync |
| IAM | iam |
| OpenSearch / Elasticsearch | es |
| S3 | s3 |
Credentials
Credentials are optional in Node.js and required in the browser. When omitted in Node.js they are resolved with @aws-sdk/credential-provider-node, which checks, in order: environment variables, SSO token cache, web identity tokens, shared credentials and config files, and finally the EC2/ECS instance metadata service.
// Credentials are picked up from the environment
const signedRequest = await signRequest(url, { service: 'lambda', region: 'eu-west-1' });[!IMPORTANT] The default provider is constructed once and reused for the lifetime of the process. The AWS SDK caches the credentials it resolves and refreshes them before they expire, so only the first signed request pays for the lookup. Because the provider is pinned, changes to
AWS_PROFILEor the other credential environment variables after the first signed request are not picked up; passcredentialsexplicitly if you need to switch identities at runtime.
You can always pass credentials explicitly, which skips the lookup. The option accepts either a static AwsCredentialIdentity or an AwsCredentialIdentityProvider function:
const signedRequest = await signRequest(url, {
service: 'lambda',
region: 'eu-west-1',
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
// sessionToken: only for temporary credentials, adds the x-amz-security-token header
sessionToken: process.env.AWS_SESSION_TOKEN,
},
});In the browser there is no environment to resolve from, so omitting credentials throws. Use temporary, scoped credentials from Amazon Cognito or a web federated identity provider via @aws-sdk/credential-providers:
import { fromCognitoIdentityPool } from '@aws-sdk/credential-providers';
const signedRequest = await signRequest(url, {
service: 'execute-api',
region: 'eu-west-1',
credentials: fromCognitoIdentityPool({
identityPoolId: 'eu-west-1:...',
clientConfig: { region: 'eu-west-1' },
}),
});[!WARNING] Never hardcode AWS credentials in a browser application. Doing so exposes your access key ID and secret access key to anyone who loads the page.
Advanced
Sign last
[!IMPORTANT] The signature covers the method, URL, query string, headers and body. Anything you change after signing invalidates it and the request fails with
403 Forbidden. In particular, do not add headers or query parameters to the request after callingsignRequest, and sendsignedRequest.urlrather than the URL you started with.
Browser bundles
The Node-only credential provider is loaded through a dynamic import, and this package maps it to false in its browser field, so bundlers leave it out of browser builds entirely. This is why credentials must be explicit in the browser.
API
signRequest(input, options)
function signRequest(input: string | Request | URL, options: SignRequestOptions): Promise<Request>;
function signRequest(input: string | Request | URL, init: RequestInit, options: SignRequestOptions): Promise<Request>;Returns a new Request with the SigV4 headers applied. The host header is always set from the URL, because SigV4 requires it. Two overloads: pass options second when there is no RequestInit, third when there is.
await signRequest(url, { service: 'lambda' });
await signRequest(url, { method: 'POST', body: '{}' }, { service: 'lambda' });parseRequest(input, init?)
function parseRequest(
input: string | Request | URL,
init?: RequestInit,
): Promise<{
url: URL;
method: string;
headers: Record<string, string>;
body?: ArrayBuffer;
}>;Normalizes the fetch-style arguments into their parts, with header names lowercased and the body read into an ArrayBuffer. Values in init override those on a Request input. signRequest uses this internally; it is exported for callers that need the normalized request without signing it.
const { url, method, headers } = await parseRequest(url, { method: 'POST' });getDefaultCredentialProvider()
function getDefaultCredentialProvider(): Promise<AwsCredentialIdentityProvider>;Returns the default provider from @aws-sdk/credential-provider-node, constructed once and reused for the lifetime of the process. Rejects in browser environments, where credentials must be explicit. This is what signRequest calls when credentials is omitted; you rarely need it directly.
const provider = await getDefaultCredentialProvider();
const credentials = await provider();Types
SignRequestOptions
The options object accepted by signRequest.
import type { SignRequestOptions } from 'aws-sigv4-sign';
type SignRequestOptions = {
service: string; // required, e.g. 'lambda' or 'execute-api'
region?: string; // default: 'us-east-1'
credentials?: AwsCredentialIdentity | AwsCredentialIdentityProvider; // default: resolved from the environment in Node.js
};License
MIT
