# @turbot/guardrails-aws-sdk-v3

> Turbot guardrails-aws-sdk-v3 wrapper.

Latest version **5.1.1** (published 2026-10-07) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @turbot/guardrails-aws-sdk-v3
pnpm add @turbot/guardrails-aws-sdk-v3
yarn add @turbot/guardrails-aws-sdk-v3
bun add @turbot/guardrails-aws-sdk-v3
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 5.1.1 |
| Published | 2026-10-07 |
| First published | 2024-12-11 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 7 |
| Unpacked size | 31.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Turbot HQ, Inc |
| Maintainers | e-gineer, vhadianto, abhina07 |

## Links

- npm: https://www.npmjs.com/package/@turbot/guardrails-aws-sdk-v3
- npm.io page: https://npm.io/package/@turbot/guardrails-aws-sdk-v3

## Dependencies (7)

- [aws4](https://npm.io/package/aws4.md) 1.13.2
- [micromatch](https://npm.io/package/micromatch.md) 4.0.8
- [@turbot/log](https://npm.io/package/@turbot/log.md) 5.5.0
- [@turbot/errors](https://npm.io/package/@turbot/errors.md) 5.3.0
- [https-proxy-agent](https://npm.io/package/https-proxy-agent.md) 7.0.6
- [@smithy/util-retry](https://npm.io/package/@smithy/util-retry.md) 4.2.12
- [@smithy/node-http-handler](https://npm.io/package/@smithy/node-http-handler.md) 4.5.0

## Recent versions

- 5.1.1 (latest) — 2026-10-07
- 5.1.1-rc.0 (rc) — 2026-10-06
- 5.1.0 — 2026-02-26
- 5.0.1 — 2024-12-11

## README

# @turbot/guardrails-aws-sdk-v3

![Tests](https://github.com/turbot/guardrails-aws-sdk-v3/actions/workflows/test.yml/badge.svg?branch=develop)

A lightweight, Turbot-optimized wrapper around AWS SDK v3, designed to simplify and standardize AWS interactions within Guardrails. This wrapper provides intelligent defaults, automatic configuration detection, and enterprise-ready features.

## Features

- **Zero Configuration**: Sensible defaults work out of the box
- **Advanced Proxy Support**: Per-service proxy control with wildcard patterns
- **Custom Retry Strategies**: Turbot-optimized retry logic with exponential backoff
- **Smart Region Fallback**: 3-level region resolution (params → env var → config)
- **IAM Signed Requests**: Built-in support for AWS signature v4 signed HTTP requests
- **Discovery Parameters**: Specialized retry strategy for AWS discovery operations

## Installation

```bash
npm install @turbot/guardrails-aws-sdk-v3
```

## Quick Start

### Basic Usage

```javascript
const taws = require("@turbot/guardrails-aws-sdk-v3");
const { S3Client, ListBucketsCommand } = require("@aws-sdk/client-s3");

// Simple connection with explicit region
const s3 = taws.connect(S3Client, { region: "us-east-1" });

async function listBuckets() {
  const data = await s3.send(new ListBucketsCommand({}));
  console.log("Buckets:", data.Buckets);
}

listBuckets();
```

### Region Configuration

The wrapper automatically resolves regions using a 3-level fallback:

```javascript
// 1. Explicit params (highest priority)
const s3 = taws.connect(S3Client, { region: "us-east-1" });

// 2. Environment variable (if params not provided)
process.env.AWS_DEFAULT_REGION = "us-west-2";
const s3 = taws.connect(S3Client, {});

// 3. TURBOT_CONFIG_ENV (lowest priority)
process.env.TURBOT_CONFIG_ENV = JSON.stringify({
  env: { region: "ap-southeast-2" },
});
const s3 = taws.connect(S3Client, {});
```

### Proxy Configuration

#### Simple Proxy (All Services)

```javascript
// Set environment variable
process.env.HTTPS_PROXY = "http://proxy.company.com:8080";

// All AWS service calls automatically use proxy
const s3 = taws.connect(S3Client, { region: "us-east-1" });
```

#### Advanced Proxy (Per-Service Control)

```javascript
// Configure via TURBOT_CONFIG_ENV
process.env.TURBOT_CONFIG_ENV = JSON.stringify({
  aws: {
    proxy: {
      https_proxy: "http://proxy.company.com:8080",
      enabled: ["s3*", "dynamodb*", "sqs*"], // Services to proxy
      disabled: ["sts*", "iam*"], // Services to bypass
    },
  },
});

const s3 = taws.connect(S3Client, { region: "us-east-1" }); // Uses proxy
const sts = taws.connect(STSClient, { region: "us-east-1" }); // Bypasses proxy
```

**Wildcard patterns**:

- `*` matches all services
- `s3*` matches S3Client, S3ControlClient, etc.
- `iam*` matches IAMClient, IAMRolesAnywhereClient, etc.

### Custom Retry Strategy

The wrapper includes Turbot-optimized retry logic:

```javascript
const s3 = taws.connect(S3Client, {
  region: "us-east-1",
  maxAttempts: 5, // Default is 10
});

// For discovery operations (uses different backoff)
const ec2 = taws.connect(EC2Client, taws.discoveryParams({ region: "us-east-1" }));
```

### IAM Signed Requests

Make SigV4-signed HTTPS requests to AWS endpoints that have no SDK client, such as an AppSync GraphQL API:

```javascript
const taws = require("@turbot/guardrails-aws-sdk-v3");

const options = {
  uri: "https://example.appsync-api.us-east-1.amazonaws.com/graphql",
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: { query: "{ __typename }" },
};

const credentials = {
  AccessKeyId: "AKIAIOSFODNN7EXAMPLE",
  SecretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
};

taws.awsIamSignedRequest(options, "appsync", credentials, (err, result) => {
  if (err) console.error(err);
  else console.log(result);
});
```

The request goes through the same proxy that `connect()` would use, with the service name (`appsync` here) matched against the `enabled` / `disabled` patterns. To send it direct while other services use the proxy, add `appsync` to `disabled`.

### Development Mode

For local development, automatically uses AWS CLI profile credentials:

```javascript
process.env.NODE_ENV = "local-development";
process.env.TURBOT_DEV_PROFILE = "developer";
process.env.TURBOT_DEV_MASTER_REGION = "ap-southeast-2";

const s3 = taws.connect(S3Client, {}); // Uses "developer" profile
```

## API Reference

### `connect(ServiceClient, params)`

Creates and configures an AWS SDK v3 client.

**Parameters**:

- `ServiceClient` (class) - AWS SDK v3 client class (e.g., S3Client, DynamoDBClient)
- `params` (object) - Configuration options:
  - `region` (string) - AWS region
  - `maxAttempts` (number) - Maximum retry attempts (default: 10)
  - `retryStrategy` (object) - Custom retry strategy
  - `customUserAgent` (string) - Custom user agent (default: "Turbot/5 (APN_137229)")
  - `signatureVersion` (string) - AWS signature version (default: "v4")
  - Any other AWS SDK v3 client options

**Returns**: Configured AWS SDK v3 client instance

### `discoveryParams(params)`

Returns parameters optimized for AWS discovery operations (uses CustomDiscoveryRetryStrategy).

**Parameters**:

- `params` (object) - Base configuration options

**Returns**: Configuration object with discovery retry strategy

### `awsIamSignedRequest(options, service, credentials, callback)`

Makes a SigV4-signed HTTPS request to an AWS service, through the proxy `connect()` would use for that service.

**Parameters**:

- `options` (object):
  - `uri` (string) - Target AWS service URL
  - `method` (string) - HTTP method
  - `headers` (object) - HTTP headers
  - `body` (object, optional) - Request body, sent as JSON
  - `timeout` (number, optional) - Milliseconds before the request fails with a timeout error (default: 300000)
- `service` (string) - AWS signing name (e.g. `appsync`), also matched against the proxy `enabled` / `disabled` patterns
- `credentials` (object):
  - `AccessKeyId` (string) - AWS access key ID
  - `SecretAccessKey` (string) - AWS secret access key
  - `SessionToken` (string, optional) - AWS session token
- `callback` (function) - Called with `(err, body)`, where `body` is the parsed JSON response

### `CustomRetryStrategy`

Turbot-optimized retry strategy with custom backoff logic.

### `CustomDiscoveryRetryStrategy`

Specialized retry strategy for AWS discovery operations.

## Environment Variables

| Variable                      | Purpose                     | Example             |
| ----------------------------- | --------------------------- | ------------------- |
| `AWS_DEFAULT_REGION`          | Default AWS region          | `us-east-1`         |
| `HTTPS_PROXY` / `https_proxy` | Proxy server URL            | `http://proxy:8080` |
| `TURBOT_CONFIG_ENV`           | JSON config (region, proxy) | See examples above  |
| `NODE_ENV`                    | Enable dev mode             | `local-development` |
| `TURBOT_DEV_PROFILE`          | Dev mode AWS profile        | `silverwater`       |
| `TURBOT_DEV_MASTER_REGION`    | Dev mode default region     | `ap-southeast-2`    |

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## License

See LICENSE file for details.

---
_Source: https://npm.io/package/@turbot/guardrails-aws-sdk-v3 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._