lex-identity-kubernetes 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 64532b0d40a6355aae79ca7e617fe31c4eeac3ab314cc19e332ae08a82c1a81a
+  data.tar.gz: 87bbcc620b450a6164831b4c12b3fd1c244d3ebae039444cd369ad91e3b35f23
+SHA512:
+  metadata.gz: 16d652cd69c68996700401b73979b2624d44a4d24a3ba6215f7a9a266e36710443c8a962db595580fd1b0cf19d0497bbdb8578a595d6be152c4bc3d24690175b
+  data.tar.gz: c79c166fa01b11844c6c91507eab494b03abc4c831eb41908adc82920f515cbc777d564d8bd4b3fb8fa922cb9bc199b984661726c8a64e8510d732988b36e483

data/.github/CODEOWNERS

@@ -0,0 +1,7 @@
+# Auto-generated from team-config.yml
+# Team: extensions
+#
+# To apply: scripts/apply-codeowners.sh lex-identity-kubernetes
+
+* @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,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: 95`, `trust_weight: 100`
+- `capabilities: [:authenticate, :vault_auth]`
+- `resolve` reads projected SA token from `/var/run/secrets/kubernetes.io/serviceaccount/token`
+- Vault-verified path: when `Legion::Crypt::LeaseManager` is available, validates token via `auth/kubernetes/login` and populates groups from Vault policies
+- Unverified JWT fallback: decodes JWT payload without signature verification; `groups` always `[]` on this path (RBAC safety); logs warning
+- `provide_token` returns a `Legion::Identity::Lease` with `renewable: true` (projected tokens auto-rotate)
+- `vault_auth` delegates to `LeaseManager#vault_logical` for namespace-aware Vault calls
+- `canonical_name` derived from `namespace-sa_name` (dots and special chars replaced with hyphens)
+- `Settings` module with configurable `token_path`, `namespace_path`, `vault_role`, `vault_auth_path`
+- `normalize` strips non-alphanumeric characters, collapses consecutive hyphens, trims leading/trailing hyphens

data/CLAUDE.md

@@ -0,0 +1,78 @@
+# lex-identity-kubernetes: Kubernetes Service Account Identity Provider
+
+**Repository Level 3 Documentation**
+- **Parent (Level 2)**: `/Users/miverso2/rubymine/legion/extensions/CLAUDE.md`
+- **Parent (Level 1)**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Kubernetes service account identity provider for LegionIO. Reads projected SA tokens from the standard K8s mount path and validates them via Vault Kubernetes auth (preferred) or falls back to unverified JWT decode.
+
+**GitHub**: https://github.com/LegionIO/lex-identity-kubernetes
+**License**: MIT
+**Version**: 0.1.0
+
+## Architecture
+
+```
+Legion::Extensions::Identity::Kubernetes
+├── Identity    # provider contract: resolve, provide_token, vault_auth, normalize, ...
+└── Settings    # default settings (token_path, namespace_path, vault_role, vault_auth_path)
+```
+
+No runners, no actors, no transport. Identity-only gem.
+
+## File Map
+
+| File | Purpose |
+|------|---------|
+| `lib/legion/extensions/identity/kubernetes.rb` | Entry point — requires version/settings/identity, declares `identity_provider?`, `remote_invocable?`, top-level delegation methods |
+| `lib/legion/extensions/identity/kubernetes/identity.rb` | Provider contract: `resolve`, `provide_token`, `vault_auth`, `normalize`, private helpers |
+| `lib/legion/extensions/identity/kubernetes/settings.rb` | Default settings, `Settings.get` merges with `Legion::Settings` |
+| `lib/legion/extensions/identity/kubernetes/version.rb` | `VERSION = '0.1.0'` |
+
+## Provider Contract
+
+| Method | Return |
+|--------|--------|
+| `provider_name` | `:kubernetes` |
+| `provider_type` | `:auth` |
+| `facing` | `:machine` |
+| `priority` | `95` |
+| `trust_weight` | `100` |
+| `capabilities` | `[:authenticate, :vault_auth]` |
+| `resolve` | identity hash or `nil` |
+| `provide_token` | `Legion::Identity::Lease` or `nil` |
+| `vault_auth(token:)` | Vault response or `nil` |
+| `normalize(val)` | String |
+
+## Key Design Rules
+
+- `groups: []` on unverified path — NEVER populate groups from unverified JWT for RBAC safety
+- Log warning when using unverified path: `"K8s identity resolved without cryptographic verification — groups empty"`
+- `groups` from Vault-verified path only — populated from `response.auth.policies`
+- `provide_token` re-reads SA token from file each call — projected tokens auto-rotate
+- `renewable: true` — signals `LeaseRenewer` to call `provide_token` periodically
+- `canonical_name` = `normalize("#{namespace}-#{sa_name}")` — dots replaced with hyphens
+- `private_class_method` explicit method names for all private helpers
+- `vault_logical` via `LeaseManager.instance.vault_logical` (NOT raw `::Vault.logical`)
+- `Legion::JSON.load` returns SYMBOL keys — use `:sub`, `:exp`, `:groups`, NOT string keys
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `legion-json` | JSON serialization (`symbolize_names: true` — SYMBOL keys) |
+| `legion-settings` | Configuration management |
+
+## Testing
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+---
+
+**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,77 @@
+# lex-identity-kubernetes
+
+Kubernetes service account identity provider for LegionIO. Reads projected SA tokens from the standard mount path and optionally validates them via Vault Kubernetes auth.
+
+**Gem**: `lex-identity-kubernetes`
+**Version**: 0.1.0
+**License**: MIT
+
+## Overview
+
+When running inside a Kubernetes pod, LegionIO can establish machine identity from the pod's service account. This provider:
+
+1. Reads the projected SA token from `/var/run/secrets/kubernetes.io/serviceaccount/token`
+2. If Vault is connected: validates the token via `auth/kubernetes/login` and derives groups from Vault policies (verified path)
+3. If Vault is not connected: decodes the JWT payload without signature verification (unverified fallback) — groups are always empty on this path for RBAC safety
+
+## Identity Shape
+
+```ruby
+{
+  canonical_name: 'legionio-legion-worker',   # namespace-sa_name
+  kind:           :machine,
+  source:         :kubernetes,
+  persistent:     true,
+  groups:         ['default', 'legionio'],    # from Vault policies (verified only)
+  metadata:       {
+    namespace:        'legionio',
+    service_account:  'legion-worker',
+    verified:         true   # false on unverified path
+  }
+}
+```
+
+## Configuration
+
+Settings at `Legion::Settings[:identity][:kubernetes]`:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `token_path` | `/var/run/secrets/kubernetes.io/serviceaccount/token` | SA token file path |
+| `namespace_path` | `/var/run/secrets/kubernetes.io/serviceaccount/namespace` | Namespace file path |
+| `vault_role` | `legionio` | Vault Kubernetes auth role |
+| `vault_auth_path` | `kubernetes` | Vault auth mount path |
+
+## Provider Contract
+
+| Method | Return |
+|--------|--------|
+| `provider_name` | `:kubernetes` |
+| `provider_type` | `:auth` |
+| `facing` | `:machine` |
+| `priority` | `95` |
+| `trust_weight` | `100` |
+| `capabilities` | `[:authenticate, :vault_auth]` |
+
+## Vault Setup
+
+```bash
+vault auth enable kubernetes
+vault write auth/kubernetes/config \
+  token_reviewer_jwt="$(cat /var/run/secrets/kubernetes.io/serviceaccount/token)" \
+  kubernetes_host="https://kubernetes.default.svc"
+
+vault write auth/kubernetes/role/legionio \
+  bound_service_account_names=legion-worker \
+  bound_service_account_namespaces=legionio \
+  policies=default,legionio \
+  ttl=1h
+```
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```

data/lex-identity-kubernetes.gemspec

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'lib/legion/extensions/identity/kubernetes/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'lex-identity-kubernetes'
+  spec.version       = Legion::Extensions::Identity::Kubernetes::VERSION
+  spec.authors       = ['Esity']
+  spec.email         = ['matthewdiverson@gmail.com']
+
+  spec.summary       = 'LEX Identity Kubernetes'
+  spec.description   = 'LegionIO Kubernetes service account identity provider — reads projected SA tokens and optionally validates via Vault Kubernetes auth'
+  spec.homepage      = 'https://github.com/LegionIO/lex-identity-kubernetes'
+  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-kubernetes'
+  spec.metadata['documentation_uri']     = 'https://github.com/LegionIO/lex-identity-kubernetes'
+  spec.metadata['changelog_uri']         = 'https://github.com/LegionIO/lex-identity-kubernetes'
+  spec.metadata['bug_tracker_uri']       = 'https://github.com/LegionIO/lex-identity-kubernetes/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 'base64',          '>= 0.2'
+  spec.add_dependency 'legion-json',     '>= 1.2.1'
+  spec.add_dependency 'legion-settings', '>= 1.3.14'
+end

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

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Legion
+  module Extensions
+    module Identity
+      module Kubernetes
+        module Identity
+          SA_TOKEN_PATH     = '/var/run/secrets/kubernetes.io/serviceaccount/token'
+          SA_NAMESPACE_PATH = '/var/run/secrets/kubernetes.io/serviceaccount/namespace'
+
+          def self.provider_name
+            :kubernetes
+          end
+
+          def self.provider_type
+            :auth
+          end
+
+          def self.facing
+            :machine
+          end
+
+          def self.priority
+            95
+          end
+
+          def self.trust_weight
+            100
+          end
+
+          def self.capabilities
+            %i[authenticate vault_auth]
+          end
+
+          def self.resolve(canonical_name: nil) # rubocop:disable Lint/UnusedMethodArgument
+            token = read_sa_token
+            return nil unless token
+
+            if vault_available?
+              vault_resolve(token)
+            else
+              unverified_resolve(token)
+            end
+          end
+
+          def self.provide_token
+            token = read_sa_token
+            return nil unless token
+
+            claims = decode_jwt_claims(token)
+            expires_at = claims && claims[:exp] ? Time.at(claims[:exp]) : nil
+
+            Legion::Identity::Lease.new(
+              provider:   :kubernetes,
+              credential: token,
+              expires_at: expires_at,
+              renewable:  true,
+              issued_at:  Time.now,
+              metadata:   { namespace: read_namespace }
+            )
+          end
+
+          def self.vault_auth(token: nil)
+            token ||= read_sa_token
+            return nil unless token
+
+            logical = if defined?(Legion::Crypt::LeaseManager)
+                        Legion::Crypt::LeaseManager.instance.vault_logical
+                      elsif defined?(::Vault)
+                        ::Vault.logical
+                      end
+            return nil unless logical
+
+            logical.write(
+              "auth/#{settings[:vault_auth_path] || 'kubernetes'}/login",
+              role: settings[:vault_role] || 'legionio',
+              jwt:  token
+            )
+          rescue StandardError => e
+            Legion::Logging.warn("K8s Vault auth failed: #{e.message}") if defined?(Legion::Logging) # rubocop:disable Legion/HelperMigration/DirectLogging,Legion/HelperMigration/LoggingGuard
+            nil
+          end
+
+          def self.normalize(val)
+            val.to_s.downcase.strip.gsub(/[^a-z0-9_-]/, '-').gsub(/-{2,}/, '-').gsub(/^-|-$/, '')
+          end
+
+          def self.settings
+            Kubernetes::Settings.get
+          end
+          private_class_method :settings
+
+          def self.vault_available?
+            defined?(Legion::Crypt::LeaseManager) &&
+              Legion::Crypt::LeaseManager.instance.respond_to?(:vault_logical)
+          end
+          private_class_method :vault_available?
+
+          def self.vault_resolve(token)
+            response = vault_auth(token: token)
+            return unverified_resolve(token) unless response
+
+            policies  = response.auth&.policies || []
+            metadata  = response.auth&.metadata || {}
+            namespace = metadata[:kubernetes_namespace] || read_namespace
+            sa_name   = metadata[:kubernetes_service_account] || 'unknown'
+
+            {
+              canonical_name: normalize("#{namespace}-#{sa_name}"),
+              kind:           :machine,
+              source:         :kubernetes,
+              persistent:     true,
+              groups:         policies,
+              metadata:       { namespace: namespace, service_account: sa_name, verified: true }
+            }
+          end
+          private_class_method :vault_resolve
+
+          def self.unverified_resolve(token)
+            claims = decode_jwt_claims(token)
+            return nil unless claims
+
+            Legion::Logging.warn('K8s identity resolved without cryptographic verification — groups empty') if defined?(Legion::Logging) # rubocop:disable Legion/HelperMigration/DirectLogging,Legion/HelperMigration/LoggingGuard
+
+            parts     = claims[:sub].to_s.split(':')
+            namespace = parts[2] || read_namespace
+            sa_name   = parts[3] || 'unknown'
+
+            {
+              canonical_name: normalize("#{namespace}-#{sa_name}"),
+              kind:           :machine,
+              source:         :kubernetes,
+              persistent:     true,
+              groups:         [],
+              metadata:       { namespace: namespace, service_account: sa_name, verified: false }
+            }
+          end
+          private_class_method :unverified_resolve
+
+          def self.read_sa_token
+            path = settings[:token_path] || SA_TOKEN_PATH
+            return nil unless File.exist?(path)
+
+            File.read(path).strip
+          end
+          private_class_method :read_sa_token
+
+          def self.read_namespace
+            path = settings[:namespace_path] || SA_NAMESPACE_PATH
+            return nil unless File.exist?(path)
+
+            File.read(path).strip
+          end
+          private_class_method :read_namespace
+
+          def self.decode_jwt_claims(token)
+            payload = token.split('.')[1]
+            return nil unless payload
+
+            padded = payload + ('=' * ((4 - (payload.length % 4)) % 4))
+            Legion::JSON.load(Base64.urlsafe_decode64(padded)) # rubocop:disable Legion/HelperMigration/DirectJson
+          rescue StandardError => e
+            Legion::Logging.debug("K8s JWT decode failed: #{e.message}") if defined?(Legion::Logging) # rubocop:disable Legion/HelperMigration/DirectLogging,Legion/HelperMigration/LoggingGuard
+            nil
+          end
+          private_class_method :decode_jwt_claims
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Legion
+  module Extensions
+    module Identity
+      module Kubernetes
+        module Settings
+          DEFAULTS = {
+            token_path:      '/var/run/secrets/kubernetes.io/serviceaccount/token',
+            namespace_path:  '/var/run/secrets/kubernetes.io/serviceaccount/namespace',
+            vault_role:      'legionio',
+            vault_auth_path: 'kubernetes'
+          }.freeze
+
+          def self.load
+            return unless defined?(Legion::Settings)
+
+            Legion::Settings.merge_settings(:kubernetes, DEFAULTS)
+          end
+
+          def self.get
+            return DEFAULTS unless defined?(Legion::Settings)
+
+            settings = Legion::Settings.dig(:identity, :kubernetes)
+            return DEFAULTS if settings.nil?
+
+            DEFAULTS.merge(settings)
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'legion/extensions/identity/kubernetes/version'
+require 'legion/extensions/identity/kubernetes/settings'
+require 'legion/extensions/identity/kubernetes/identity'
+
+module Legion
+  module Extensions
+    module Identity
+      module Kubernetes
+        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,103 @@
+--- !ruby/object:Gem::Specification
+name: lex-identity-kubernetes
+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: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !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 Kubernetes service account identity provider — reads projected
+  SA tokens and optionally validates via Vault Kubernetes auth
+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-kubernetes.gemspec
+- lib/legion/extensions/identity/kubernetes.rb
+- lib/legion/extensions/identity/kubernetes/identity.rb
+- lib/legion/extensions/identity/kubernetes/settings.rb
+- lib/legion/extensions/identity/kubernetes/version.rb
+homepage: https://github.com/LegionIO/lex-identity-kubernetes
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/LegionIO/lex-identity-kubernetes
+  source_code_uri: https://github.com/LegionIO/lex-identity-kubernetes
+  documentation_uri: https://github.com/LegionIO/lex-identity-kubernetes
+  changelog_uri: https://github.com/LegionIO/lex-identity-kubernetes
+  bug_tracker_uri: https://github.com/LegionIO/lex-identity-kubernetes/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 Kubernetes
+test_files: []