sigv4fetch

A compact AWS Signature Version 4 (SigV4) client for fetch. Sign requests and call AWS REST APIs without the full AWS SDK.

Inspired by aws4fetch, with TypeScript types, injectable Web APIs, and Node.js 22+ as the baseline runtime.

Requirements

• Node.js 22+ — native fetch, Request, Headers, TextEncoder, and Web Crypto (crypto.subtle) are used directly
• A small XML parser dependency is used for S3-compatible listing helpers

Install

pnpm add sigv4fetch

npm install sigv4fetch

Quick start

import { AwsClient } from 'sigv4fetch'

const aws = new AwsClient({
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  sessionToken: process.env.AWS_SESSION_TOKEN, // optional, for temporary credentials
})

const response = await aws.fetch('https://lambda.us-east-1.amazonaws.com/2015-03-31/functions/my-fn/invocations', {
  method: 'POST',
  body: JSON.stringify({ key: 'value' }),
  headers: { 'Content-Type': 'application/json' },
})

console.log(await response.json())

Service and region are inferred from the URL when omitted. You can also set defaults on the client:

const aws = new AwsClient({
  accessKeyId: '...',
  secretAccessKey: '...',
  service: 's3',
  region: 'us-west-2',
})

API

AwsClient

High-level client for signing and sending requests.

import { AwsClient } from 'sigv4fetch'

const aws = new AwsClient({
  accessKeyId: string       // required
  secretAccessKey: string   // required
  sessionToken?: string    // STS / IAM role credentials
  service?: string          // default service (otherwise parsed from URL)
  region?: string           // default region (otherwise parsed from URL)
  cache?: Map<string, ArrayBuffer>  // signing key cache
  retries?: number          // default 10 (0 = no retries)
  initRetryMs?: number      // default 50, doubles each retry with jitter
  api?: AwsApiInput         // optional injected Web APIs (see below)
})

aws.sign(input, init?)

Returns a signed Request. Accepts a URL string or Request.

const signed = await aws.sign('https://dynamodb.us-east-1.amazonaws.com/', {
  method: 'POST',
  body: JSON.stringify({ TableName: 'MyTable' }),
  headers: {
    'Content-Type': 'application/x-amz-json-1.0',
    'X-Amz-Target': 'DynamoDB_20120810.ListTables',
  },
})

// use with any fetch implementation
await fetch(signed)

aws.fetch(input, init?)

Signs the request and calls fetch. Retries on 5xx and 429 with exponential backoff and jitter.

AwsV4Signer

Lower-level signer when you only need the signed method, URL, headers, and body.

import { AwsV4Signer } from 'sigv4fetch'

const signer = new AwsV4Signer({
  url: 'https://example-bucket.s3.amazonaws.com/object.txt',
  accessKeyId: '...',
  secretAccessKey: '...',
  method: 'GET',
})

const { method, url, headers, body } = await signer.sign()

Per-request options

Pass signing overrides via init.aws:

await aws.fetch(url, {
  method: 'PUT',
  body: fileContents,
  headers: { 'Content-Type': 'text/plain' },
  aws: {
    service: 's3',
    region: 'eu-west-1',
    datetime: '20150830T123600Z', // fixed timestamp (testing / replay)
  },
})

| Option | Description | | --- | --- | | accessKeyId | Override client access key | | secretAccessKey | Override client secret key | | sessionToken | Temporary credential token | | service | AWS service name | | region | AWS region | | datetime | SigV4 timestamp (YYYYMMDDTHHmmssZ) | | signQuery | Sign query string instead of Authorization header (presigned URLs) | | appendSessionToken | Append X-Amz-Security-Token after signing (default for IoT gateway) | | allHeaders | Sign all headers instead of the default subset | | singleEncode | Only encode %2F once (mainly for testing) | | cache | Per-request signing key cache |

Presigned URLs

const signer = new AwsV4Signer({
  url: 'https://my-bucket.s3.amazonaws.com/report.pdf',
  accessKeyId: '...',
  secretAccessKey: '...',
  signQuery: true,
})

const { url } = await signer.sign()
console.log(url.toString()) // shareable presigned URL

S3 presigned URLs default to X-Amz-Expires=86400 (24 hours) when not set.

S3-Compatible Providers

Use customS3Client for AWS S3 and most S3-compatible storage providers, including Cloudflare R2, Backblaze B2, DigitalOcean Spaces, Linode Object Storage, MinIO, Wasabi, Tigris, and other custom endpoints.

For virtual-host style endpoints:

import { customS3Client, listObjectsV2 } from 'sigv4fetch'

const s3 = customS3Client({
  host: 's3.us-east-1.amazonaws.com',
  accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
  region: 'us-east-1',
})

const objects = await listObjectsV2(s3, {
  bucket: 'my-bucket',
  sortBy: 'key',
})

For path-style endpoints, such as many MinIO deployments:

const minio = customS3Client({
  host: 'localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
  region: 'us-east-1',
  secure: false,
  forcePathStyle: true,
})

Cloudflare R2 also has a convenience helper:

import { cloudflareR2Client, listObjectsV2 } from 'sigv4fetch'

const r2 = cloudflareR2Client({
  accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
  accessKeyId: process.env.CLOUDFLARE_ACCESS_KEY_ID!,
  secretAccessKey: process.env.CLOUDFLARE_SECRET_ACCESS_KEY!,
})

const objects = await listObjectsV2(r2, {
  bucket: 'my-bucket',
  prefix: 'uploads/',
  sortBy: 'lastModified',
  sortDirection: 'desc',
})

console.log(objects.contents)

listObjectsV2 parses the XML returned by S3-compatible providers and can sort the returned contents array client-side. sortBy supports key, lastModified, size, eTag, and storageClass.

Common object helpers are included:

import {
  deleteObject,
  deleteObjects,
  getObjectBlob,
  headObject,
  putObject,
} from 'sigv4fetch'

await putObject(s3, {
  bucket: 'my-bucket',
  key: 'uploads/hello.txt',
  body: 'hello',
  contentType: 'text/plain',
  metadata: { source: 'example' },
})

const head = await headObject(s3, {
  bucket: 'my-bucket',
  key: 'uploads/hello.txt',
})

const object = await getObjectBlob(s3, {
  bucket: 'my-bucket',
  key: 'uploads/hello.txt',
})

await deleteObject(s3, {
  bucket: 'my-bucket',
  key: 'uploads/hello.txt',
})

await deleteObjects(s3, {
  bucket: 'my-bucket',
  objects: [{ key: 'uploads/a.txt' }, { key: 'uploads/b.txt' }],
})

Provider compatibility depends on how closely the service implements the S3 API. Some providers require path-style URLs, a specific region value, or slightly different endpoint hosts.

Injectable Web APIs

Optionally inject fetch, Request, Headers, crypto, and TextEncoder. Useful for tests or custom fetch implementations:

import { AwsClient, getDefaultApi } from 'sigv4fetch'

const api = getDefaultApi()

const aws = new AwsClient({
  accessKeyId: '...',
  secretAccessKey: '...',
  api: {
    ...api,
    fetch: myCustomFetch,
  },
})

On Node 22+, globals are available out of the box — injection is optional.

Note: When injecting Request, pass Request instances created from the same constructor (input instanceof aws.api.Request).

Supported environments

| Environment | Support | | --- | --- | | Node.js 22+ | ✅ Native globals | | Cloudflare Workers | ✅ (Web Crypto + fetch) | | Browsers | ✅ | | Deno / Bun | ✅ (with fetch + Web Crypto) |

Body types

Request bodies must be a string, ArrayBuffer, or ArrayBufferView unless you set the X-Amz-Content-Sha256 header yourself. Blob, FormData, and readable streams are not hashed automatically.

S3 requests use UNSIGNED-PAYLOAD by default for the payload hash unless you provide X-Amz-Content-Sha256.

Development

pnpm install
pnpm run typecheck
pnpm run build
pnpm run dev      # watch mode

Publish

pnpm run prepublishOnly   # typecheck + build
npm publish

License

MIT © nunesunil