Authentication & Identity

/**
 * AWS credential identity containing access keys and optional session token
 * Used throughout the AWS SDK for service authentication
 */
interface AwsCredentialIdentity {
  /** AWS access key ID */
  readonly accessKeyId: string;
  /** AWS secret access key */
  readonly secretAccessKey: string;
  /** Optional session token for temporary credentials */
  readonly sessionToken?: string;
  /** Optional expiration time for temporary credentials */
  readonly expiration?: Date;
  /** Optional credential scope for scoped-down permissions */
  readonly credentialScope?: string;
  /** Optional AWS account ID associated with the credentials */
  readonly accountId?: string;
}

/**
 * Provider function that resolves to AWS credentials
 * Can be synchronous, asynchronous, or return a direct value
 */
type AwsCredentialIdentityProvider = Provider<AwsCredentialIdentity>;

/**
 * AWS credential identity with source attribution for debugging
 * Extends the base credential identity with metadata about origin
 */
type AttributedAwsCredentialIdentity = AwsCredentialIdentity & {
  /** Source where the credentials were obtained from */
  $source?: AwsSdkCredentialsFeatures;
};

/**
 * Runtime configuration provider for credential resolution
 * Used in client configuration for dynamic credential resolution
 */
type RuntimeConfigAwsCredentialIdentityProvider = (
  awsIdentityProperties?: AwsIdentityProperties
) => Promise<AwsCredentialIdentity>;

import { AwsCredentialIdentity, AwsCredentialIdentityProvider } from "@aws-sdk/types";

// Static credentials
const staticCredentials: AwsCredentialIdentity = {
  accessKeyId: "AKIAIOSFODNN7EXAMPLE",
  secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
};

// Temporary credentials with session token
const temporaryCredentials: AwsCredentialIdentity = {
  accessKeyId: "AKIAIOSFODNN7EXAMPLE",
  secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
  sessionToken: "AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4Olgk",
  expiration: new Date(Date.now() + 3600000) // 1 hour from now
};

// Async credential provider
const credentialProvider: AwsCredentialIdentityProvider = async () => {
  // Fetch credentials from some source
  return {
    accessKeyId: "fetched-access-key",
    secretAccessKey: "fetched-secret-key"
  };
};

/**
 * Base identity interface for all authentication mechanisms
 * Extended by specific identity types throughout the SDK
 */
interface Identity {
  /** Optional expiration time for the identity */
  readonly expiration?: Date;
}

/**
 * Generic identity provider function
 * Can provide any type of identity synchronously or asynchronously
 */
interface IdentityProvider<T extends Identity> {
  (identityProperties?: any): Promise<T>;
}

/**
 * Anonymous identity for unauthenticated requests
 * Used for services that support anonymous access
 */
interface AnonymousIdentity extends Identity {
  /** Always false for anonymous identities */
  readonly anonymous: false;
}

/**
 * Token-based identity for bearer token authentication
 * Used with services that accept JWT or similar tokens
 */
interface TokenIdentity extends Identity {
  /** The authentication token */
  readonly token: string;
}

/**
 * Provider function that resolves to token identity
 * Used for dynamic token resolution and refresh
 */
type TokenIdentityProvider = Provider<TokenIdentity>;

/**
 * Token identity with source attribution for debugging
 * Extends token identity with metadata about token origin
 */
type AttributedTokenIdentity = TokenIdentity & {
  /** Source where the token was obtained from */
  $source?: string;
};

/**
 * Legacy token interface for backward compatibility
 * @deprecated Use TokenIdentity instead
 */
interface Token extends TokenIdentity {
  /** The authentication token */
  readonly token: string;
}

/**
 * Legacy token provider for backward compatibility
 * @deprecated Use TokenIdentityProvider instead
 */
type TokenProvider = Provider<Token>;

/**
 * Login identity for username/password authentication
 * Used with services that support basic authentication schemes
 */
interface LoginIdentity extends Identity {
  /** Username for authentication */
  readonly username: string;
  /** Password for authentication */
  readonly password: string;
}

/**
 * Provider function that resolves to login identity
 * Used for dynamic credential resolution in basic auth scenarios
 */
type LoginIdentityProvider = Provider<LoginIdentity>;

/**
 * Legacy credentials interface
 * @deprecated Use AwsCredentialIdentity instead
 */
interface Credentials extends AwsCredentialIdentity {
  /** AWS access key ID */
  readonly accessKeyId: string;
  /** AWS secret access key */
  readonly secretAccessKey: string;
  /** Optional session token */
  readonly sessionToken?: string;
}

/**
 * Legacy credential provider type
 * @deprecated Use AwsCredentialIdentityProvider instead
 */
type CredentialProvider = Provider<Credentials>;

/**
 * AWS-specific identity properties for enhanced credential management
 * Used in advanced authentication scenarios with custom credential resolution
 */
interface AwsIdentityProperties {
  /** Caller client configuration for nested credential resolution */
  callerClientConfig?: {
    /** Credentials or credential provider */
    credentials?: AwsCredentialIdentity | AwsCredentialIdentityProvider;
    /** Default credential provider factory function */
    credentialDefaultProvider?: (input?: any) => AwsCredentialIdentityProvider;
    /** Logger for credential resolution debugging */
    logger?: Logger;
    /** AWS profile name for configuration */
    profile?: string;
    /** Region provider function */
    region(): Promise<string>;
    /** Request handler for credential resolution HTTP requests */
    requestHandler?: RequestHandler<any, any>;
  };
}

/**
 * Runtime configuration provider for identity management
 * Used in client configuration for dynamic identity resolution
 */
type RuntimeConfigIdentityProvider = (input?: any) => IdentityProvider<Identity>;

/**
 * Options for credential provider configuration
 * Used when initializing credential providers with additional context
 */
interface CredentialProviderOptions {
  /** Logger for credential resolution debugging */
  logger?: Logger;
  /** Parent client configuration for context */
  parentClientConfig?: {
    /** Region configuration */
    region?: string | Provider<string>;
    /** AWS profile name */
    profile?: string;
    /** Additional configuration properties */
    [key: string]: unknown;
  };
}

import { 
  AwsIdentityProperties, 
  CredentialProviderOptions,
  Logger 
} from "@aws-sdk/types";

// Configure identity properties for advanced scenarios
const identityProperties: AwsIdentityProperties = {
  callerClientConfig: {
    credentials: async () => ({
      accessKeyId: "dynamic-key",
      secretAccessKey: "dynamic-secret"
    }),
    region: async () => "us-east-1",
    logger: console
  }
};

// Configure credential provider options
const providerOptions: CredentialProviderOptions = {
  logger: console,
  parentClientConfig: {
    region: "us-west-2",
    profile: "development"
  }
};