lex-identity-approle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 630ee2dc79404f13449fd09d3bfd5e4a8608b7f453cae79c4077e75e247f6c55
+  data.tar.gz: 2b99766aece2ca3e516576664b11bc6066cac56ef0cdec2a0a6adfafe7e47b10
+SHA512:
+  metadata.gz: 58e2dc76f64b7ad4871614edbc8991ba803dcc383d616e2e818d967bbc95b8ec605cda92256594e86ad538c3432d1b0e8a5df8e31ece433eeb206190215a0ad7
+  data.tar.gz: 318724056bc425c0ed4d5225af91c5ebee2622b7f8c396f30f2c0ce6c6dac1a49a927ba638ea16c2aea988864bc8750e7f868fcd04eef66a992686673efa11ea

data/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Auto-generated from team-config.yml
+# Team: extensions
+#
+# To apply: scripts/apply-codeowners.sh lex-identity-approle
+
+* @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,2 @@
+inherit_gem:
+  rubocop-legion: config/lex.yml

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [0.1.0] - 2026-04-07
+
+### Added
+
+- Initial release
+- `Identity` module implementing the LegionIO identity provider contract
+- `provider_type: :auth`, `facing: :machine`, `priority: 100`, `trust_weight: 100`
+- `capabilities: [:authenticate, :vault_auth]`
+- `resolve` calls `provide_token` internally (single login, prevents double secret_id consumption)
+- `provide_token` performs Vault AppRole login and returns a `Legion::Identity::Lease`
+- Cached lease (`@cached_lease`) — prevents re-use of single-use secret_ids
+- Expired-lease detection via `Lease#valid?`
+- `role_id` and `secret_id` sourced from settings, ENV, or file mounts (K8s secret paths)
+- Uses `Legion::Crypt::LeaseManager.instance.logical` for namespace-aware Vault routing when available
+- Top-level delegation methods (`provider_name`, `provider_type`, `facing`) for extension registration
+- `normalize` replaces non-alphanumeric chars (except `_` and `-`) with underscores
+- Full spec coverage: provider contract, resolve, provide_token, settings, file-based credentials

data/CLAUDE.md

@@ -0,0 +1,99 @@
+# lex-identity-approle: Vault AppRole Identity Provider for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent (Level 2)**: `/Users/miverso2/rubymine/legion/extensions/CLAUDE.md`
+- **Parent (Level 1)**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Vault AppRole machine identity provider. Authenticates to Vault at boot via AppRole, caches the lease, and exposes the identity to the LegionIO framework. Greenfield gem — no existing AppRole code in the codebase.
+
+**GitHub**: https://github.com/LegionIO/lex-identity-approle
+**License**: MIT
+**Version**: 0.1.0
+
+## Architecture
+
+```
+Legion::Extensions::Identity::Approle
+├── identity_provider? = true
+├── remote_invocable?  = false
+├── provider_name (delegates to Identity)
+├── provider_type (delegates to Identity)
+├── facing (delegates to Identity)
+└── Identity    # provider contract: resolve, provide_token, normalize, ...
+    Settings    # ENV + file-based credential loading
+```
+
+No runners, no actors, no transport helpers.
+
+## File Map
+
+| File | Purpose |
+|------|---------|
+| `lib/legion/extensions/identity/approle.rb` | Entry point: declares `identity_provider?`, `remote_invocable?`, delegation methods |
+| `lib/legion/extensions/identity/approle/identity.rb` | Provider contract: `resolve`, `provide_token`, `normalize`, private helpers |
+| `lib/legion/extensions/identity/approle/settings.rb` | Settings with ENV + Legion::Settings fallback |
+| `lib/legion/extensions/identity/approle/version.rb` | `VERSION = '0.1.0'` |
+
+## Provider Contract
+
+| Method | Return |
+|--------|--------|
+| `provider_name` | `:approle` |
+| `provider_type` | `:auth` |
+| `facing` | `:machine` |
+| `priority` | `100` |
+| `trust_weight` | `100` |
+| `capabilities` | `%i[authenticate vault_auth]` |
+| `resolve` | identity hash or `nil` |
+| `provide_token` | `Legion::Identity::Lease` or `nil` |
+| `normalize(val)` | String |
+
+## Key Rules
+
+- `resolve` calls `provide_token` internally — single login per boot cycle
+- `@cached_lease` prevents double-consumption of single-use secret_ids
+- `private_class_method` with explicit method names: `build_lease`, `vault_approle_login`, `role_id`, `secret_id`, `read_file`, `settings`
+- Uses `Legion::Crypt::LeaseManager.instance.logical` when available; falls back to `::Vault.logical`
+- `normalize` replaces non-alphanumeric chars (except `_` and `-`) with underscores
+
+## Settings
+
+```json
+{
+  "identity": {
+    "approle": {
+      "role_id": null,
+      "secret_id": null,
+      "role_id_file": "/run/secrets/vault-role-id",
+      "secret_id_file": "/run/secrets/vault-secret-id",
+      "auth_path": "approle"
+    }
+  }
+}
+```
+
+ENV fallbacks: `VAULT_APPROLE_ROLE_ID`, `VAULT_APPROLE_SECRET_ID`.
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `legion-json` | JSON serialization (framework compat) |
+| `legion-settings` | Configuration management (framework compat) |
+
+Runtime optional (not declared in gemspec):
+- `vault` gem — used via `::Vault.logical` or `Legion::Crypt::LeaseManager`
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec     # full suite
+bundle exec rubocop   # clean
+```
+
+---
+
+**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/README.md

@@ -0,0 +1,62 @@
+# lex-identity-approle
+
+Vault AppRole identity provider for LegionIO. Machine identity for headless services.
+
+## Overview
+
+`lex-identity-approle` is a Phase 6 identity provider that authenticates to HashiCorp Vault using the AppRole auth method. It provides machine identity for Nomad jobs, K8s pods, and any headless service that needs to bind a Vault token at boot.
+
+**Provider contract:**
+
+| Attribute | Value |
+|-----------|-------|
+| `provider_name` | `:approle` |
+| `provider_type` | `:auth` |
+| `facing` | `:machine` |
+| `priority` | `100` (highest — tried first among machine auth providers) |
+| `trust_weight` | `100` |
+| `capabilities` | `[:authenticate, :vault_auth]` |
+
+## Credential Sources
+
+`role_id` and `secret_id` are resolved in this order:
+
+1. `Legion::Settings[:identity][:approle][:role_id]` / `[:secret_id]`
+2. `ENV['VAULT_APPROLE_ROLE_ID']` / `ENV['VAULT_APPROLE_SECRET_ID']`
+3. File mounts: `/run/secrets/vault-role-id` / `/run/secrets/vault-secret-id` (K8s default)
+
+Override file paths via settings:
+
+```json
+{
+  "identity": {
+    "approle": {
+      "role_id_file": "/custom/path/role-id",
+      "secret_id_file": "/custom/path/secret-id",
+      "auth_path": "approle"
+    }
+  }
+}
+```
+
+## Single-Login Design
+
+`resolve` calls `provide_token` internally. `provide_token` caches the returned Lease in `@cached_lease` and returns it on subsequent calls as long as it remains valid. This prevents double-consumption of single-use `secret_id` values (the Vault AppRole default is `secret_id_num_uses = 1`).
+
+To use unlimited secret_ids, configure Vault with `secret_id_num_uses = 0`.
+
+## Vault Routing
+
+Uses `Legion::Crypt::LeaseManager.instance.logical` when available for namespace-aware routing. Falls back to `::Vault.logical` when legion-crypt is not loaded.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'lex-identity-approle'
+```
+
+## License
+
+MIT

data/lex-identity-approle.gemspec

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/identity/approle/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-identity-approle'
+  spec.version       = Legion::Extensions::Identity::Approle::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Identity AppRole'
+  spec.description   = 'LegionIO Vault AppRole identity provider — machine identity for headless services authenticating to Vault'
+  spec.homepage      = 'https://github.com/LegionIO/lex-identity-approle'
+  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-approle'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-identity-approle'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-identity-approle'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-identity-approle/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 'legion-json',     '>= 1.2.1'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
+end

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

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Approle
+        module Identity
+          module_function
+
+          def provider_name
+            :approle
+          end
+
+          def provider_type
+            :auth
+          end
+
+          def facing
+            :machine
+          end
+
+          def priority
+            100
+          end
+
+          def trust_weight
+            100
+          end
+
+          def capabilities
+            %i[authenticate vault_auth]
+          end
+
+          def resolve(canonical_name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            return nil unless role_id && secret_id
+
+            lease = provide_token
+            return nil unless lease
+
+            meta = lease.metadata || {}
+            {
+              canonical_name: normalize(meta[:role_name] || "approle-#{role_id[0..7]}"),
+              kind:           :machine,
+              source:         :approle,
+              persistent:     true,
+              groups:         meta[:policies] || [],
+              metadata:       { role_name: meta[:role_name], policies: meta[:policies] }
+            }
+          end
+
+          def provide_token
+            return @cached_lease if @cached_lease&.valid? # rubocop:disable ThreadSafety/ClassInstanceVariable
+            return nil unless role_id && secret_id
+
+            response = vault_approle_login(role_id: role_id, secret_id: secret_id)
+            return nil unless response
+
+            @cached_lease = build_lease(response) # rubocop:disable ThreadSafety/ClassInstanceVariable
+          end
+
+          def normalize(val)
+            val.to_s.downcase.strip.gsub(/[^a-z0-9_-]/, '_')
+          end
+
+          def build_lease(response)
+            Legion::Identity::Lease.new(
+              provider:   :approle,
+              credential: response.auth.client_token,
+              lease_id:   response.auth.lease_id,
+              expires_at: Time.now + response.auth.lease_duration,
+              renewable:  response.auth.renewable,
+              issued_at:  Time.now,
+              metadata:   { policies: response.auth.policies }
+            )
+          end
+
+          def vault_approle_login(role_id:, secret_id:)
+            logical = if defined?(Legion::Crypt::LeaseManager)
+                        Legion::Crypt::LeaseManager.instance.logical
+                      else
+                        ::Vault.logical
+                      end
+            logical.write(
+              "auth/#{settings[:auth_path] || 'approle'}/login",
+              role_id:   role_id,
+              secret_id: secret_id
+            )
+          rescue ::Vault::HTTPError => e
+            Legion::Logging.warn("AppRole login failed: #{e.message}") if defined?(Legion::Logging) # rubocop:disable Legion/HelperMigration/DirectLogging, Legion/HelperMigration/LoggingGuard
+            nil
+          end
+
+          def role_id
+            settings[:role_id] || read_file(settings[:role_id_file])
+          end
+
+          def secret_id
+            settings[:secret_id] || read_file(settings[:secret_id_file])
+          end
+
+          def read_file(path)
+            return nil unless path && File.exist?(path)
+
+            File.read(path).strip
+          end
+
+          def settings
+            Approle::Settings.settings
+          end
+
+          private_class_method :build_lease, :vault_approle_login, :role_id, :secret_id, :read_file, :settings
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Approle
+        module Settings
+          DEFAULTS = {
+            role_id:        ENV.fetch('VAULT_APPROLE_ROLE_ID', nil),
+            secret_id:      ENV.fetch('VAULT_APPROLE_SECRET_ID', nil),
+            role_id_file:   '/run/secrets/vault-role-id',
+            secret_id_file: '/run/secrets/vault-secret-id',
+            auth_path:      'approle'
+          }.freeze
+
+          def self.settings
+            return Legion::Settings[:identity][:approle] if defined?(Legion::Settings) &&
+                                                            Legion::Settings[:identity].is_a?(Hash) &&
+                                                            Legion::Settings[:identity][:approle].is_a?(Hash)
+
+            DEFAULTS
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/identity/approle/version'
+require 'legion/extensions/identity/approle/settings'
+require 'legion/extensions/identity/approle/identity'
+
+module Legion
+  module Extensions
+    module Identity
+      module Approle
+        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,89 @@
+--- !ruby/object:Gem::Specification
+name: lex-identity-approle
+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: 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 Vault AppRole identity provider — machine identity for headless
+  services authenticating to Vault
+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
+- README.md
+- lex-identity-approle.gemspec
+- lib/legion/extensions/identity/approle.rb
+- lib/legion/extensions/identity/approle/identity.rb
+- lib/legion/extensions/identity/approle/settings.rb
+- lib/legion/extensions/identity/approle/version.rb
+homepage: https://github.com/LegionIO/lex-identity-approle
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-identity-approle
+  source_code_uri: https://github.com/LegionIO/lex-identity-approle
+  documentation_uri: https://github.com/LegionIO/lex-identity-approle
+  changelog_uri: https://github.com/LegionIO/lex-identity-approle
+  bug_tracker_uri: https://github.com/LegionIO/lex-identity-approle/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 AppRole
+test_files: []