lex-identity-aws 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c40345c1b15e2e8de94ee6ce8e4a1223686c444794d5f266c40439e1140267e6
+  data.tar.gz: a92d1150ad3a709dc0a8f0ec9d9dfe66b8a0d7078cd59de7fb5cc38c860a2357
+SHA512:
+  metadata.gz: 156198c60dce379bcfd992e5fa383cae5eb9b0d5796c5f6247c701e3366c1cf2a3e26974f1da9328c367a265e641da2d114a01c00bfc16fee39080d2677f4736
+  data.tar.gz: 4bc293f39cda7e5c5098952a7a3afa8b1aee367ec364d8450b26529f9bad6ab573dc353235c03876e583f8cae27ad2b1e96f9e26adb67ed8d798be12ed8e83a8

data/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Auto-generated from team-config.yml
+# Team: extensions
+#
+# To apply: scripts/apply-codeowners.sh lex-identity-aws
+
+* @LegionIO/maintainers
+* @LegionIO/extensions

data/.github/dependabot.yml

@@ -0,0 +1,18 @@
+version: 2
+updates:
+  - package-ecosystem: bundler
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+      day: monday
+    open-pull-requests-limit: 5
+    labels:
+      - "type:dependencies"

data/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    - cron: '0 9 * * 1'
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  excluded-files:
+    uses: LegionIO/.github/.github/workflows/excluded-files.yml@main
+
+  security:
+    uses: LegionIO/.github/.github/workflows/security-scan.yml@main
+
+  version-changelog:
+    uses: LegionIO/.github/.github/workflows/version-changelog.yml@main
+
+  dependency-review:
+    uses: LegionIO/.github/.github/workflows/dependency-review.yml@main
+
+  stale:
+    if: github.event_name == 'schedule'
+    uses: LegionIO/.github/.github/workflows/stale.yml@main
+
+  release:
+    needs: [ci, excluded-files]
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.rspec_status
+Gemfile.lock

data/.rubocop.yml

@@ -0,0 +1,8 @@
+inherit_gem:
+  rubocop-legion: config/lex.yml
+
+# Identity provider modules use def self.* methods and cannot include Helpers::Lex.
+# Direct Legion::Logging calls are the only option in this context.
+Legion/HelperMigration/DirectLogging:
+  Exclude:
+    - 'lib/legion/extensions/identity/aws/identity.rb'

data/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## [0.1.0] - 2026-04-07
+
+### Added
+
+- Initial release
+- `Identity` module implementing the LegionIO identity provider contract
+- `provider_type: :auth`, `facing: :machine`, `priority: 90`, `trust_weight: 100`
+- `capabilities: [:authenticate, :credentials]`
+- `resolve` calls STS `GetCallerIdentity` and derives `canonical_name` from the ARN role name segment
+- `provide_token` resolves credentials via AssumeRole (when `role_arn` configured) or default chain,
+  returns a `Legion::Identity::Lease` with only `access_key_id` + region in metadata (never `secret_access_key` or `session_token`)
+- `current_credentials` exposes the cached `Aws::Credentials` object for Phase 8 consumers via `Broker.credentials_for`
+- `default_chain_credentials` uses an STS client to trigger the full SDK credential chain (env vars, shared creds, web identity, ECS, instance profile)
+- `StandardError` rescue in `default_chain_credentials` to handle `Aws::EC2Metadata::RequestError` (RuntimeError) and `Aws::Errors::NoSuchProfileError`
+- Top-level delegation methods (`provider_name`, `provider_type`, `facing`) satisfy extension registration without enabling double-resolution
+- `Settings` module with ENV fallbacks: `AWS_REGION`, `AWS_DEFAULT_REGION`, `AWS_ROLE_ARN`, `AWS_PROFILE`

data/CLAUDE.md

@@ -0,0 +1,46 @@
+# lex-identity-aws
+
+**Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+AWS IAM identity provider for LegionIO. Phase 6 cloud/machine provider. Resolves machine identity from STS `GetCallerIdentity` and provides session credentials via instance profile or AssumeRole.
+
+**GitHub**: https://github.com/LegionIO/lex-identity-aws
+**Gem**: `lex-identity-aws`
+**Version**: 0.1.0
+**License**: MIT
+**Category**: `identity` (prefix match, phase 0, tier 0)
+
+## Key Design Rules
+
+- NEVER store `secret_access_key` or `session_token` in Lease metadata — only `access_key_id` + region + expiration
+- Use STS client for default chain credentials (NOT `Aws::CredentialProviderChain` — internal API)
+- Force-resolve lazy credentials with `.credentials` call
+- Rescue `StandardError` (not just `Aws::Errors::ServiceError`) — `Aws::EC2Metadata::RequestError` is RuntimeError
+- `canonical_name` derived from ARN role name segment (second slash-split segment)
+- `provide_token` credential field is `access_key_id` only (non-secret identifier)
+- Store actual `Aws::Credentials` object in `@credential_cache` — exposed via `current_credentials` for Phase 8 consumers
+- `private_class_method` with explicit method names
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/extensions/identity/aws.rb` | Entry point — top-level module with `identity_provider?`, `remote_invocable?`, delegation methods |
+| `lib/legion/extensions/identity/aws/identity.rb` | Provider contract: `resolve`, `provide_token`, `current_credentials`, `normalize` + private helpers |
+| `lib/legion/extensions/identity/aws/settings.rb` | Settings module with ENV fallbacks |
+| `lib/legion/extensions/identity/aws/version.rb` | VERSION constant |
+| `spec/legion/extensions/identity/aws/identity_spec.rb` | Unit tests for Identity module |
+| `spec/legion/extensions/identity/aws/settings_spec.rb` | Unit tests for Settings module |
+
+## Dependencies
+
+- `aws-sdk-core` >= 3.0
+- `aws-sdk-sts` >= 1.0
+- `legion-json` >= 1.2.1
+- `legion-settings` >= 1.3.14
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+gemspec
+
+group :development, :test do
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.75'
+  gem 'rubocop-legion', '~> 0.1'
+  gem 'simplecov', '~> 0.22'
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# lex-identity-aws
+
+AWS IAM identity provider for [LegionIO](https://github.com/LegionIO/LegionIO).
+
+Resolves machine identity from AWS STS and provides session credentials via instance profile or AssumeRole. Part of the Phase 6 cloud/machine provider suite.
+
+## Provider Contract
+
+| Attribute | Value |
+|-----------|-------|
+| `provider_name` | `:aws` |
+| `provider_type` | `:auth` |
+| `facing` | `:machine` |
+| `priority` | `90` |
+| `trust_weight` | `100` |
+| `capabilities` | `[:authenticate, :credentials]` |
+
+## Usage
+
+The provider auto-discovers via the `lex-identity-*` prefix in LegionIO's category registry and loads at phase 0 (before all other extensions).
+
+At boot, `resolve` calls `sts.get_caller_identity` and derives a canonical name from the IAM role name segment of the ARN:
+
+```
+arn:aws:sts::123456789012:assumed-role/legion-worker/session  ->  legion-worker
+arn:aws:iam::123456789012:role/my-role                        ->  my-role
+```
+
+`provide_token` returns a `Legion::Identity::Lease` with `credential` set to `access_key_id` only. The full `Aws::Credentials` object (including secret and session token) is cached in memory and accessible via `Identity.current_credentials` or `Broker.credentials_for(:aws)` (Phase 8).
+
+## Security
+
+`secret_access_key` and `session_token` are **never** stored in Lease metadata. Lease metadata is exposed via audit logs, `/api/stats`, and Apollo. Use `Broker.credentials_for(:aws)` for full credential access.
+
+## Credential Chain
+
+When `role_arn` is not configured, the provider uses an STS client to trigger the full AWS SDK default credential chain:
+
+1. Environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+2. Shared credentials file (`~/.aws/credentials`)
+3. Web identity token (EKS IRSA)
+4. ECS task role
+5. EC2 instance profile (IMDSv2)
+
+When `role_arn` is configured, `AssumeRoleCredentials` is used instead.
+
+## Settings
+
+Configure via `settings.json` under `identity.aws`:
+
+```json
+{
+  "identity": {
+    "aws": {
+      "region": "us-east-2",
+      "role_arn": "arn:aws:iam::123456789012:role/my-role",
+      "session_duration": 3600,
+      "profile": "vault-contributor"
+    }
+  }
+}
+```
+
+All settings fall back to ENV vars: `AWS_REGION`, `AWS_DEFAULT_REGION`, `AWS_ROLE_ARN`, `AWS_PROFILE`.
+
+## Dependencies
+
+- `aws-sdk-core` >= 3.0
+- `aws-sdk-sts` >= 1.0
+- `legion-json` >= 1.2.1
+- `legion-settings` >= 1.3.14
+
+## License
+
+MIT

data/lex-identity-aws.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/identity/aws/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-identity-aws'
+  spec.version       = Legion::Extensions::Identity::Aws::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Identity AWS'
+  spec.description   = 'LegionIO AWS IAM identity provider — resolves machine identity from STS ' \
+                       'and provides session credentials via instance profile or AssumeRole'
+  spec.homepage      = 'https://github.com/LegionIO/lex-identity-aws'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 3.4'
+
+  spec.metadata['homepage_uri']          = spec.homepage
+  spec.metadata['source_code_uri']       = 'https://github.com/LegionIO/lex-identity-aws'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-identity-aws'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-identity-aws'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-identity-aws/issues'
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'aws-sdk-core', '>= 3.0'
+  spec.add_dependency 'aws-sdk-sts',  '>= 1.0'
+  spec.add_dependency 'legion-json',     '>= 1.2.1'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
+end

data/lib/legion/extensions/identity/aws/identity.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Aws
+        module Identity
+          def self.provider_name
+            :aws
+          end
+
+          def self.provider_type
+            :auth
+          end
+
+          def self.facing
+            :machine
+          end
+
+          def self.priority
+            90
+          end
+
+          def self.trust_weight
+            100
+          end
+
+          def self.capabilities
+            %i[authenticate credentials]
+          end
+
+          def self.resolve(canonical_name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            identity = caller_identity
+            return nil unless identity
+
+            # ARN format: arn:aws:sts::123456789012:assumed-role/role-name/session-name
+            # or:         arn:aws:iam::123456789012:role/role-name
+            arn_parts = identity.arn.to_s.split('/')
+            role_name = arn_parts[1] || identity.arn.to_s.split(':').last
+
+            {
+              canonical_name: normalize(role_name),
+              kind:           :machine,
+              source:         :aws,
+              persistent:     true,
+              groups:         [],
+              metadata:       {
+                account_id: identity.account,
+                arn:        identity.arn,
+                user_id:    identity.user_id
+              }
+            }
+          end
+
+          def self.provide_token
+            credentials = resolve_credentials
+            return nil unless credentials
+
+            expires_at = if credentials.respond_to?(:expiration) && credentials.expiration
+                           credentials.expiration
+                         else
+                           Time.now + 3600
+                         end
+
+            # Store the full credential object for Broker.credentials_for(:aws) consumers.
+            # NEVER store secret_access_key or session_token in Lease metadata —
+            # Lease#to_h is exposed via audit logs, /api/stats, and Apollo.
+            @credential_cache = credentials # rubocop:disable ThreadSafety/ClassInstanceVariable
+
+            Legion::Identity::Lease.new(
+              provider:   :aws,
+              credential: credentials.access_key_id,
+              expires_at: expires_at,
+              renewable:  credentials.respond_to?(:expiration),
+              issued_at:  Time.now,
+              metadata:   {
+                access_key_id: credentials.access_key_id,
+                region:        settings[:region],
+                expiration:    expires_at&.iso8601
+              }
+            )
+          end
+
+          def self.current_credentials
+            @credential_cache # rubocop:disable ThreadSafety/ClassInstanceVariable
+          end
+
+          def self.normalize(val)
+            val.to_s.downcase.strip.gsub(/[^a-z0-9_-]/, '_')
+          end
+
+          def self.settings
+            Legion::Extensions::Identity::Aws.settings
+          end
+
+          def self.caller_identity
+            require 'aws-sdk-sts'
+            sts = ::Aws::STS::Client.new(region: settings[:region])
+            sts.get_caller_identity
+          rescue ::Aws::Errors::ServiceError => e
+            Legion::Logging.warn("AWS STS get_caller_identity failed: #{e.message}")
+            nil
+          end
+
+          def self.resolve_credentials
+            if settings[:role_arn]
+              assume_role_credentials
+            else
+              default_chain_credentials
+            end
+          end
+
+          def self.assume_role_credentials
+            require 'aws-sdk-sts'
+            instance_id = defined?(Legion) && Legion.respond_to?(:instance_id) ? Legion.instance_id.to_s[0..7] : 'default'
+            ::Aws::AssumeRoleCredentials.new(
+              client:            ::Aws::STS::Client.new(region: settings[:region]),
+              role_arn:          settings[:role_arn],
+              role_session_name: "legion-#{instance_id}",
+              duration_seconds:  settings[:session_duration] || 3600
+            )
+          rescue ::Aws::Errors::ServiceError => e
+            Legion::Logging.warn("AWS AssumeRole failed: #{e.message}")
+            nil
+          end
+
+          def self.default_chain_credentials
+            require 'aws-sdk-core'
+            # Use an STS client to trigger the full SDK default credential chain.
+            # Aws::CredentialProviderChain is internal and not a public API.
+            # Creating an STS client triggers: env vars -> shared credentials ->
+            # web identity -> ECS task role -> instance profile (the full chain).
+            client = ::Aws::STS::Client.new(region: settings[:region])
+            creds  = client.config.credentials
+            creds.credentials # force-resolve lazy credentials
+            creds
+          rescue StandardError => e
+            # Aws::EC2Metadata::RequestError is RuntimeError, not ServiceError.
+            # Aws::Errors::NoSuchProfileError for invalid AWS_PROFILE.
+            # All caught here for graceful fallback.
+            Legion::Logging.debug("AWS default chain failed: #{e.message}")
+            nil
+          end
+
+          private_class_method :caller_identity, :resolve_credentials, :assume_role_credentials,
+                               :default_chain_credentials, :settings
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/aws/settings.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Aws
+        SETTINGS_DEFAULTS = {
+          region:           nil,
+          role_arn:         nil,
+          session_duration: 3600,
+          profile:          nil
+        }.freeze
+
+        def self.settings
+          base = if defined?(Legion::Settings) && Legion::Settings.respond_to?(:dig)
+                   Legion::Settings.dig(:identity, :aws) || {}
+                 else
+                   {}
+                 end
+
+          region = ENV.fetch('AWS_REGION', nil) || ENV.fetch('AWS_DEFAULT_REGION', nil) || 'us-east-2'
+          role_arn = ENV.fetch('AWS_ROLE_ARN', nil)
+          profile  = ENV.fetch('AWS_PROFILE', nil)
+
+          SETTINGS_DEFAULTS
+            .merge(region: region, role_arn: role_arn, profile: profile)
+            .merge(base)
+        end
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/aws/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Aws
+        VERSION = '0.1.0'
+      end
+    end
+  end
+end

data/lib/legion/extensions/identity/aws.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/identity/aws/version'
+require 'legion/extensions/identity/aws/settings'
+require 'legion/extensions/identity/aws/identity'
+
+module Legion
+  module Extensions
+    module Identity
+      module Aws
+        extend Legion::Extensions::Core if Legion::Extensions.const_defined?(:Core, false)
+
+        def self.identity_provider?
+          true
+        end
+
+        def self.remote_invocable?
+          false
+        end
+
+        def self.provider_name
+          Identity.provider_name
+        end
+
+        def self.provider_type
+          Identity.provider_type
+        end
+
+        def self.facing
+          Identity.facing
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: lex-identity-aws
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Esity
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: aws-sdk-sts
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: legion-json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: legion-settings
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.14
+description: LegionIO AWS IAM identity provider — resolves machine identity from STS
+  and provides session credentials via instance profile or AssumeRole
+email:
+- matthewdiverson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/CODEOWNERS"
+- ".github/dependabot.yml"
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rubocop.yml"
+- CHANGELOG.md
+- CLAUDE.md
+- Gemfile
+- LICENSE
+- README.md
+- lex-identity-aws.gemspec
+- lib/legion/extensions/identity/aws.rb
+- lib/legion/extensions/identity/aws/identity.rb
+- lib/legion/extensions/identity/aws/settings.rb
+- lib/legion/extensions/identity/aws/version.rb
+homepage: https://github.com/LegionIO/lex-identity-aws
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-identity-aws
+  source_code_uri: https://github.com/LegionIO/lex-identity-aws
+  documentation_uri: https://github.com/LegionIO/lex-identity-aws
+  changelog_uri: https://github.com/LegionIO/lex-identity-aws
+  bug_tracker_uri: https://github.com/LegionIO/lex-identity-aws/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: LEX Identity AWS
+test_files: []