feat: Add AWS SSO credential support for SDK v3 (Claude-assisted)

[dhait]

Summary

This PR adds support for AWS SSO (Single Sign-On) credentials when using AWS SDK v3 mode. Users can now authenticate using aws sso login and deploy their serverless applications using SSO profiles.

Fixes #87

What Changed

Core Features

• Added SSO credential support via fromNodeProviderChain from @aws-sdk/credential-providers
• Profile resolution logic that respects the correct precedence order (CLI flag > environment > config)
• Enhanced error messages for SSO-specific failures (expired sessions, missing login)

Bug Fixes (discovered during implementation)

• Fixed missing CloudFormation command: Added describeChangeSet to SDK v3 command mappings
• Fixed S3 empty response handling: SDK v3 doesn't include Contents property for empty buckets

Files Modified

1. /lib/plugins/aws/provider.js

   • Added import for fromNodeProviderChain
   • Added _getActiveProfile() method to determine active AWS profile
   • Modified _getV3BaseConfig() to use credential providers instead of static credentials
   • Updated getCredentials() for v3 SDK mode with SSO support
   • Enhanced error handling in _requestV3() with SSO-specific error messages

2. /lib/aws/commands.js

   • Added DescribeChangeSetCommand import and mapping

3. /lib/plugins/aws/deploy/lib/check-for-changes.js

   • Fixed handling of empty S3 bucket listings for SDK v3

4. /lib/plugins/aws/utils/find-and-group-deployments.js

   • Fixed handling of S3 responses without Contents property

5. /lib/plugins/aws/remove/lib/bucket.js

   • Fixed handling of S3 responses without Contents property

6. /docs/guides/credentials.md

   • Added comprehensive SSO documentation with examples

7. /test/unit/lib/plugins/aws/provider.test.js

   • Added 12 comprehensive tests for SSO functionality

How to Test

1. Enable SDK v3 mode (required for SSO support):

   export SLS_AWS_SDK_V3=1

2. Login with AWS SSO:

   aws sso login --profile your-sso-profile

3. Deploy using SSO profile:

   serverless deploy --aws-profile your-sso-profile

Testing Checklist

• ✅ All 12 new SSO-specific tests passing
• ✅ Existing tests remain passing
• ✅ Linting passes (npm run lint)
• ✅ Manual testing confirms deployment works with SSO credentials
• ✅ Tested with both legacy SSO format and new SSO session format
• ✅ Error messages display correctly for expired/missing sessions
• ✅ Backward compatibility verified (SDK v2 mode unchanged)

Breaking Changes

None. This feature is only active when SLS_AWS_SDK_V3=1 is set. Existing credential methods continue to work as before.

Documentation

Updated /docs/guides/credentials.md with:

• Instructions for configuring SSO profiles
• Usage examples with the Serverless Framework
• Examples of both SSO configuration formats
• Troubleshooting guidance

Important Notes

• SSO support requires AWS SDK v3 mode (SLS_AWS_SDK_V3=1 environment variable)
• The credential provider chain handles all fallback scenarios automatically
• Supports both legacy SSO format and new SSO session format in ~/.aws/config
• Provides helpful error messages when SSO session expires or is missing

Performance Impact

Minimal. The credential provider chain only resolves credentials when needed and caches them appropriately.

Security Considerations

• SSO credentials are temporary and automatically expire
• No credentials are stored in code or configuration files
• Uses AWS's standard credential provider chain security model

Future Enhancements

Consider making SDK v3 the default mode in a future major release to enable SSO support by default.

NOTE: Claude by Anthropic assisted in the development of this code.