Signature V4 signing utility

[zirkelc]

Is this related to an existing feature request or issue?

#2146

Which area does this RFC relate to?

New Feature: Signature V4

Summary

A native AWS SigV4 signing utility for Powertools Lambda that simplifies authenticated requests to AWS services (API Gateway, Lambda URLs, AppSync, etc.). The utility provides a class-based API with two capabilities: signing requests for use with any HTTP library, and a drop-in fetch replacement for automatic signing.

This proposal is based on my aws-signature-v4 libraries which have been used in production environments.

Use case

Lambda functions frequently need to make authenticated HTTP requests to AWS resources:

• Calling API Gateway endpoints with IAM authorization
• Invoking Lambda Function URLs
• Querying AppSync GraphQL APIs

Currently, developers must:

1. Understand complex SigV4 signing mechanics
2. Manually integrate with @smithy/signature-v4
3. Handle credential resolution
4. Adapt signing for different HTTP libraries (Axios, Got, fetch, etc.)

This utility abstracts that complexity into a simple, idiomatic API.

Proposal

API Design

import { SigV4Signer, type SigV4Options } from '@aws-lambda-powertools/sigv4';

// Configuration
interface SigV4Options {
  service: string;                    // Required: 'execute-api' | 'lambda' | 'appsync' | 'es' | ...
  region?: string;                    // Optional: defaults to AWS_REGION env var
  credentials?: AwsCredentialIdentity | AwsCredentialIdentityProvider; // Optional in Lambda
  fetch?: typeof fetch;               // Optional: custom fetch implementation
}

class SigV4Signer {
  constructor(options: SigV4Options);

  /**
   * Sign a request and return a signed Request object.
   * Use when you need the signed request for a different HTTP library.
   */
  sign(input: string | URL | Request, init?: RequestInit): Promise<Request>;

  /**
   * Bound fetch function with automatic SigV4 signing.
   * Can be called directly or destructured for passing to other libraries.
   */
  get fetch(): typeof fetch;
}

Usage Examples

Direct usage of signer.fetch(URL):

import { SigV4Signer } from '@aws-lambda-powertools/sigv4';

const signer = new SigV4Signer({ service: 'execute-api' });

// Call fetch directly on the signer
const response = await signer.fetch('https://api.example.com/resource', {
  method: 'POST',
  body: JSON.stringify({ data: 'value' }),
});

Destructure signer.fetch to pass to libraries requiring fetch :

// Destructure fetch for standalone use
const { fetch } = new SigV4Signer({ service: 'execute-api' });

// Libraries like graphql-request accept a custom fetch
const client = new GraphQLClient(endpoint, {
  fetch: fetch,
});

Get signed Request object for use with other libraries:

const signer = new SigV4Signer({ service: 'lambda' });

// Sign request for use with axios, got, etc.
const signedRequest = await signer.sign('https://fn.lambda-url.us-east-1.on.aws/');

const response = await axios(signedRequest.url, {
  method: signedRequest.method,
  headers: signedRequest.headers,
});

Credential Resolution

In Lambda/Node.js environments, credentials are automatically resolved via the AWS SDK credential provider chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
2. IAM role attached to Lambda function
3. ECS task role / EC2 instance profile

Explicit credentials can be provided when needed:

const signer = new SigV4Signer({
  service: 'execute-api',
  credentials: {
    accessKeyId: 'AKIA...',
    secretAccessKey: '...',
    sessionToken: '...', // optional
  },
});

Out of scope

• SigV4a multi-region signing (can be added later)
• Caching of signed requests

Potential challenges

1. Service auto-detection from URL: For standard AWS URLs (e.g., *.execute-api.*.amazonaws.com, *.lambda-url.*.on.aws), the service could be derived from the hostname automatically. This would make service optional in those cases. However, auto-detection won't work for custom domains or CloudFront distributions where the underlying AWS service is hidden.

Dependencies and Integrations

Dependencies:

• @smithy/signature-v4 - Core SigV4 signing
• @aws-crypto/sha256-js - SHA256 hashing
• @aws-sdk/credential-provider-node - Auto credential resolution

Integrations:

• Works with any fetch-compatible library
• Compatible with GraphQL clients (graphql-request, urql, Apollo)
• Works with REST clients that accept custom fetch

Alternative solutions

1. Direct SDK usage: Use @smithy/signature-v4 directly - more verbose, requires understanding internals
2. aws-sigv4-fetch / aws-sigv4-sign: My packages with implementation based on official AWS packages
3. aws4: Popular package with manual implementation of SigV4 signing

Acknowledgment

• This RFC meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

Future readers

Please react with 👍 and your use case to help us understand customer demand.

[dreamorosi]

Hi @zirkelc, I have blocked some time tomorrow to review this - apologies for the delay.

[dreamorosi]

Hi @zirkelc - apologies for the long delay. Thank you for putting this together, I spent some time this morning in doing a proof of concept for this and made some decisions that deviate from the original proposal but that I hope will make sense.

In terms of package & layout, I think we should go for @aws-lambda-powertools/signer instead of naming the algorithm specifically. As the RFC points out, there are more types of signatures that could be added in the future like SigV4a - the signer name conveys that this is a family of AWS request signers plus a fetch convenience (named with the agent-noun convention: logger/tracer/parser → signer).

Based on the above, I also think we should start with subpath exports from day one, so future signers are pure additions and each one can bring their dependencies:

• /sigv4 → SigV4Signer
• /fetch → createSignedFetcher
• /sigv4a → reserved for the future SigV4a signer

In terms of coupling, I went back & forth a lot between the proposal of coupling the fetch feature with the signer and not, and I think we should build the utility as two units that can be composed. In practice, this means a standalone SigV4Signer class (signing is first-class, covers axios/got/interceptors/WebSocket/testing) and a separate createSignedFetcher factory function (the fetch convenience), which consumes a signer instance and returns a drop-in fetch.

This allows using SigV4Signer as standalone for those non-web request use cases, but also allows us to add SigV4aSigner in the future as non-breaking by making the fetcher depend on a structural Signer interface (sign(input, init?) => Promise<Request>) and not on the concrete class.

In terms of sign method, the signature should look like this sign(input: string | URL | Request, init?: RequestInit): Promise<Request> with web-standard Request in and out; this adapts Request and HttpRequest around @smithy/signature-v4. In terms of options, we'll support service (required), region?, and credentials?. We won't do service auto-detection as it's unreliable for custom domains and CloudFront.

In terms of dependencies, the biggest departure from the RFC proposal is that we'll lean into the Lambda runtime (and our tenets), which means we'll take a single hard dependency on @smithy/signature-v4. For other areas:

• Credentials: default to env-var creds (always present in Lambda); drop @aws-sdk/credential-provider-node. Docs show the explicit escape hatch (fromNodeProviderChain() / fromContainerMetadata(), user-installed) for non-Lambda environments.
• Crypto: use node:crypto injected into smithy; drop @aws-crypto/sha256-js. We officially target Lambda managed Node runtimes; custom runtimes shim it themselves.
• Custom fetch override lives on the fetcher, not the signer.

For this initial implementation we'll handle only, meaning buffers and hashes bufferable bodies (via request.clone()). Non-replayable streaming bodies throw the signing error with a message naming the limitation. Similarly, UNSIGNED-PAYLOAD (incl. applyChecksum) are deferred, and can be implemented based on demand as additive options and/or a signStream method.