or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

configuration.md events.md index.md requests.md services.md utilities.md

tile.json

Configuration & Authentication

The AWS SDK provides comprehensive configuration and authentication capabilities supporting multiple credential sources and environments. Configuration can be applied globally or per-service instance.

Core Configuration

Global Configuration

const AWS = require('aws-sdk');

// Global configuration object
AWS.config = {
  // Update configuration
  update(options: ConfigurationOptions): void;
  loadFromPath(path: string): void;
  
  // Credential management
  getCredentials(callback: (err?: Error) => void): void;
  getToken(callback: (err?: Error, token?: Token) => void): void;
  
  // Promise configuration
  setPromisesDependency(dep: PromiseConstructor): void;
  getPromisesDependency(): PromiseConstructor;
  
  // Core properties
  region: string;
  credentials: Credentials;
  accessKeyId: string;
  secretAccessKey: string;
  sessionToken: string;
  
  // Request behavior
  maxRetries: number;
  maxRedirects: number;
  httpOptions: HTTPOptions;
  paramValidation: boolean | ParamValidationOptions;
  computeChecksums: boolean;
  convertResponseTypes: boolean;
  correctClockSkew: boolean;
  
  // Endpoint configuration
  endpoint: string | Endpoint;
  sslEnabled: boolean;
  s3ForcePathStyle: boolean;
  s3BucketEndpoint: boolean;
  s3DisableBodySigning: boolean;
  s3UsEast1RegionalEndpoint: 'legacy' | 'regional';
  s3UseArnRegion: boolean;
  useAccelerateEndpoint: boolean;
  useFipsEndpoint: boolean;
  useDualstackEndpoint: boolean;
  
  // Advanced options
  retryDelayOptions: RetryDelayOptions;
  logger: Logger;
  systemClockOffset: number;
  signatureVersion: string;
  signatureCache: boolean;
  customUserAgent: string;
}

Configuration Methods

Basic Configuration:

AWS.config.update({
  region: 'us-west-2',
  accessKeyId: 'YOUR_ACCESS_KEY',
  secretAccessKey: 'YOUR_SECRET_KEY'
});

Loading from File:

AWS.config.loadFromPath('./config.json');
// config.json: { "region": "us-east-1", "accessKeyId": "...", ... }

Per-Service Configuration:

const s3 = new AWS.S3({
  region: 'us-east-1',
  apiVersion: '2006-03-01',
  httpOptions: { timeout: 120000 }
});

Credential Management

AWS.Credentials Class

class Credentials {
  constructor(accessKeyId: string, secretAccessKey: string, sessionToken?: string);
  
  // Properties
  accessKeyId: string;
  secretAccessKey: string;  
  sessionToken?: string;
  expired: boolean;
  expireTime?: Date;
  
  // Methods
  needsRefresh(): boolean;
  refresh(callback: (err?: Error) => void): void;
  get(callback: (err?: Error) => void): void;
}

Credential Providers

Environment Variables:

class EnvironmentCredentials extends Credentials {
  constructor(envPrefix?: string);
}

// Reads AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
const creds = new AWS.EnvironmentCredentials();

Shared Credentials File:

class SharedIniFileCredentials extends Credentials {
  constructor(options?: {
    profile?: string;
    filename?: string;
    disableAssumeRole?: boolean;
    preferStaticCredentials?: boolean;
    tokenCodeFn?: (serialNumber: string, callback: Function) => void;
    roleSessionName?: string;
  });
}

// Reads ~/.aws/credentials
const creds = new AWS.SharedIniFileCredentials({
  profile: 'my-profile'
});

EC2 Instance Metadata:

class EC2MetadataCredentials extends Credentials {
  constructor(options?: {
    httpOptions?: HTTPOptions;
    maxRetries?: number;
    retryDelayOptions?: RetryDelayOptions;
  });
}

// Automatic credential retrieval from EC2 metadata service
const creds = new AWS.EC2MetadataCredentials();

ECS Container Credentials:

class ECSCredentials extends Credentials {
  constructor(options?: {
    httpOptions?: HTTPOptions;
    maxRetries?: number;
    retryDelayOptions?: RetryDelayOptions;
  });
}

// Automatic credential retrieval from ECS container metadata
const creds = new AWS.ECSCredentials();

Temporary Credentials (STS):

class TemporaryCredentials extends Credentials {
  constructor(options?: {
    RoleArn?: string;
    RoleSessionName?: string;
    ExternalId?: string;
    Policy?: string;
    DurationSeconds?: number;
    MasterCredentials?: Credentials;
  });
}

// Assume an IAM role
const creds = new AWS.TemporaryCredentials({
  RoleArn: 'arn:aws:iam::123456789012:role/MyRole',
  RoleSessionName: 'MySession'
});

Web Identity Federation:

class WebIdentityCredentials extends Credentials {
  constructor(options: {
    RoleArn: string;
    RoleSessionName?: string;
    WebIdentityToken: string;
    ProviderId?: string;
    Policy?: string;
    DurationSeconds?: number;
  });
}

// OIDC/SAML federation
const creds = new AWS.WebIdentityCredentials({
  RoleArn: 'arn:aws:iam::123456789012:role/WebIdentityRole',
  WebIdentityToken: 'eyJ0eXAiOiJKV1Q...'
});

Cognito Identity:

class CognitoIdentityCredentials extends Credentials {
  constructor(options: {
    IdentityPoolId: string;
    IdentityId?: string;
    Logins?: { [provider: string]: string };
    LoginId?: string;
    RoleArn?: string;
    RoleSessionName?: string;
  });
  
  clearCachedId(): void;
}

// Amazon Cognito Identity authentication
const creds = new AWS.CognitoIdentityCredentials({
  IdentityPoolId: 'us-east-1:12345678-1234-1234-1234-123456789012'
});

Credential Provider Chain:

class CredentialProviderChain {
  constructor(providers?: CredentialProvider[]);
  
  resolve(callback: (err?: Error, credentials?: Credentials) => void): void;
  resolvePromise(): Promise<Credentials>;
  
  static defaultProviders: CredentialProvider[];
}

// Default chain: Environment → Shared File → EC2/ECS Metadata → etc.
const chain = new AWS.CredentialProviderChain();
AWS.config.credentialProvider = chain;

Process Credentials:

class ProcessCredentials extends Credentials {
  constructor(options?: {
    profile?: string;
    filename?: string;
    httpOptions?: HTTPOptions;
  });
}

// Execute external process for credentials
const creds = new AWS.ProcessCredentials();

AWS SSO:

class SsoCredentials extends Credentials {
  constructor(options: {
    profile?: string;
    filename?: string;
    httpOptions?: HTTPOptions;
  });
}

// AWS Single Sign-On credentials
const creds = new AWS.SsoCredentials({
  profile: 'my-sso-profile'
});

File System Credentials:

class FileSystemCredentials extends Credentials {
  constructor(filename: string, options?: {
    httpOptions?: HTTPOptions;
  });
}

// Load credentials from file system
const creds = new AWS.FileSystemCredentials('./credentials.json');

SAML Credentials:

class SAMLCredentials extends Credentials {
  constructor(options: {
    RoleArn: string;
    PrincipalArn: string;
    SAMLAssertion: string;
    RoleSessionName?: string;
    Policy?: string;
    DurationSeconds?: number;
  });
}

// SAML assertion credentials
const creds = new AWS.SAMLCredentials({
  RoleArn: 'arn:aws:iam::123456789012:role/SAMLRole',
  PrincipalArn: 'arn:aws:iam::123456789012:saml-provider/ExampleProvider',
  SAMLAssertion: '<base64-encoded-saml-assertion>'
});

Chainable Temporary Credentials:

class ChainableTemporaryCredentials extends Credentials {
  constructor(options?: {
    params?: any;
    masterCredentials?: Credentials;
    tokenCodeFn?: (serialNumber: string, callback: Function) => void;
  });
}

// Chain multiple assume role operations
const creds = new AWS.ChainableTemporaryCredentials({
  params: {
    RoleArn: 'arn:aws:iam::123456789012:role/ChainedRole',
    RoleSessionName: 'ChainedSession'
  }
});

Token File Web Identity Credentials:

class TokenFileWebIdentityCredentials extends Credentials {
  constructor(options?: {
    roleArn?: string;
    roleSessionName?: string;
    webIdentityTokenFile?: string;
    roleAssumerWithWebIdentity?: any;
  });
}

// Token file-based web identity credentials
const creds = new AWS.TokenFileWebIdentityCredentials();

Remote Credentials (Base Class):

class RemoteCredentials extends Credentials {
  constructor(options?: {
    httpOptions?: HTTPOptions;
    maxRetries?: number;
    retryDelayOptions?: RetryDelayOptions;
  });
}

Token Management

AWS.Token Class

class Token {
  constructor(options: {
    token: string;
    expireTime?: Date;
  });
  
  // Properties
  token: string;
  expireTime?: Date;
  
  // Methods
  needsRefresh(): boolean;
  refresh(callback: (err?: Error) => void): void;
  get(callback: (err?: Error) => void): void;
}

Token Providers

Static Token Provider:

class StaticTokenProvider {
  constructor(token: string | Token);
  
  resolve(callback: (err?: Error, token?: Token) => void): void;
  resolvePromise(): Promise<Token>;
}

// Static token provider
const tokenProvider = new AWS.StaticTokenProvider('my-token');

SSO Token Provider:

class SSOTokenProvider {
  constructor(options?: {
    profile?: string;
    filename?: string;
  });
  
  resolve(callback: (err?: Error, token?: Token) => void): void;
  resolvePromise(): Promise<Token>;
}

// SSO token provider
const ssoTokenProvider = new AWS.SSOTokenProvider({
  profile: 'my-sso-profile'
});

Token Provider Chain:

class TokenProviderChain {
  constructor(providers?: TokenProvider[]);
  
  resolve(callback: (err?: Error, token?: Token) => void): void;
  resolvePromise(): Promise<Token>;
  
  static defaultProviders: TokenProvider[];
}

// Token provider chain
const tokenChain = new AWS.TokenProviderChain();
AWS.config.tokenProvider = tokenChain;

Configuration Options

interface ConfigurationOptions {
  // Authentication
  region?: string;
  credentials?: Credentials | CredentialProviderChain | null;
  accessKeyId?: string;
  secretAccessKey?: string;
  sessionToken?: string;
  signatureVersion?: 'v2' | 'v3' | 'v4' | 's3' | 's3v4';
  signatureCache?: boolean;
  
  // Endpoints & SSL
  endpoint?: string | Endpoint;
  sslEnabled?: boolean;
  s3ForcePathStyle?: boolean;
  s3BucketEndpoint?: boolean;
  s3DisableBodySigning?: boolean;
  s3UsEast1RegionalEndpoint?: 'legacy' | 'regional';
  s3UseArnRegion?: boolean;
  useAccelerateEndpoint?: boolean;
  useFipsEndpoint?: boolean;
  useDualstackEndpoint?: boolean;
  
  // Request behavior
  maxRetries?: number;
  maxRedirects?: number;
  retryDelayOptions?: RetryDelayOptions;
  correctClockSkew?: boolean;
  paramValidation?: boolean | ParamValidationOptions;
  computeChecksums?: boolean;
  convertResponseTypes?: boolean;
  
  // HTTP configuration
  httpOptions?: HTTPOptions;
  
  // Monitoring & debugging
  logger?: Logger;
  systemClockOffset?: number;
  customUserAgent?: string;
}

interface HTTPOptions {
  proxy?: string;
  agent?: any;
  connectTimeout?: number;
  timeout?: number;
  xhrAsync?: boolean; // Browser only
  xhrWithCredentials?: boolean; // Browser only
}

interface RetryDelayOptions {
  customBackoff?: (retryCount: number, err?: Error) => number;
  base?: number;
}

interface ParamValidationOptions {
  min?: boolean;
  max?: boolean;
  pattern?: boolean;
  enum?: boolean;
}

interface Logger {
  write?: (chunk: any, encoding?: string) => void;
  log?: (...messages: any[]) => void;
}

Configuration Examples

Production Configuration:

AWS.config.update({
  region: 'us-west-2',
  credentials: new AWS.SharedIniFileCredentials({
    profile: 'production'
  }),
  maxRetries: 3,
  retryDelayOptions: {
    customBackoff: function(retryCount) {
      return Math.pow(2, retryCount) * 100;
    }
  },
  httpOptions: {
    timeout: 120000,
    connectTimeout: 5000
  },
  logger: console
});

Browser Configuration:

AWS.config.update({
  region: 'us-east-1',
  credentials: new AWS.CognitoIdentityCredentials({
    IdentityPoolId: 'us-east-1:12345678-1234-1234-1234-123456789012'
  }),
  httpOptions: {
    xhrAsync: false
  }
});

Cross-Region S3 Configuration:

const s3 = new AWS.S3({
  region: 'eu-west-1',
  s3ForcePathStyle: false,
  useAccelerateEndpoint: true,
  s3UsEast1RegionalEndpoint: 'regional'
});