spiffe-workload 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1661e0826c4de0e0f9e21788abbd78c41ad04c15b30c2f8e2b5a104949232e3e
+  data.tar.gz: 930a68a433e1e0d7a9b529713352bedd769177cc0e482d57e17c7ca998d54617
+SHA512:
+  metadata.gz: 2c5160736a3274699160105a2e772af9c8259e91292189f69dc5f1de8612b0ef4435ccf7e0d8dd32888780d0ec976dd3c985db2c022d23c94af00034f9a7ddd6
+  data.tar.gz: cc9a091b5373da018de85ec9a5c7b3b0d77a649c5ffde8a13f9da936303632ecab1ecadbb12b10f4335046b4a68cdca1b10d20d2fe0da542b664d3e710d5edc9

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## [0.1.0] - 2026-02-04
+
+### Added
+- Full SPIFFE Workload API implementation
+- X.509 SVID fetching with automatic rotation
+- JWT SVID generation
+- Trust bundle management
+- OpenSSL integration for TLS contexts
+- Thread-safe credential caching
+- Puppet integration support
+- Basic Workload API client
+- Manual protobuf definitions
+
+### Fixed
+- Security header: `workload.spiffe.io: 'true'`
+- gRPC service name: `SpiffeWorkloadAPI`
+- Method names use proper snake_case
+- Proper protobuf code generation

data/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 SPIFFE Ruby Contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,342 @@
+# SPIFFE Workload API - Ruby Client
+
+[![CI](https://github.com/halradaideh/spiffe-rubygem/actions/workflows/ci.yml/badge.svg)](https://github.com/halradaideh/spiffe-rubygem/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/spiffe-workload.svg)](https://badge.fury.io/rb/spiffe-workload)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+A Ruby client library for the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md), enabling Ruby applications to obtain and use SPIFFE identities from a SPIRE agent.
+
+This project aims to be part of the [SPIFFE](https://spiffe.io/) ecosystem. See the [SPIFFE GitHub](https://github.com/spiffe/spiffe) for more information about the SPIFFE project.
+
+## What is this?
+
+This gem allows Ruby applications (including Puppet) to:
+- Fetch X.509 SVIDs (certificates) from SPIRE for mTLS
+- Generate JWT SVIDs for API authentication  
+- Access trust bundles for verification
+- Handle automatic credential rotation
+
+It communicates directly with the SPIRE agent over Unix domain sockets, enabling proper process-based attestation (unlike subprocess-based CLI tools).
+
+## Installation
+
+```bash
+gem install spiffe-workload
+```
+
+For Puppet:
+```bash
+/opt/puppetlabs/puppet/bin/gem install spiffe-workload
+```
+
+## Prerequisites
+
+1. **SPIRE Agent** running with workload API socket accessible
+2. **Workload entry** registered for your application
+
+```bash
+# Verify SPIRE agent is running
+ls -la /run/spire/sockets/agent.sock
+
+# Register your application
+spire-server entry create \
+  -parentID spiffe://example.org/agent/myhost \
+  -spiffeID spiffe://example.org/myapp \
+  -selector unix:uid:$(id -u) \
+  -selector unix:path:/path/to/your/app
+```
+
+## Quick Start
+
+### Fetch X.509 Certificate
+
+```ruby
+require 'spiffe'
+
+client = Spiffe.workload_api_client
+svid = client.x509_svid
+
+puts "My identity: #{svid.spiffe_id}"
+puts "Expires: #{svid.leaf_certificate.not_after}"
+
+client.shutdown
+```
+
+### Fetch JWT Token
+
+```ruby
+require 'spiffe'
+
+client = Spiffe.workload_api_client
+jwt = client.jwt_svid(audience: 'my-service')
+
+puts "Token: #{jwt.token}"
+puts "Expires: #{jwt.expiration}"
+
+client.shutdown
+```
+
+### mTLS HTTP Request
+
+```ruby
+require 'spiffe'
+require 'net/http'
+
+client = Spiffe.workload_api_client
+uri = URI('https://api.example.com/data')
+
+http = Net::HTTP.new(uri.host, uri.port)
+http.use_ssl = true
+http.ssl_context = client.tls_context
+
+response = http.get(uri.path)
+puts response.body
+
+client.shutdown
+```
+
+## Configuration
+
+### Socket Path
+
+Auto-detected from:
+1. `socket_path` parameter
+2. `SPIFFE_ENDPOINT_SOCKET` environment variable  
+3. Default: `/run/spire/sockets/agent.sock`
+
+```ruby
+client = Spiffe.workload_api_client(
+  socket_path: '/var/run/spire/agent.sock'
+)
+```
+
+### Timeout
+
+```ruby
+client = Spiffe.workload_api_client(timeout: 10)
+```
+
+## Puppet Integration
+
+### Custom Function Example
+
+```ruby
+# modules/spiffe/lib/puppet/functions/spiffe_jwt.rb
+Puppet::Functions.create_function(:spiffe_jwt) do
+  def spiffe_jwt(audience)
+    require 'spiffe'
+    client = Spiffe.workload_api_client
+    jwt = client.jwt_svid(audience: audience)
+    jwt.token
+  ensure
+    client&.shutdown
+  end
+end
+```
+
+Use in Puppet manifest:
+
+```puppet
+$token = Deferred('spiffe_jwt', ['vault.example.com'])
+
+file { '/etc/app/token':
+  content => $token,
+  mode    => '0600',
+}
+```
+
+### SPIRE Configuration for Puppet
+
+```yaml
+# Puppet agent workload entry
+selectors:
+  - "unix:uid:0"                                    # Root user
+  - "unix:path:/opt/puppetlabs/puppet/bin/ruby"   # Puppet Ruby binary
+```
+
+## API Reference
+
+### `Spiffe.workload_api_client`
+
+Creates a new Workload API client.
+
+**Parameters:**
+- `socket_path` (String, optional): Path to SPIRE agent socket
+- `timeout` (Integer, optional): Request timeout in seconds
+
+**Returns:** `Spiffe::Workload::Client`
+
+### `Client#x509_svid`
+
+Fetches X.509 SVID.
+
+**Returns:** `Spiffe::Workload::X509SVIDWrapper`
+
+Properties:
+- `spiffe_id` - SPIFFE ID string
+- `leaf_certificate` - OpenSSL::X509::Certificate
+- `certificate_chain` - Array of certificates
+- `private_key` - OpenSSL::PKey::RSA
+- `ttl` - Time to live in seconds
+
+### `Client#jwt_svid(audience:, spiffe_id: nil)`
+
+Fetches JWT SVID.
+
+**Parameters:**
+- `audience` (String|Array): Target audience(s)
+- `spiffe_id` (String, optional): Specific SPIFFE ID
+
+**Returns:** `Spiffe::Workload::JWTSVIDWrapper`
+
+Properties:
+- `spiffe_id` - SPIFFE ID string
+- `token` - JWT token string
+- `expiration` - Expiration time
+- `claims` - Decoded JWT claims
+
+### `Client#tls_context`
+
+Creates OpenSSL context with current SVID.
+
+**Returns:** `OpenSSL::SSL::SSLContext`
+
+### `Client#on_x509_svid_update { |svid| ... }`
+
+Registers callback for SVID rotation.
+
+### `Client#shutdown`
+
+Cleanly shuts down the client.
+
+## Troubleshooting
+
+### "Socket does not exist"
+
+```bash
+# Check SPIRE agent status
+systemctl status spire-agent
+
+# Verify socket location
+sudo find /run /var/run -name "agent.sock" 2>/dev/null
+```
+
+### "No identity issued"
+
+```bash
+# Check workload registration
+spire-server entry show
+
+# Verify selectors match your process
+ps aux | grep your-app
+```
+
+### "Permission denied"
+
+```bash
+# Check socket permissions
+ls -la /run/spire/sockets/agent.sock
+
+# Add user to spire group
+sudo usermod -a -G spire $USER
+```
+
+## Architecture
+
+This gem implements a **client-side library** for the SPIFFE Workload API:
+
+```
+┌────────────────┐
+│  Ruby App      │
+│  (this gem)    │
+└───────┬────────┘
+        │ gRPC over Unix socket
+        ▼
+┌────────────────┐
+│  SPIRE Agent   │
+│  (attests app) │
+└───────┬────────┘
+        │ mTLS
+        ▼
+┌────────────────┐
+│  SPIRE Server  │
+└────────────────┘
+```
+
+**Key points:**
+- No subprocess attestation issues (unlike CLI tools)
+- Direct process attestation by SPIRE
+- Thread-safe credential caching
+- Automatic rotation support
+
+## Contributing
+
+We welcome contributions! This project follows the [SPIFFE contribution guidelines](https://github.com/spiffe/spiffe/blob/main/CONTRIBUTING.md).
+
+### Getting Started
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Ensure tests pass (`bundle exec rspec`)
+5. Ensure code style passes (`bundle exec rubocop`)
+6. Commit with DCO sign-off (`git commit -s -m 'Add amazing feature'`)
+7. Push to your fork (`git push origin feature/amazing-feature`)
+8. Open a Pull Request
+
+### DCO Sign-off
+
+All commits must include a `Signed-off-by` line to certify the [Developer Certificate of Origin (DCO)](DCO):
+
+```bash
+git commit -s -m "Your commit message"
+```
+
+### Similar SPIFFE Projects
+
+- [go-spiffe](https://github.com/spiffe/go-spiffe) - Go implementation
+- [java-spiffe](https://github.com/spiffe/java-spiffe) - Java implementation  
+- [py-spiffe](https://github.com/spiffe/py-spiffe) - Python implementation
+
+See [SPIFFE CONTRIBUTING.md](https://github.com/spiffe/spiffe/blob/main/CONTRIBUTING.md) for more details on contributing to SPIFFE projects.
+
+## Development
+
+### Build from Source
+
+```bash
+git clone https://github.com/halradaideh/spiffe-rubygem.git
+cd spiffe-rubygem
+bundle install
+gem build spiffe-workload.gemspec
+gem install spiffe-workload-*.gem
+```
+
+### Run Tests
+
+```bash
+bundle exec rspec
+```
+
+### Generate Protobuf
+
+```bash
+gem install grpc-tools
+rake generate_protos
+```
+
+## License
+
+Apache License 2.0 - see [LICENSE](LICENSE) file
+
+## Support
+
+- **Issues:** GitHub Issues
+- **SPIFFE Slack:** [slack.spiffe.io](https://slack.spiffe.io)
+- **SPIFFE Docs:** [spiffe.io/docs](https://spiffe.io/docs)
+
+## Version
+
+Current version: 0.2.0
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.

data/lib/spiffe/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Spiffe
+  VERSION = '0.2.0'
+end