usps-jwt_auth 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be13d7639636f1abce28a82c032ea04883808bec8bb3925060f3f2071e1bf3ef
-  data.tar.gz: 8486bf2584dbcc901f00e17ef059ec3125db036f76f7c81080d68125177f50b0
+  metadata.gz: a248993ec7c0ad7e97d4bfcb7e89302f3366f7c3fd95c122f71d116f9c541bcf
+  data.tar.gz: ef4e072d124dd0f398fbb80202523c3a99b5a25220c48dfeaf27c8a732800259
 SHA512:
-  metadata.gz: 2a8d5e69bd26ed1a65da6f4c7beb907aa570e7ae1942c4f256fee3c42e8f39bdcbc938018b626825ac77e5d50a64d6b994534361acfac8fda025c2681f39d4a3
-  data.tar.gz: 5fc08818ac1c3cd4b13b1005f294d6bfd0d3837fc03fd0609c74235cf9de706d5311fc01aaa44cb3cda34edcad22636f56807f6a0ac7d5e7e7b5c79a43048f5f
+  metadata.gz: f38759de429b850a32caa02b412fbbc644dca520f74422bef274fe30dc0f709b272057b81aaf411afce3a7c979bc550e1bb1531dbd228f0185fb6e12bff6ea73
+  data.tar.gz: 57c98a347480941fbf0f7c88a27252228eb0198d91ffb11f7259b5abf5dfb79f50b4c6db7113dbbe5fe5748ffa7a90a4fdc172268123741d6b27faec0023124c

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    usps-jwt_auth (1.1.0)
+    usps-jwt_auth (1.2.0)
       activesupport (~> 8.0)
       colorize (~> 1.1)
       fileutils (~> 1.7)

data/README.md

@@ -39,11 +39,35 @@ Usps::JwtAuth.configure do |config|
   config.issuer_base = 'usps:1'    # ENV['JWT_ISSUER_BASE'] # 'usps:1'
   config.issuers     = ['admin:1'] # ENV['JWT_ISSUERS']     # []
 
+  # Base URL of the shared public-key store (see "Public key resolution").
+  config.public_keys_url = 'https://keys.aws.usps.org' # ENV['JWT_PUBLIC_KEYS_URL'] # nil
+
+  # Optional. Called as `publisher.call(fingerprint, pem)` when an issuer writes a
+  # new public key, so it can be pushed to the shared store. Defaults to nil (no-op).
+  config.publisher = ->(fingerprint, pem) { S3.put("#{fingerprint}.pub", pem) }
+
   config.is_admin = ->(user) { Pundit.policy(user, :admin).admin? }
   config.find_member = ->(certificate) { Members::Member.find(certificate) }
 end
 ```
 
+## Public key resolution
+
+A token names its signing key by an SSH SHA256 fingerprint (the `key` claim),
+which is content-addressed — a fingerprint maps to exactly one key, forever.
+
+When decoding, the gem first looks for `<fingerprint>.pub` under `public_keys_path`
+(the local cache). On a miss, if `public_keys_url` is set, it fetches
+`<public_keys_url>/<fingerprint>.pub` once, **verifies the fetched key reproduces
+the fingerprint** (so the store is an untrusted cache that cannot forge keys),
+caches it under `public_keys_path`, and uses it. With no `public_keys_url` set,
+only locally cached keys are used.
+
+Issuers publish keys to that same store: set `publisher` and the gem pushes each
+newly written public key on encode. Because keys are content-addressed, rotation
+needs no consumer changes — a new key is published and consumers fetch it on first
+sight.
+
 ## Usage
 
 ```ruby

data/lib/usps/jwt_auth/config.rb

@@ -7,7 +7,8 @@ module Usps
     class Config
       REQUIRED_OPTIONS = %i[audience is_admin find_member].freeze
 
-      attr_accessor :key_size, :algorithm, :issuer_base, :issuers, :audience, :is_admin, :find_member
+      attr_accessor :key_size, :algorithm, :issuer_base, :issuers, :audience, :is_admin, :find_member,
+                    :public_keys_url, :publisher
       attr_reader :environment
 
       def initialize
@@ -19,6 +20,11 @@ module Usps
         @issuer_base = ENV.fetch('JWT_ISSUER_BASE', 'usps:1')
         @issuers = ENV.fetch('JWT_ISSUERS', [])
         @audience = ENV.fetch('JWT_AUDIENCE', nil)
+        # Base URL of the shared public-key store (CloudFront). Consumers fetch
+        # "<public_keys_url>/<fingerprint>.pub" on a local cache miss. nil disables fetching.
+        # `publisher` (defaults to nil) is an optional callable invoked as
+        # publisher.call(fingerprint, pem) when an issuer writes a new public key.
+        @public_keys_url = ENV.fetch('JWT_PUBLIC_KEYS_URL', nil)
 
         yield self if block_given? # Also support setting options on initialize
       end

data/lib/usps/jwt_auth/decode.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require 'net/http'
+require 'uri'
+require 'fileutils'
+
 module Usps
   module JwtAuth
     # Decode and validate data from a JWT
@@ -32,12 +36,57 @@ module Usps
 
     private
 
+      # Resolve the public key the token names by its fingerprint. Fast path is the local
+      # cache; on a miss we fetch it once from the shared store and cache it permanently
+      # (a fingerprint maps to one key forever). The store is treated as untrusted — see
+      # cache_verified_key — so a tampered key can never be trusted.
       def public_key(token)
-        OpenSSL::PKey::RSA.new(File.read("#{JwtAuth.config.public_keys_path}/#{fingerprint(token)}.pub"))
+        fingerprint = fingerprint(token)
+        OpenSSL::PKey::RSA.new(File.read(cache_path(fingerprint)))
       rescue Errno::ENOENT
-        # No public key matches the token's fingerprint (e.g. a stale token after key rotation),
-        # so the token cannot be verified and is treated as invalid.
-        raise JWT::VerificationError, 'No public key for token fingerprint'
+        fetch_public_key(fingerprint)
+      end
+
+      def cache_path(fingerprint)
+        "#{JwtAuth.config.public_keys_path}/#{fingerprint}.pub"
+      end
+
+      # Fetch the named key from the shared store, verify it, and cache it locally.
+      def fetch_public_key(fingerprint)
+        url = JwtAuth.config.public_keys_url
+        # No store configured, so a missing local key cannot be resolved (e.g. a stale token
+        # after rotation): the token cannot be verified and is treated as invalid.
+        raise JWT::VerificationError, 'No public key for token fingerprint' unless url
+
+        pem = http_get("#{url}/#{fingerprint}.pub")
+        cache_verified_key(fingerprint, pem)
+      rescue JWT::VerificationError
+        raise
+      rescue StandardError => e
+        raise JWT::VerificationError, "Could not fetch public key for token fingerprint: #{e.message}"
+      end
+
+      # Trust nothing the store returns until the key reproduces the fingerprint the token
+      # names. Without this check a compromised store/CDN could serve an attacker key under a
+      # known fingerprint and forge valid tokens. Only verified keys are written to the cache.
+      def cache_verified_key(fingerprint, pem)
+        key = OpenSSL::PKey::RSA.new(pem)
+        unless Fingerprint.for(key.public_key) == fingerprint
+          raise JWT::VerificationError, 'Fetched public key does not match token fingerprint'
+        end
+
+        path = cache_path(fingerprint)
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, pem)
+        key
+      end
+
+      def http_get(url)
+        uri = URI.parse(url)
+        response = Net::HTTP.get_response(uri)
+        raise "HTTP #{response.code} for #{url}" unless response.is_a?(Net::HTTPSuccess)
+
+        response.body
       end
 
       def fingerprint(token)

data/lib/usps/jwt_auth/encode.rb

@@ -30,34 +30,14 @@ module Usps
         @public_key ||= private_key.public_key
       end
 
-      # OpenSSH-style SHA256 key fingerprint: base64url(SHA256(ssh-rsa wire blob)),
-      # i.e. the value `ssh-keygen -lf` prints as `SHA256:...`. This matches the key
-      # filenames and `key` claim that the consuming apps already recognize.
+      # The OpenSSH-style SHA256 fingerprint of this key — see Fingerprint. Stamped onto
+      # the token's `key` claim so consumers can resolve and verify the matching public key.
       def fingerprint
-        digest = OpenSSL::Digest::SHA256.digest(ssh_public_blob)
-        [digest].pack('m0').tr('+/', '-_').delete('=')
+        Fingerprint.for(public_key)
       end
 
     private
 
-      # Public key in the OpenSSH wire format: string('ssh-rsa') + mpint(e) + mpint(n).
-      def ssh_public_blob
-        ssh_string('ssh-rsa') + ssh_mpint(public_key.e) + ssh_mpint(public_key.n)
-      end
-
-      # SSH "string": 4-byte big-endian length prefix followed by the bytes.
-      def ssh_string(bytes)
-        [bytes.bytesize].pack('N') + bytes.b
-      end
-
-      # SSH "mpint": a length-prefixed big-endian integer; a leading zero byte is
-      # prepended when the high bit is set so the value stays non-negative.
-      def ssh_mpint(num)
-        bytes = num.to_s(2)
-        bytes = "\x00".b + bytes if bytes.bytes.first && bytes.bytes.first >= 0x80
-        ssh_string(bytes)
-      end
-
       def expires_at
         ::Time.now.to_i + @expiration_time
       end
@@ -94,6 +74,14 @@ module Usps
 
         File.open(path, 'w+') { |f| f.puts(public_key) }
         ::FileUtils.chmod(0o644, path)
+        publish_public_key
+      end
+
+      # Push the freshly written public key to the shared store, if a publisher is wired
+      # in, so consumers can resolve this fingerprint without a manual sync. Re-publishing
+      # an existing fingerprint is a harmless no-op for the store.
+      def publish_public_key
+        JwtAuth.config.publisher&.call(fingerprint, public_key.to_pem)
       end
 
       def generate_private_key

data/lib/usps/jwt_auth/fingerprint.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'openssl'
+
+module Usps
+  module JwtAuth
+    # OpenSSH-style SHA256 key fingerprint: base64url(SHA256(ssh-rsa wire blob)),
+    # i.e. the value `ssh-keygen -lf` prints as `SHA256:...`. This is the identifier
+    # used for key filenames and the JWT `key` claim, and it is content-addressed: a
+    # given fingerprint maps to exactly one public key, forever. Encode stamps it onto
+    # tokens; Decode uses it to verify a fetched key really is the key the token names.
+    module Fingerprint
+      class << self
+        def for(public_key)
+          digest = OpenSSL::Digest::SHA256.digest(ssh_public_blob(public_key))
+          [digest].pack('m0').tr('+/', '-_').delete('=')
+        end
+
+      private
+
+        # Public key in the OpenSSH wire format: string('ssh-rsa') + mpint(e) + mpint(n).
+        def ssh_public_blob(public_key)
+          ssh_string('ssh-rsa') + ssh_mpint(public_key.e) + ssh_mpint(public_key.n)
+        end
+
+        # SSH "string": 4-byte big-endian length prefix followed by the bytes.
+        def ssh_string(bytes)
+          [bytes.bytesize].pack('N') + bytes.b
+        end
+
+        # SSH "mpint": a length-prefixed big-endian integer; a leading zero byte is
+        # prepended when the high bit is set so the value stays non-negative.
+        def ssh_mpint(num)
+          bytes = num.to_s(2)
+          bytes = "\x00".b + bytes if bytes.bytes.first && bytes.bytes.first >= 0x80
+          ssh_string(bytes)
+        end
+      end
+    end
+  end
+end

data/lib/usps/jwt_auth/version.rb

@@ -2,6 +2,6 @@
 
 module Usps
   module JwtAuth
-    VERSION = '1.1.0'
+    VERSION = '1.2.0'
   end
 end

data/lib/usps/jwt_auth.rb

@@ -33,6 +33,7 @@ end
 # Internal requires
 require_relative 'jwt_auth/version'
 require_relative 'jwt_auth/config'
+require_relative 'jwt_auth/fingerprint'
 require_relative 'jwt_auth/encode'
 require_relative 'jwt_auth/decode'
 require_relative 'jwt_auth/incorrect_login'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: usps-jwt_auth
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Julian Fiander
@@ -86,6 +86,7 @@ files:
 - lib/usps/jwt_auth/config.rb
 - lib/usps/jwt_auth/decode.rb
 - lib/usps/jwt_auth/encode.rb
+- lib/usps/jwt_auth/fingerprint.rb
 - lib/usps/jwt_auth/incorrect_login.rb
 - lib/usps/jwt_auth/railtie.rb
 - lib/usps/jwt_auth/version.rb