nonnative 3.17.0 → 3.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cfb0d140b1fe5374f9d34b8e6accf2fc21ded8f8bba720cea25a166897b2886e
-  data.tar.gz: '0409f68ad074bc744aac66c324d5c5c1d38fa13b2085485562c1c2039435866f'
+  metadata.gz: 011e40916b32666c33c2a0374ee97c3e96d563cf950f5c68e12b8afa7c18e986
+  data.tar.gz: 7b21a33ad8fc14077751e679b66a14523c79c0783004934f55fa61ea5608e477
 SHA512:
-  metadata.gz: f1ba38459a5762fd599ff0a44e5dcc4e2be6caad32f7006fd0d1c4a68c1970652929649021cfa735f64550aa14224c25a0bfafdddc3e210573549249590a31ad
-  data.tar.gz: 2a0ace60a99ad96a97d7cf65e3282ee3fbe6e66b58c222bf101588fde85b52eca517d9e55bd7e8be81fd523c38f03cf415434539b91428a78d71e75802e7e8ad
+  metadata.gz: 0e24fea055ed0e972507bfcb8ebbdf2c604d41e1a6908333a1863f1ba44dd356ea518936d3d6076f73fb37d0c3a9f593b6321ef1392d51d6d1cdf4c145b5ad6d
+  data.tar.gz: ec70302587120b093bb506d5d324821e880b10e406974822f44e1efa7c3fdee29465847eb8f71466ab3806ddd0eb328f2e0788bca28196066c6b3636ce0edb83

data/.circleci/config.yml

@@ -14,10 +14,10 @@ commands:
 executors:
   ruby:
     docker:
-      - image: alexfalkowski/ruby:3.19
+      - image: alexfalkowski/ruby:3.20
   release:
     docker:
-      - image: alexfalkowski/release:8.21
+      - image: alexfalkowski/release:8.22
   alpine:
     docker:
       - image: alpine:latest

data/.claude/skills

@@ -0,0 +1 @@
+../bin/skills

data/AGENTS.md

@@ -111,7 +111,7 @@ of dependencies.
 Public entry point: `lib/nonnative.rb`.
 
 Main API: `configure`, `start`, `stop`, `clear`, `reset`, `pool`,
-`go_argv`, `go_command`.
+`go_argv`, `go_command`, `token`.
 
 Configuration is `Nonnative::Configuration`, built with
 `config.process`, `config.server`, `config.service`, or
@@ -127,6 +127,16 @@ Runners:
 reverse. Readiness and shutdown checks are TCP-only via
 `Nonnative::Port#open?` and `#closed?`.
 
+Token generation: `Nonnative.token(kind:, issuer:, key:, private_key:, expiration:)`
+returns a `Nonnative::Token` whose `generate(aud:, sub:)` produces a signed token for
+authenticating against services under test; it feeds `Nonnative::Header.auth_bearer`.
+Kinds are `jwt` (EdDSA, `kid` header), `paseto` (v4.public, `kid` footer), and `ssh`
+(go-service style raw-Ed25519 `base64(claims).base64(signature)`). All Ed25519 and
+generation-only. `jwt`/`paseto` take a PKCS#8 PEM key; `ssh` takes an OpenSSH-format
+key. PASETO needs system libsodium (via `rbnacl`), required lazily so `require
+'nonnative'` works without it until a PASETO token is generated.
+`Nonnative::Token.http_audience` / `grpc_audience` build the endpoint-scoped `aud`.
+
 ## Cucumber Surface
 
 `lib/nonnative/cucumber.rb` is public compatibility surface. Do not remove or
@@ -192,6 +202,7 @@ Limitations:
 - Readiness/timeouts: `lib/nonnative/port.rb`, `lib/nonnative/timeout.rb`
 - Process lifecycle: `lib/nonnative/process.rb`
 - Go executable command/argv building: `lib/nonnative/go_executable.rb`
+- Token generation: `lib/nonnative/token.rb`, `lib/nonnative/jwt_token.rb`, `lib/nonnative/paseto_token.rb`, `lib/nonnative/ssh_token.rb`, `lib/nonnative/ed25519_key.rb`
 - Proxies: `lib/nonnative/fault_injection_proxy.rb`, `lib/nonnative/socket_pair_factory.rb`
 - Cucumber: `lib/nonnative/cucumber.rb`, `lib/nonnative/startup.rb`, `features/support/env.rb`
 - Config loading: `lib/nonnative/configuration.rb`, `lib/nonnative/configuration_file.rb`, `lib/nonnative/configuration_runner.rb`, `lib/nonnative/configuration_proxy.rb`

data/CLAUDE.md

@@ -0,0 +1,4 @@
+<!-- BEGIN bin claude-init -->
+@AGENTS.md
+@bin/AGENTS.md
+<!-- END bin claude-init -->

data/Gemfile.lock

@@ -1,20 +1,26 @@
 PATH
   remote: .
   specs:
-    nonnative (3.17.0)
+    nonnative (3.19.0)
       concurrent-ruby (>= 1, < 2)
       config (>= 5, < 6)
       cucumber (>= 7, < 12)
       cucumber-cucumber-expressions (< 19)
+      ed25519 (>= 1, < 2)
       get_process_mem (>= 1, < 2)
       grpc (>= 1, < 2)
+      jwt (>= 3, < 4)
+      jwt-eddsa (>= 0, < 1)
       puma (>= 7, < 8)
+      rbnacl (>= 7, < 8)
       rest-client (>= 2, < 3)
       retriable (>= 3, < 4)
       rspec-benchmark (>= 0, < 1)
       rspec-expectations (>= 3, < 4)
       rspec-wait (>= 1, < 2)
+      ruby-paseto (>= 0, < 1)
       sinatra (>= 4, < 5)
+      ssh_data (>= 1, < 2)
 
 GEM
   remote: https://rubygems.org/
@@ -30,7 +36,7 @@ GEM
     config (5.6.1)
       deep_merge (~> 1.2, >= 1.2.1)
       ostruct
-    cucumber (11.1.0)
+    cucumber (11.1.1)
       base64 (~> 0.2)
       builder (~> 3.2)
       cucumber-ci-environment (> 9, < 12)
@@ -59,6 +65,7 @@ GEM
     diff-lcs (1.6.2)
     docile (1.4.1)
     domain_name (0.6.20240107)
+    ed25519 (1.4.0)
     ffi (1.17.4-x86_64-darwin)
     ffi (1.17.4-x86_64-linux-gnu)
     get_process_mem (1.0.0)
@@ -72,29 +79,37 @@ GEM
       rake (~> 13.3)
     googleapis-common-protos-types (1.23.0)
       google-protobuf (~> 4.26)
-    grpc (1.81.1-x86_64-darwin)
+    grpc (1.82.0-x86_64-darwin)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
-    grpc (1.81.1-x86_64-linux-gnu)
+    grpc (1.82.0-x86_64-linux-gnu)
       google-protobuf (>= 3.25, < 5.0)
       googleapis-common-protos-types (~> 1.0)
     http-accept (1.7.0)
     http-cookie (1.1.6)
       domain_name (~> 0.5)
     json (2.20.0)
-    language_server-protocol (3.17.0.5)
+    jwt (3.2.0)
+      base64
+    jwt-eddsa (0.9.0)
+      base64
+      ed25519
+      jwt (>= 2.9.0)
+    language_server-protocol (3.17.0.6)
     lint_roller (1.1.0)
     logger (1.7.0)
     memoist3 (1.0.0)
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2026.0414)
+    mime-types-data (3.2026.0701)
     mini_mime (1.1.5)
+    multi_json (1.15.0)
     multi_test (1.1.0)
     mustermann (3.1.1)
     netrc (0.11.0)
     nio4r (2.7.5)
+    openssl (3.3.3)
     ostruct (0.6.3)
     parallel (2.1.0)
     parser (3.3.11.1)
@@ -114,6 +129,8 @@ GEM
       rack (>= 3.0.0)
     rainbow (3.1.1)
     rake (13.4.2)
+    rbnacl (7.1.2)
+      ffi (~> 1)
     rbs (4.0.3)
       logger
       prism (>= 1.6.0)
@@ -146,7 +163,7 @@ GEM
     rspec-support (3.13.7)
     rspec-wait (1.0.2)
       rspec (>= 3.4)
-    rubocop (1.88.0)
+    rubocop (1.88.1)
       json (~> 2.3)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.1.0)
@@ -157,13 +174,18 @@ GEM
       rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 4.0)
-    rubocop-ast (1.49.1)
+    rubocop-ast (1.50.0)
       parser (>= 3.3.7.2)
       prism (~> 1.7)
     ruby-lsp (0.26.9)
       language_server-protocol (~> 3.17.0)
       prism (>= 1.2, < 2.0)
       rbs (>= 3, < 5)
+    ruby-paseto (0.2.0)
+      multi_json (~> 1.15.0)
+      openssl (~> 3.3)
+      sorbet-runtime
+      zeitwerk
     ruby-progressbar (1.13.0)
     simplecov (0.22.0)
       docile (~> 1.1)
@@ -181,14 +203,17 @@ GEM
       rack-protection (= 4.2.1)
       rack-session (>= 2.0.0, < 3)
       tilt (~> 2.0)
+    sorbet-runtime (0.6.13323)
+    ssh_data (1.3.0)
     sys-uname (1.5.1)
       ffi (~> 1.1)
       memoist3 (~> 1.0.0)
-    tilt (2.7.0)
+    tilt (2.8.0)
     tsort (0.2.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
+    zeitwerk (2.8.2)
 
 PLATFORMS
   x86_64-darwin-21

data/Makefile

@@ -1,3 +1,4 @@
 include bin/build/make/help.mak
 include bin/build/make/ruby.mak
 include bin/build/make/git.mak
+include bin/build/make/claude.mak

data/README.md

@@ -180,6 +180,37 @@ health = Nonnative.grpc_health(
 expect(health.serving?).to eq(true)
 ```
 
+### 🔑 Tokens
+
+`Nonnative.token` builds a signer for authenticating requests against a service under test. You pass the signing parameters directly (parsed from your own configuration); it is not coupled to any service's config format. The generated string is ready for `Nonnative::Header.auth_bearer`.
+
+```ruby
+token = Nonnative.token(
+  kind: 'jwt',
+  issuer: 'iss',
+  key: 'key-1',
+  private_key: 'config/ed25519.pem',
+  expiration: 3600
+)
+
+headers = Nonnative::Header.auth_bearer(
+  token.generate(aud: Nonnative::Token.http_audience('GET', '/v1/things'), sub: 'user-1')
+)
+```
+
+Supported `kind` values (all Ed25519, generation only):
+
+- `jwt`: EdDSA JWT with the key id in the `kid` header. `private_key` is a PKCS#8 PEM file.
+- `paseto`: PASETO v4.public with the key id in a `{"kid":"..."}` footer. `private_key` is a PKCS#8 PEM file. Requires system **libsodium** (via `rbnacl`); it loads lazily, so `require 'nonnative'` works without libsodium until you generate a PASETO token.
+- `ssh`: go-service style `base64(claims).base64(signature)` with a raw Ed25519 signature over `v1` claims. `private_key` is an **OpenSSH-format** key. `issuer` and `sub` are ignored (the subject is the key id).
+
+The audience is endpoint-scoped; build it with the helpers:
+
+```ruby
+Nonnative::Token.http_audience('GET', '/v1/things')        # => "GET /v1/things"
+Nonnative::Token.grpc_audience('/health.v1.Health/Check')  # => "/health.v1.Health/Check"
+```
+
 ### 🔁 Lifecycle strategies (Cucumber integration)
 
 Nonnative ships Cucumber hooks (when loaded) that support these tags/strategies:
@@ -757,6 +788,7 @@ The `fault_injection` proxy allows you to simulate failures by injecting them. W
 Clients connect to the service `host`/`port`, while the proxy forwards traffic to nested `proxy.host`/`proxy.port`.
 
 - `close_all` - Closes the socket as soon as it connects.
+- `reset_peer` - Resets the socket as soon as it connects, so clients observe a TCP reset (`Errno::ECONNRESET`) rather than the graceful close performed by `close_all`.
 - `delay` - Delays traffic on the connection. Defaults to 2 seconds and can be configured through options.
 - `timeout` - Accepts the connection and stalls traffic until reset or stop closes the connection, so clients exercise their own read timeout behavior.
 - `invalid_data` - Forwards client requests unchanged, then corrupts upstream responses before they reach the client.
@@ -770,6 +802,7 @@ name = 'name of service in configuration'
 service = Nonnative.pool.service_by_name(name)
 
 service.proxy.close_all # To use close_all.
+service.proxy.reset_peer # To reset (RST) client connections.
 service.proxy.timeout # To stall traffic until reset or stop.
 service.proxy.reset # To reset it back to a good state.
 ```
@@ -778,6 +811,7 @@ Use the Cucumber proxy steps:
 
 ```cucumber
 Given I set the proxy for service 'service_1' to 'close_all'
+Given I set the proxy for service 'service_1' to 'reset_peer'
 Given I set the proxy for service 'service_1' to 'timeout'
 Then I should reset the proxy for service 'service_1'
 ```

data/lib/nonnative/cucumber.rb

@@ -55,6 +55,7 @@ module Nonnative
     module ProxySteps
       PROXY_OPERATIONS = {
         'close_all' => :close_all,
+        'reset_peer' => :reset_peer,
         'delay' => :delay,
         'timeout' => :timeout,
         'invalid_data' => :invalid_data,

data/lib/nonnative/ed25519_key.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Loads an Ed25519 private key from a PEM file for signing tokens.
+  #
+  # Verifiers such as go-service use Ed25519 keys encoded as PKCS#8 PEM. This reads the PEM once and
+  # exposes it in the shapes the token backends need: the raw PEM for {Nonnative::PasetoToken} and the
+  # 32-byte seed for {Nonnative::JwtToken}.
+  #
+  # @example
+  #   key = Nonnative::Ed25519Key.new('config/ed25519.pem')
+  #   key.pem   # => "-----BEGIN PRIVATE KEY-----\n..."
+  #   key.seed  # => 32-byte binary String
+  class Ed25519Key
+    # @param path [String] path to a PKCS#8 Ed25519 private key PEM file
+    def initialize(path)
+      @pem = File.read(path)
+    end
+
+    # @return [String] the PEM contents (PKCS#8 Ed25519 private key)
+    attr_reader :pem
+
+    # Extracts the raw 32-byte Ed25519 seed from the PEM.
+    #
+    # @return [String] the raw 32-byte Ed25519 seed
+    def seed
+      OpenSSL::PKey.read(@pem).raw_private_key
+    end
+  end
+end

data/lib/nonnative/fault_injection_proxy.rb

@@ -10,6 +10,7 @@ module Nonnative
   # This class exposes a small public control surface for tests:
   #
   # - {#close_all}: close connections immediately on accept
+  # - {#reset_peer}: reset connections immediately on accept (TCP RST rather than a graceful close)
   # - {#delay}: delay reads by a configured duration (default: 2 seconds)
   # - {#timeout}: accept connections and keep them silent until clients time out
   # - {#invalid_data}: forward requests unchanged and mutate upstream responses before they reach clients
@@ -99,6 +100,16 @@ module Nonnative
       apply_state :close_all
     end
 
+    # Forces new connections to be reset immediately.
+    #
+    # Unlike {#close_all}, which closes the socket gracefully (FIN), this closes the accepted socket
+    # with a zero linger timeout so clients observe a TCP reset (`Errno::ECONNRESET`).
+    #
+    # @return [void]
+    def reset_peer
+      apply_state :reset_peer
+    end
+
     # Delays reads before forwarding.
     #
     # The delay duration is controlled by `service.proxy.options[:delay]` and defaults to 2 seconds.

data/lib/nonnative/jwt_token.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Generates Ed25519 (EdDSA) JWT tokens for authenticating against services under test.
+  #
+  # The key id is set in the JWT `kid` header, and the claims match the common
+  # iss/aud/sub/iat/nbf/exp/jti set expected by verifiers such as go-service.
+  #
+  # @example
+  #   jwt = Nonnative::JwtToken.new(issuer: 'iss', key: 'key-1', private_key: 'config/ed25519.pem', expiration: 3600)
+  #   jwt.generate(aud: 'GET /v1/things', sub: 'user-1')
+  #
+  # @see https://github.com/jwt/ruby-jwt-eddsa jwt-eddsa
+  class JwtToken
+    # @param issuer [String] the `iss` claim
+    # @param key [String] the key id set in the JWT `kid` header
+    # @param private_key [String] path to a PKCS#8 Ed25519 private key PEM file
+    # @param expiration [Integer] token lifetime in seconds (drives `exp`)
+    def initialize(issuer:, key:, private_key:, expiration:)
+      @issuer = issuer
+      @key = key
+      @ed25519 = Nonnative::Ed25519Key.new(private_key)
+      @expiration = expiration
+    end
+
+    # Generates a signed EdDSA JWT.
+    #
+    # @param aud [String] the `aud` claim (for example `"GET /v1/things"` or a gRPC full method)
+    # @param sub [String] the `sub` claim
+    # @return [String] the signed JWT
+    def generate(aud:, sub:)
+      now = Time.now.to_i
+      payload = {
+        iss: @issuer,
+        aud: aud,
+        sub: sub,
+        iat: now,
+        nbf: now,
+        exp: now + @expiration,
+        jti: SecureRandom.uuid
+      }
+
+      JWT.encode(payload, Ed25519::SigningKey.new(@ed25519.seed), 'EdDSA', { kid: @key })
+    end
+  end
+end

data/lib/nonnative/paseto_token.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Generates Ed25519 PASETO v4.public tokens for authenticating against services under test.
+  #
+  # The key id is carried in a JSON footer (`{"kid":"..."}`), and the claims match the common
+  # iss/aud/sub/iat/nbf/exp/jti set expected by verifiers such as go-service. The signing library is
+  # required lazily so that requiring `nonnative` does not depend on `rbnacl`/libsodium being present.
+  #
+  # @example
+  #   paseto = Nonnative::PasetoToken.new(issuer: 'iss', key: 'key-1', private_key: 'config/ed25519.pem', expiration: 3600)
+  #   paseto.generate(aud: 'GET /v1/things', sub: 'user-1')
+  #
+  # @see https://github.com/bannable/paseto ruby-paseto
+  class PasetoToken
+    # @param issuer [String] the `iss` claim
+    # @param key [String] the key id carried in the `kid` footer
+    # @param private_key [String] path to a PKCS#8 Ed25519 private key PEM file
+    # @param expiration [Integer] token lifetime in seconds (drives `exp`)
+    def initialize(issuer:, key:, private_key:, expiration:)
+      @issuer = issuer
+      @key = key
+      @ed25519 = Nonnative::Ed25519Key.new(private_key)
+      @expiration = expiration
+    end
+
+    # Generates a signed PASETO v4.public token.
+    #
+    # @param aud [String] the `aud` claim (for example `"GET /v1/things"` or a gRPC full method)
+    # @param sub [String] the `sub` claim
+    # @return [String] the signed PASETO token
+    def generate(aud:, sub:)
+      load_dependencies!
+
+      now = Time.now.utc
+      claims = {
+        'iss' => @issuer,
+        'aud' => aud,
+        'sub' => sub,
+        'iat' => now.iso8601,
+        'nbf' => now.iso8601,
+        'exp' => (now + @expiration).iso8601,
+        'jti' => SecureRandom.uuid
+      }
+
+      Paseto::V4::Public.new(@ed25519.pem).encode!(claims, footer: { 'kid' => @key }.to_json)
+    end
+
+    private
+
+    # Loads the PASETO signing libraries lazily and raises a clear error if they are unavailable.
+    # rbnacl loads system libsodium at runtime, which the gemspec cannot guarantee, so requiring it
+    # here keeps `require 'nonnative'` working without libsodium for consumers that do not use PASETO.
+    def load_dependencies!
+      require 'rbnacl'
+      require 'paseto'
+    rescue LoadError => e
+      raise Nonnative::Error, "PASETO token generation requires libsodium and the rbnacl and ruby-paseto gems (#{e.message})"
+    end
+  end
+end

data/lib/nonnative/reset_peer_socket_pair.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Socket-pair variant used by the fault-injection proxy to simulate an abrupt connection reset.
+  #
+  # When active, the proxy accepts a TCP connection and closes it with a zero linger timeout, so the
+  # kernel sends a TCP RST instead of a graceful FIN. Clients observe a reset ("connection reset by
+  # peer", `Errno::ECONNRESET`) rather than a clean end-of-stream, which is distinct from the graceful
+  # close performed by {Nonnative::CloseAllSocketPair}.
+  #
+  # This behavior is enabled by calling {Nonnative::FaultInjectionProxy#reset_peer}.
+  #
+  # @see Nonnative::FaultInjectionProxy
+  # @see Nonnative::SocketPairFactory
+  # @see Nonnative::SocketPair
+  # @see Nonnative::CloseAllSocketPair
+  class ResetPeerSocketPair < SocketPair
+    # Resets the accepted socket by closing it with a zero linger timeout, forcing a TCP RST.
+    #
+    # @param local_socket [TCPSocket] the accepted client socket
+    # @return [void]
+    def connect(local_socket)
+      Nonnative.logger.info "resetting socket '#{local_socket.inspect}' for 'reset_peer' pair"
+
+      local_socket.setsockopt(Socket::Option.linger(true, 0))
+      local_socket.close
+    end
+  end
+end

data/lib/nonnative/socket_pair_factory.rb

@@ -9,6 +9,7 @@ module Nonnative
   # Proxy states are mapped as follows:
   # - `:none` (or any unknown value) -> {Nonnative::SocketPair} (pass-through)
   # - `:close_all` -> {Nonnative::CloseAllSocketPair}
+  # - `:reset_peer` -> {Nonnative::ResetPeerSocketPair}
   # - `:delay` -> {Nonnative::DelaySocketPair}
   # - `:timeout` -> {Nonnative::TimeoutSocketPair}
   # - `:invalid_data` -> {Nonnative::InvalidDataSocketPair}
@@ -16,6 +17,7 @@ module Nonnative
   # @see Nonnative::FaultInjectionProxy
   # @see Nonnative::SocketPair
   # @see Nonnative::CloseAllSocketPair
+  # @see Nonnative::ResetPeerSocketPair
   # @see Nonnative::DelaySocketPair
   # @see Nonnative::TimeoutSocketPair
   # @see Nonnative::InvalidDataSocketPair
@@ -23,13 +25,15 @@ module Nonnative
     class << self
       # Creates a socket-pair instance for the given proxy state.
       #
-      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:delay`, `:timeout`, `:invalid_data`)
+      # @param kind [Symbol] proxy state (e.g. `:none`, `:close_all`, `:reset_peer`, `:delay`, `:timeout`, `:invalid_data`)
       # @param proxy [Nonnative::ConfigurationProxy] proxy configuration (host/port/options)
       # @return [Nonnative::SocketPair] a socket-pair implementation instance
       def create(kind, proxy)
         pair = case kind
                when :close_all
                  CloseAllSocketPair
+               when :reset_peer
+                 ResetPeerSocketPair
                when :delay
                  DelaySocketPair
                when :timeout

data/lib/nonnative/ssh_token.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Generates go-service style SSH tokens for authenticating against services under test.
+  #
+  # Despite the name this is not an SSH protocol signature: the key is loaded from an OpenSSH-format
+  # Ed25519 private key and used as a raw Ed25519 key, matching go-service's SSH token scheme. The token
+  # is `<base64(claims)>.<base64(signature)>`, where the signature is a raw Ed25519 signature over the
+  # claims JSON. Claims are ver/kid/sub/aud/iat/exp, with `sub == kid == key` and `iat`/`exp` in Unix
+  # nanoseconds. `issuer` and `sub` are accepted for a uniform interface with the other kinds but unused:
+  # SSH tokens have no issuer, and the subject is always the key id.
+  #
+  # @example
+  #   ssh = Nonnative::SshToken.new(key: 'key-1', private_key: 'config/id_ed25519', expiration: 3600)
+  #   ssh.generate(aud: 'GET /v1/things', sub: 'user-1')
+  #
+  # @see https://github.com/github/ssh_data ssh_data
+  class SshToken
+    # The go-service SSH token format version.
+    TOKEN_VERSION = 'v1'
+
+    # @param key [String] the key id; also used as the subject
+    # @param private_key [String] path to an OpenSSH-format Ed25519 private key file
+    # @param expiration [Integer] token lifetime in seconds (drives `exp`)
+    def initialize(key:, private_key:, expiration:, **)
+      @key = key
+      @private_key = private_key
+      @expiration = expiration
+    end
+
+    # Generates a signed SSH token.
+    #
+    # @param aud [String] the `aud` claim (for example `"GET /v1/things"` or a gRPC full method)
+    # @return [String] the token, `"<base64(claims)>.<base64(signature)>"`
+    def generate(aud:, **)
+      now = Time.now
+      issued_at = (now.to_i * 1_000_000_000) + now.nsec
+      claims = {
+        ver: TOKEN_VERSION,
+        kid: @key,
+        sub: @key,
+        aud: aud,
+        iat: issued_at,
+        exp: issued_at + (@expiration * 1_000_000_000)
+      }.to_json
+
+      signature = Ed25519::SigningKey.new(seed).sign(claims)
+
+      "#{Base64.strict_encode64(claims)}.#{Base64.strict_encode64(signature)}"
+    end
+
+    private
+
+    def seed
+      SSHData::PrivateKey.parse_openssh(File.read(@private_key)).first.sk[0, 32]
+    end
+  end
+end

data/lib/nonnative/token.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Nonnative
+  # Builds signed tokens (JWT, PASETO, or SSH) for authenticating against services under test.
+  #
+  # The consumer passes in the signing parameters they parsed from their own configuration; this class
+  # is not coupled to any particular service's configuration format. The generated token string is
+  # ready to pass to {Nonnative::Header.auth_bearer}.
+  #
+  # @example JWT
+  #   token = Nonnative::Token.new(kind: 'jwt', issuer: 'iss', key: 'key-1',
+  #                                private_key: 'config/ed25519.pem', expiration: 3600)
+  #   header = Nonnative::Header.auth_bearer(token.generate(aud: 'GET /v1/things', sub: 'user-1'))
+  #
+  # @example PASETO
+  #   token = Nonnative::Token.new(kind: 'paseto', issuer: 'iss', key: 'key-1',
+  #                                private_key: 'config/ed25519.pem', expiration: 3600)
+  #   token.generate(aud: Nonnative::Token.grpc_audience('/health.v1.Health/Check'), sub: 'user-1')
+  #
+  # @see Nonnative::Header.auth_bearer
+  class Token
+    # Supported token kinds mapped to their implementation.
+    KINDS = { 'jwt' => Nonnative::JwtToken, 'paseto' => Nonnative::PasetoToken, 'ssh' => Nonnative::SshToken }.freeze
+
+    class << self
+      # Builds the audience string for an HTTP endpoint.
+      #
+      # @param method [String] HTTP method (for example `"GET"`)
+      # @param path [String] request path (for example `"/v1/things"`)
+      # @return [String] the audience string (for example `"GET /v1/things"`)
+      def http_audience(method, path)
+        "#{method} #{path}"
+      end
+
+      # Builds the audience string for a gRPC endpoint.
+      #
+      # @param full_method [String] the gRPC full method (for example `"/health.v1.Health/Check"`)
+      # @return [String] the audience string
+      def grpc_audience(full_method)
+        full_method
+      end
+    end
+
+    # @param kind [String] token kind, one of `"jwt"`, `"paseto"`, or `"ssh"`
+    # @param issuer [String] the `iss` claim (unused by the `ssh` kind)
+    # @param key [String] the key id (JWT `kid` header, PASETO `kid` footer, or SSH `kid` claim)
+    # @param private_key [String] path to the Ed25519 private key file (PKCS#8 PEM for `jwt`/`paseto`, OpenSSH format for `ssh`)
+    # @param expiration [Integer] token lifetime in seconds (drives `exp`)
+    # @raise [ArgumentError] if the kind is not supported
+    def initialize(kind:, issuer:, key:, private_key:, expiration:)
+      klass = KINDS.fetch(kind) { raise ArgumentError, "Unsupported token kind '#{kind}'" }
+      @token = klass.new(issuer: issuer, key: key, private_key: private_key, expiration: expiration)
+    end
+
+    # Generates a signed token.
+    #
+    # @param aud [String] the `aud` claim
+    # @param sub [String] the `sub` claim
+    # @return [String] the signed token
+    def generate(aud:, sub:)
+      @token.generate(aud: aud, sub: sub)
+    end
+  end
+end

data/lib/nonnative/version.rb

@@ -4,5 +4,5 @@ module Nonnative
   # The current gem version.
   #
   # @return [String]
-  VERSION = '3.17.0'
+  VERSION = '3.19.0'
 end

data/lib/nonnative.rb

@@ -49,6 +49,10 @@ require 'open3'
 require 'securerandom'
 require 'shellwords'
 require 'uri'
+require 'openssl'
+require 'json'
+require 'time'
+require 'singleton' # ruby-paseto depends on this stdlib, which Ruby no longer auto-loads
 
 require 'grpc'
 require 'grpc/health/v1/health_services_pb'
@@ -64,6 +68,11 @@ require 'rspec/wait'
 require 'puma'
 require 'puma/server'
 
+# jwt-eddsa (with the ed25519 gem) and ssh_data are pure Ruby and need no system library, so they load
+# here. PASETO's rbnacl needs system libsodium, so Nonnative::PasetoToken requires it lazily instead.
+require 'jwt/eddsa'
+require 'ssh_data'
+
 require 'nonnative/version'
 require 'nonnative/error'
 require 'nonnative/start_error'
@@ -102,6 +111,7 @@ require 'nonnative/no_proxy'
 require 'nonnative/fault_injection_proxy'
 require 'nonnative/socket_pair'
 require 'nonnative/close_all_socket_pair'
+require 'nonnative/reset_peer_socket_pair'
 require 'nonnative/delay_socket_pair'
 require 'nonnative/timeout_socket_pair'
 require 'nonnative/invalid_data_socket_pair'
@@ -109,6 +119,11 @@ require 'nonnative/socket_pair_factory'
 require 'nonnative/go_executable'
 require 'nonnative/cucumber'
 require 'nonnative/header'
+require 'nonnative/ed25519_key'
+require 'nonnative/jwt_token'
+require 'nonnative/paseto_token'
+require 'nonnative/ssh_token'
+require 'nonnative/token'
 
 # The main namespace for the gem.
 #
@@ -194,6 +209,23 @@ module Nonnative
       Nonnative::GoExecutable.new(tools, exec, output).argv(cmd, *params)
     end
 
+    # Builds a token generator for authenticating against a service under test.
+    #
+    # The signing parameters are passed in directly; this is not coupled to any service's
+    # configuration format. The generated token string is ready for {Nonnative::Header.auth_bearer}.
+    #
+    # @param kind [String] token kind, one of `"jwt"`, `"paseto"`, or `"ssh"`
+    # @param issuer [String] the `iss` claim (unused by the `ssh` kind)
+    # @param key [String] the key id (JWT `kid` header, PASETO `kid` footer, or SSH `kid` claim)
+    # @param private_key [String] path to the Ed25519 private key file (PKCS#8 PEM for `jwt`/`paseto`, OpenSSH format for `ssh`)
+    # @param expiration [Integer] token lifetime in seconds (drives `exp`)
+    # @return [Nonnative::Token]
+    #
+    # @example
+    #   token = Nonnative.token(kind: 'jwt', issuer: 'iss', key: 'key-1', private_key: 'config/ed25519.pem', expiration: 3600)
+    #   Nonnative::Header.auth_bearer(token.generate(aud: 'GET /v1/things', sub: 'user-1'))
+    def token(kind:, issuer:, key:, private_key:, expiration:) = Nonnative::Token.new(kind:, issuer:, key:, private_key:, expiration:)
+
     # Returns an HTTP client for common health/readiness endpoints.
     #
     # @return [Nonnative::Observability]

data/nonnative.gemspec

@@ -28,13 +28,19 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'config', '>= 5', '< 6'
   spec.add_dependency 'cucumber', '>= 7', '< 12'
   spec.add_dependency 'cucumber-cucumber-expressions', '< 19'
+  spec.add_dependency 'ed25519', '>= 1', '< 2'
   spec.add_dependency 'get_process_mem', '>= 1', '< 2'
   spec.add_dependency 'grpc', '>= 1', '< 2'
+  spec.add_dependency 'jwt', '>= 3', '< 4'
+  spec.add_dependency 'jwt-eddsa', '>= 0', '< 1'
   spec.add_dependency 'puma', '>= 7', '< 8'
+  spec.add_dependency 'rbnacl', '>= 7', '< 8'
   spec.add_dependency 'rest-client', '>= 2', '< 3'
   spec.add_dependency 'retriable', '>= 3', '< 4'
   spec.add_dependency 'rspec-benchmark', '>= 0', '< 1'
   spec.add_dependency 'rspec-expectations', '>= 3', '< 4'
   spec.add_dependency 'rspec-wait', '>= 1', '< 2'
+  spec.add_dependency 'ruby-paseto', '>= 0', '< 1'
   spec.add_dependency 'sinatra', '>= 4', '< 5'
+  spec.add_dependency 'ssh_data', '>= 1', '< 2'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nonnative
 version: !ruby/object:Gem::Version
-  version: 3.17.0
+  version: 3.19.0
 platform: ruby
 authors:
 - Alejandro Falkowski
@@ -83,6 +83,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '19'
+- !ruby/object:Gem::Dependency
+  name: ed25519
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: get_process_mem
   requirement: !ruby/object:Gem::Requirement
@@ -123,6 +143,46 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: jwt-eddsa
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: puma
   requirement: !ruby/object:Gem::Requirement
@@ -143,6 +203,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '8'
+- !ruby/object:Gem::Dependency
+  name: rbnacl
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
@@ -243,6 +323,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
+- !ruby/object:Gem::Dependency
+  name: ruby-paseto
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1'
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
@@ -263,6 +363,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
+- !ruby/object:Gem::Dependency
+  name: ssh_data
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 description: Starts OS processes, in-process Ruby servers, and proxy-only services
   with TCP readiness checks and fault-injection proxies.
 email:
@@ -272,6 +392,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".circleci/config.yml"
+- ".claude/skills"
 - ".codecov.yml"
 - ".config/cucumber.yml"
 - ".editorconfig"
@@ -281,6 +402,7 @@ files:
 - ".goreleaser.yml"
 - ".rubocop.yml"
 - AGENTS.md
+- CLAUDE.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -299,6 +421,7 @@ files:
 - lib/nonnative/configuration_service_readiness.rb
 - lib/nonnative/cucumber.rb
 - lib/nonnative/delay_socket_pair.rb
+- lib/nonnative/ed25519_key.rb
 - lib/nonnative/error.rb
 - lib/nonnative/fault_injection_proxy.rb
 - lib/nonnative/go_executable.rb
@@ -312,26 +435,31 @@ files:
 - lib/nonnative/http_server.rb
 - lib/nonnative/http_service.rb
 - lib/nonnative/invalid_data_socket_pair.rb
+- lib/nonnative/jwt_token.rb
 - lib/nonnative/no_proxy.rb
 - lib/nonnative/not_found_error.rb
 - lib/nonnative/observability.rb
+- lib/nonnative/paseto_token.rb
 - lib/nonnative/pool.rb
 - lib/nonnative/port.rb
 - lib/nonnative/ports.rb
 - lib/nonnative/process.rb
 - lib/nonnative/proxy.rb
 - lib/nonnative/proxy_factory.rb
+- lib/nonnative/reset_peer_socket_pair.rb
 - lib/nonnative/runner.rb
 - lib/nonnative/server.rb
 - lib/nonnative/service.rb
 - lib/nonnative/socket_pair.rb
 - lib/nonnative/socket_pair_factory.rb
+- lib/nonnative/ssh_token.rb
 - lib/nonnative/start_error.rb
 - lib/nonnative/startup.rb
 - lib/nonnative/stop_error.rb
 - lib/nonnative/tcp_probe.rb
 - lib/nonnative/timeout.rb
 - lib/nonnative/timeout_socket_pair.rb
+- lib/nonnative/token.rb
 - lib/nonnative/version.rb
 - nonnative.gemspec
 homepage: https://github.com/alexfalkowski/nonnative