aws4

aws4 is a small, dependency-free utility that signs Node.js http/https request options using Amazon’s AWS Signature Version 4 algorithm. Instead of shipping a full per-service SDK with generated clients for every API, it works directly against the plain options object you’d pass to http.request, computing the canonical request, string-to-sign, and derived signing key, then attaching the Authorization header (or signed query-string parameters) needed to authenticate against virtually any AWS service.

Because it operates on raw request options rather than wrapping specific AWS APIs, aws4 is often used as a low-level signing primitive underneath other libraries and scripts that need to talk to services like S3, DynamoDB, SQS, IAM, or OpenSearch/Elasticsearch without depending on the (much larger) official AWS SDK for JavaScript. It infers sensible defaults — service, region, host, HTTP method, and content headers — directly from the options passed in, and supports edge cases like AWS CodeCommit Git-over-HTTPS credential generation.

What You Get

• A single aws4.sign(requestOptions, credentials) call that mutates and returns a plain Node.js http.request-compatible options object with SigV4 auth applied
• Automatic inference of AWS service and region from a request’s host/hostname when they aren’t specified explicitly
• Support for both header-based signing (Authorization header) and query-string signing (signQuery: true) for pre-signed URLs
• Credential resolution from process.env (AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_SESSION_TOKEN) when explicit credentials aren’t passed
• A tiny built-in LRU cache (lru.js) that memoizes the expensive derived signing key per credential/date/region/service combination
• A standalone RequestSigner constructor for lower-level use cases, such as generating CodeCommit Git-over-HTTPS passwords

Common Use Cases

• Signing raw HTTP requests to AWS services (S3, DynamoDB, SQS, IAM, OpenSearch) from scripts or services that don’t want the weight of the full AWS SDK
• Building lightweight, custom AWS API clients or CLI tools on top of Node’s native http/https modules
• Generating pre-signed S3 URLs or query-string-authenticated requests via signQuery: true
• Producing CodeCommit Git-over-HTTPS passwords for automated Git operations against AWS CodeCommit repositories
• Serving as the signing primitive inside higher-level internal tooling that talks to multiple AWS services

Under The Hood

Architecture aws4 is a deliberately small, single-purpose module: all signing logic lives in aws4.js around one constructor, RequestSigner, whose prototype methods (prepareRequest, canonicalString, stringToSign, signature, authHeader, sign) map directly onto the sequential steps of the AWS Signature Version 4 specification. A companion module, lru.js, implements a minimal doubly-linked-list LRU cache used solely to memoize derived signing keys keyed by secret/date/region/service, avoiding redundant HMAC chains for repeated requests against the same service and day. There is no plugin system, no per-service client generation, and no external state beyond that cache — the entire library is one file plus one small internal cache module, which keeps the execution path (construct signer, prepare request, compute signature, mutate and return options) easy to trace end to end.

Tech Stack The library has zero runtime dependencies, relying only on Node’s built-in url, querystring, and crypto modules for HMAC-SHA256/SHA256 operations and URL parsing. Its devDependencies are limited to mocha and should for testing. A browser/ subdirectory provides a bundled build with its own package.json, letting the same signing logic run client-side for use cases like browser-based S3 uploads. Packaging is minimal — package.json declares only aws4.js and lru.js as published files, keeping the installed footprint tiny.

Code Quality The project has an extensive test suite for its size: test/fast.js runs synchronous unit tests (nearly 1,000 lines) covering host-parsing edge cases across dozens of AWS services, canonical-request construction, and known-good signature fixtures, while test/slow.js runs live integration tests against real AWS services. A test/aws-sig-v4-test-suite/ directory vendors AWS’s own official SigV4 test vectors, giving the implementation an authoritative correctness check beyond hand-written assertions. Tests run via Mocha/should and are wired into GitHub Actions CI (.github/workflows/build.yml). There are no TypeScript types shipped, but naming and code structure are consistent throughout, and error handling is minimal but appropriate for a narrow, synchronous signing utility.

API Design aws4 favors a minimal, single-function surface: call aws4.sign(options, credentials) and the returned/mutated options object is ready to hand to http.request. Sensible defaults (method inferred from body presence, region defaulting to us-east-1, host derived from service/region) mean most calls require no boilerplate beyond specifying a service. The lower-level RequestSigner class is exposed for callers who need finer control, such as generating a CodeCommit Git password without making an actual HTTP request. Documentation in the README enumerates every recognized option clearly, and the API has remained stable for years, making it a de facto reference implementation that other libraries (including aws4fetch) explicitly model themselves on.