lyrebird 1.0.0.alpha2 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b18c9229d638025f9882d18957a043c890e128ae5cbf9541d97f0cce078ce8e1
-  data.tar.gz: 28ce7ba82169a7fa5b1ac90299eb09af37781adefc74522a6ee43e16f822f740
+  metadata.gz: a2c22dc89d09728d25d5563a9db0c136b144865ddea516ea71bd1806a4bf0ce2
+  data.tar.gz: 002da134ef786dd04b2f61a3b2f01a2fe43ec4e772081b9d76dd4b4f5788e839
 SHA512:
-  metadata.gz: 7edb0e358a6f295f80731bcf2d6544d55843b69c69bd25fcfbffc9a750240af558dfad598ba2939e6b9fa96033b17a7e827715908e08f3005ece03284c75f9a2
-  data.tar.gz: c7ba17cac0ffe23dcc264c52c6b8c6ce8fc44900bc0a302866e9c9aee2f874fd6f12ae5feda573c2d864047aac56a6bb5d67a000f570b018be54062b1e0acaab
+  metadata.gz: dc069741583e5940e825df140b405fe9c5710632c38927d2fb0baa80c52a4dafcb06170ac72a82259b9708f651e83e2ca11ee1d758d0031c1502f2d068faba57
+  data.tar.gz: 78a80065561c35f30b81a588a9584c173b044064a9b73266385a6708109f0b02952e0acbcbc1d6768d1750ea47ebdcbf346f42dbc7b9e151e0731a43316c995a

data/LICENSE.md

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026-present Simple SAML
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -1,3 +1,7 @@
+[![Gem Version](
+https://badge.fury.io/rb/lyrebird.svg
+)](https://badge.fury.io/rb/lyrebird)
+
 # Lyrebird
 A Ruby gem for mimicking SAML Identity Provider (IdP) responses in test
 environments.
@@ -11,6 +15,10 @@ gem "lyrebird", group: :test
 ```ruby
 # test/integration/saml_test.rb
 class SAMLTest < ActionDispatch::IntegrationTest
+  setup do
+    @idp_cert = Lyrebird::Certificate.build
+  end
+
   test "consume creates a session" do
     user = users(:alice)
 
@@ -20,6 +28,7 @@ class SAMLTest < ActionDispatch::IntegrationTest
       r.recipient = saml_consume_url
       r.audience = root_url
       r.name_id = user.email
+      r.sign_with = @idp_cert
 
       r.attributes do |a|
         a.email = user.email
@@ -84,20 +93,20 @@ end
 ### Getting the encoded response
 ```ruby
 response.mimic    # Base64-encoded SAML response (for POST binding)
-response.document # REXML::Document for inspection
+response.document # Nokogiri::XML::Document for inspection
 ```
 
 ### Signing
 Sign both the assertion and response with an IdP certificate:
 ```ruby
-idp_cert = Lyrebird::Certificate.generate
+idp_cert = Lyrebird::Certificate.build
 response = Lyrebird::Response.build(sign_with: idp_cert)
 ```
 
 ### Encryption
 Encrypt assertions using the SP's certificate so only the SP can decrypt them:
 ```ruby
-sp_cert = Lyrebird::Certificate.generate  # In practice, provided by the SP
+sp_cert = Lyrebird::Certificate.build
 response = Lyrebird::Response.build(encrypt_with: sp_cert)
 ```
 
@@ -121,46 +130,49 @@ Lyrebird::NAMEID_UNSPECIFIED # unspecified
 Override defaults globally for all responses/assertions:
 ```ruby
 # test/test_helper.rb
-Lyrebird::DEFAULTS.issuer = "https://custom.example.com"
-Lyrebird::DEFAULTS.recipient = "https://custom.example.com/acs"
-Lyrebird::DEFAULTS.audience = "https://custom.example.com"
-Lyrebird::DEFAULTS.name_id = "default@example.com"
-Lyrebird::DEFAULTS.valid_for = 600 # 10 minutes
-Lyrebird::DEFAULTS.attributes = { role: "user" }
+Lyrebird.configure do |d|
+  d.issuer = "https://custom.example.com"
+  d.recipient = "https://custom.example.com/acs"
+  d.audience = "https://custom.example.com"
+  d.name_id = "default@example.com"
+  d.valid_for = 600 # 10 minutes
+  d.attributes = { role: "user" }
+end
 ```
+Defaults are frozen after configuration for thread safety.
 
 ## Certificate
 Generates and manages X.509 certificates for signing SAML responses.
 
-### Generating a new certificate
+### Building a certificate
 ```ruby
 # With defaults
-cert = Lyrebird::Certificate.generate
+cert = Lyrebird::Certificate.build
 
 # With options
-cert = Lyrebird::Certificate.generate(
-  bits: 4096,                         # RSA key size (default: 2048)
-  cn: "example.com",                  # Common Name
-  o: "Acme",                          # Organization
-  valid_for: 30,                      # Validity in days (default: 365)
-  valid_until: Time.new(2999, 12, 31) # Specific expiration (overrides valid_for)
-)
+cert = Lyrebird::Certificate.build do |c|
+  c.bits = 4096                           # RSA key size (default: 2048)
+  c.cn = "example.com"                    # Common Name
+  c.o = "Acme"                            # Organization
+  c.valid_for = 30                        # Days (default: 365)
+  c.valid_until = Time.new(2999, 12, 31)  # Overrides valid_for
+end
 ```
 
 ### Loading an existing certificate
 ```ruby
 cert = Lyrebird::Certificate.load(
-  private_key_pem: File.read("private_key.pem"),
-  certificate_pem: File.read("certificate.pem")
+  key_pem: File.read("private_key.pem"),
+  x509_pem: File.read("certificate.pem")
 )
 ```
 
-### Exporting
+### Using a certificate
 ```ruby
-cert.private_key     # OpenSSL::PKey::RSA object
-cert.certificate     # OpenSSL::X509::Certificate object
-cert.private_key_pem # PEM-encoded private key
-cert.certificate_pem # PEM-encoded certificate
-cert.base64          # Base64-encoded certificate (for SAML metadata)
-cert.fingerprint     # SHA256 fingerprint
+cert.key          # OpenSSL::PKey::RSA private key
+cert.x509         # OpenSSL::X509::Certificate object
+cert.key_pem      # PEM-encoded private key
+cert.x509_pem     # PEM-encoded certificate
+cert.base64       # Base64-encoded certificate (for SAML metadata)
+cert.fingerprint  # SHA256 fingerprint
 ```

data/lib/lyrebird/assertion.rb

@@ -28,74 +28,110 @@ module Lyrebird
     end
 
     def document
-      REXML::Document.new.tap do |d|
-        d.add_element(root)
+      @document ||= Nokogiri::XML::Document.new.tap do |doc|
+        doc.root = root(doc)
       end
     end
 
     private
 
-    def root
-      REXML::Element.new("saml:Assertion").tap do |r|
-        r.add_namespace("saml", SAML_ASSERTION_NS)
-        r.add_attribute("ID", ID.generate)
-        r.add_attribute("Version", "2.0")
-        r.add_attribute("IssueInstant", @issue_instant.iso8601)
-        r.add_element("saml:Issuer").text = @issuer
-        r.add_element(subject)
-        r.add_element(conditions)
-        r.add_element(authn_statement)
-        r.add_element(attribute_statement) if @attributes.any?
+    def root(doc)
+      doc.create_element("Assertion").tap do |a|
+        ns = a.add_namespace_definition("saml", SAML_ASSERTION_NS)
+
+        a.namespace = ns
+        a["ID"] = ID.generate
+        a["Version"] = "2.0"
+        a["IssueInstant"] = @issue_instant.iso8601
+
+        a.add_child(doc.create_element("Issuer")).tap do |i|
+          i.namespace = ns
+          i.content = @issuer
+        end
+
+        a.add_child(subject(doc, ns))
+        a.add_child(conditions(doc, ns))
+        a.add_child(authn_statement(doc, ns))
+        a.add_child(attribute_statement(doc, ns)) if @attributes.any?
       end
     end
 
-    def subject
-      REXML::Element.new("saml:Subject").tap do |s|
-        name_id = s.add_element("saml:NameID")
-        name_id.add_attribute("Format", @name_id_format)
-        name_id.text = @name_id
-        s.add_element(subject_confirmation)
+    def subject(doc, ns)
+      doc.create_element("Subject").tap do |s|
+        s.namespace = ns
+
+        s.add_child(doc.create_element("NameID")).tap do |nid|
+          nid.namespace = ns
+          nid["Format"] = @name_id_format
+          nid.content = @name_id
+        end
+
+        s.add_child(subject_confirmation(doc, ns))
       end
     end
 
-    def subject_confirmation
-      REXML::Element.new("saml:SubjectConfirmation").tap do |sc|
-        sc.add_attribute("Method", CM_BEARER)
-        data = sc.add_element("saml:SubjectConfirmationData")
-        data.add_attribute("NotOnOrAfter", @not_on_or_after.iso8601)
-        data.add_attribute("Recipient", @recipient)
-        data.add_attribute("InResponseTo", @in_response_to) if @in_response_to
+    def subject_confirmation(doc, ns)
+      doc.create_element("SubjectConfirmation").tap do |sc|
+        sc.namespace = ns
+        sc["Method"] = CM_BEARER
+
+        sc.add_child(doc.create_element("SubjectConfirmationData")).tap do |d|
+          d.namespace = ns
+          d["NotOnOrAfter"] = @not_on_or_after.iso8601
+          d["Recipient"] = @recipient
+          d["InResponseTo"] = @in_response_to if @in_response_to
+        end
       end
     end
 
-    def conditions
-      REXML::Element.new("saml:Conditions").tap do |c|
-        c.add_attribute("NotBefore", @not_before.iso8601)
-        c.add_attribute("NotOnOrAfter", @not_on_or_after.iso8601)
-        ar = c.add_element("saml:AudienceRestriction")
-        ar.add_element("saml:Audience").text = @audience
+    def conditions(doc, ns)
+      doc.create_element("Conditions").tap do |c|
+        c.namespace = ns
+        c["NotBefore"] = @not_before.iso8601
+        c["NotOnOrAfter"] = @not_on_or_after.iso8601
+
+        c.add_child(doc.create_element("AudienceRestriction")).tap do |ar|
+          ar.namespace = ns
+          ar.add_child(doc.create_element("Audience")).tap do |a|
+            a.namespace = ns
+            a.content = @audience
+          end
+        end
       end
     end
 
-    def authn_statement
-      REXML::Element.new("saml:AuthnStatement").tap do |as|
-        as.add_attribute("AuthnInstant", @issue_instant.iso8601)
-        as.add_attribute("SessionIndex", ID.generate)
-        ac = as.add_element("saml:AuthnContext")
-        cr = ac.add_element("saml:AuthnContextClassRef")
-        cr.text = @authn_context
+    def authn_statement(doc, ns)
+      doc.create_element("AuthnStatement").tap do |as|
+        as.namespace = ns
+        as["AuthnInstant"] = @issue_instant.iso8601
+        as["SessionIndex"] = ID.generate
+
+        as.add_child(doc.create_element("AuthnContext")).tap do |ac|
+          ac.namespace = ns
+          ac.add_child(doc.create_element("AuthnContextClassRef")).tap do |cr|
+            cr.namespace = ns
+            cr.content = @authn_context
+          end
+        end
       end
     end
 
-    def attribute_statement
-      REXML::Element.new("saml:AttributeStatement").tap do |as|
+    def attribute_statement(doc, ns)
+      doc.create_element("AttributeStatement").tap do |as|
+        as.namespace = ns
+
         @attributes.each do |name, values|
-          a = as.add_element("saml:Attribute")
-          a.add_attribute("Name", name)
-          a.add_attribute("NameFormat", ATTR_NAME_FORMAT)
+          as.add_child(doc.create_element("Attribute")).tap do |a|
+            a.namespace = ns
+            a["Name"] = name
+            a["NameFormat"] = ATTR_NAME_FORMAT
 
-          Array(values).each do |value|
-            a.add_element("saml:AttributeValue").text = value
+            Array(values).each do |value|
+              a.add_child(doc.create_element("AttributeValue")).tap do |av|
+                av.namespace = ns
+                av.content = value
+              end
+            end
           end
         end
       end

data/lib/lyrebird/certificate.rb

@@ -2,62 +2,67 @@
 
 module Lyrebird
   class Certificate
-    attr_reader :private_key, :certificate
+    attr_reader :key, :x509
 
-    def self.generate(bits: 2048, **options)
-      new(OpenSSL::PKey::RSA.new(bits), **options)
+    def self.build(**kwargs)
+      config = OpenStruct.new(kwargs)
+      yield config if block_given?
+      new(**config.to_h)
     end
 
-    def self.load(private_key_pem:, certificate_pem:)
-      private_key = OpenSSL::PKey::RSA.new(private_key_pem)
-      certificate = OpenSSL::X509::Certificate.new(certificate_pem)
-      new(private_key, certificate: certificate)
+    def self.load(key_pem:, x509_pem:)
+      key = OpenSSL::PKey::RSA.new(key_pem)
+      x509 = OpenSSL::X509::Certificate.new(x509_pem)
+      new(key: key, x509: x509)
     end
 
     def initialize(
-      private_key,
+      bits: 2048,
       cn: nil,
       o: nil,
       valid_for: 365,
       valid_until: nil,
-      certificate: nil
+      key: nil,
+      x509: nil
     )
-      @private_key = private_key
       @common_name = cn
       @organization = o
       @valid_for = valid_for
       @valid_until = valid_until
-      @certificate = certificate || build_certificate
+      @key = key || OpenSSL::PKey::RSA.new(bits)
+      @x509 = x509 || build_x509
     end
 
-    def private_key_pem
-      @private_key.to_pem
+    def key_pem
+      @key.to_pem
     end
 
-    def certificate_pem
-      @certificate.to_pem
+    def x509_pem
+      @x509.to_pem
     end
 
     def fingerprint
-      OpenSSL::Digest::SHA256.hexdigest(@certificate.to_der)
+      OpenSSL::Digest::SHA256.hexdigest(@x509.to_der)
     end
 
     def base64
-      Base64.strict_encode64(@certificate.to_der)
+      Base64.strict_encode64(@x509.to_der)
     end
 
     private
 
-    def build_certificate
-      now = Time.now
+    def build_x509
+      now = Time.now.utc
 
       OpenSSL::X509::Certificate.new.tap do |c|
-        c.public_key = @private_key.public_key
+        c.version = 2
+        c.serial = OpenSSL::BN.rand(64)
+        c.public_key = @key.public_key
         c.subject = build_subject
         c.issuer = c.subject
         c.not_before = now
         c.not_after = @valid_until || now + (@valid_for * 86_400)
-        c.sign(@private_key, OpenSSL::Digest::SHA256.new)
+        c.sign(@key, OpenSSL::Digest::SHA256.new)
       end
     end
 

data/lib/lyrebird/defaults.rb

@@ -33,7 +33,7 @@ module Lyrebird
       @attributes = {
         first_name: "Test",
         last_name: "User",
-      }
+      }.freeze
     end
   end
 

data/lib/lyrebird/encryption.rb

@@ -5,70 +5,91 @@ module Lyrebird
     def initialize(element, certificate)
       @element = element
       @certificate = certificate
+      @doc = element.document
       @aes_key = SecureRandom.random_bytes(32)
     end
 
     def encrypt
-      encrypted_assertion
+      build_encrypted_assertion
     end
 
     private
 
-    def encrypted_assertion
-      REXML::Element.new("saml:EncryptedAssertion").tap do |ea|
-        ea.add_namespace("saml", SAML_ASSERTION_NS)
-        ea.add_element(encrypted_data)
+    def build_encrypted_assertion
+      @doc.create_element("EncryptedAssertion").tap do |ea|
+        @saml = ea.add_namespace_definition("saml", SAML_ASSERTION_NS)
+        ea.namespace = @saml
+        ea.add_child(build_encrypted_data)
       end
     end
 
-    def encrypted_data
-      REXML::Element.new("xenc:EncryptedData").tap do |ed|
-        ed.add_namespace("xenc", XMLENC_NS)
-        ed.add_attribute("Type", "#{XMLENC_NS}Element")
-        em = ed.add_element("xenc:EncryptionMethod")
-        em.add_attribute("Algorithm", AES256_CBC)
-        ed.add_element(key_info)
-        ed.add_element(cipher_data)
+    def build_encrypted_data
+      @doc.create_element("EncryptedData").tap do |ed|
+        @xenc = ed.add_namespace_definition("xenc", XMLENC_NS)
+        ed.namespace = @xenc
+        ed["Type"] = "#{XMLENC_NS}Element"
+
+        ed.add_child(@doc.create_element("EncryptionMethod")).tap do |em|
+          em.namespace = @xenc
+          em["Algorithm"] = AES256_CBC
+        end
+
+        ed.add_child(build_key_info)
+        ed.add_child(build_cipher_data)
       end
     end
 
-    def key_info
-      REXML::Element.new("ds:KeyInfo").tap do |ki|
-        ki.add_namespace("ds", XMLDSIG_NS)
-        ki.add_element(encrypted_key)
+    def build_key_info
+      @doc.create_element("KeyInfo").tap do |ki|
+        @ds = ki.add_namespace_definition("ds", XMLDSIG_NS)
+        ki.namespace = @ds
+        ki.add_child(build_encrypted_key)
       end
     end
 
-    def encrypted_key
-      REXML::Element.new("xenc:EncryptedKey").tap do |ek|
-        ek.add_namespace("xenc", XMLENC_NS)
-        em = ek.add_element("xenc:EncryptionMethod")
-        em.add_attribute("Algorithm", RSA_OAEP)
-        ek.add_element(encrypted_key_cipher_data)
+    def build_encrypted_key
+      @doc.create_element("EncryptedKey").tap do |ek|
+        ek.add_namespace_definition("xenc", XMLENC_NS)
+        ek.namespace = @xenc
+
+        ek.add_child(@doc.create_element("EncryptionMethod")).tap do |em|
+          em.namespace = @xenc
+          em["Algorithm"] = RSA_OAEP
+        end
+
+        ek.add_child(build_encrypted_key_cipher_data)
       end
     end
 
-    def encrypted_key_cipher_data
-      public_key = @certificate.certificate.public_key
+    def build_encrypted_key_cipher_data
+      public_key = @certificate.x509.public_key
       padding = OpenSSL::PKey::RSA::PKCS1_OAEP_PADDING
       encrypted_aes_key = public_key.public_encrypt(@aes_key, padding)
 
-      REXML::Element.new("xenc:CipherData").tap do |cd|
-        cv = Base64.strict_encode64(encrypted_aes_key)
-        cd.add_element("xenc:CipherValue").text = cv
+      @doc.create_element("CipherData").tap do |cd|
+        cd.namespace = @xenc
+
+        cd.add_child(@doc.create_element("CipherValue")).tap do |cv|
+          cv.namespace = @xenc
+          cv.content = Base64.strict_encode64(encrypted_aes_key)
+        end
       end
     end
 
-    def cipher_data
+    def build_cipher_data
       cipher = OpenSSL::Cipher.new("AES-256-CBC")
       cipher.encrypt
       cipher.key = @aes_key
       iv = cipher.random_iv
-      ciphertext = cipher.update(@element.to_s) + cipher.final
+      ciphertext = cipher.update(@element.to_xml) + cipher.final
+
+      @doc.create_element("CipherData").tap do |cd|
+        cd.namespace = @xenc
 
-      REXML::Element.new("xenc:CipherData").tap do |cd|
-        cv = Base64.strict_encode64(iv + ciphertext)
-        cd.add_element("xenc:CipherValue").text = cv
+        cd.add_child(@doc.create_element("CipherValue")).tap do |cv|
+          cv.namespace = @xenc
+          cv.content = Base64.strict_encode64(iv + ciphertext)
+        end
       end
     end
   end

data/lib/lyrebird/response.rb

@@ -35,44 +35,71 @@ module Lyrebird
     end
 
     def mimic
-      Base64.strict_encode64(document.to_s)
+      Base64.strict_encode64(document.to_xml(save_with: 0))
     end
 
     def document
-      REXML::Document.new.tap do |d|
-        d.add_element(root)
+      @document ||= Nokogiri::XML::Document.new.tap do |doc|
+        doc.root = build_response(doc)
+        sign_assertion(doc) if @sign_with && !@encrypt_with
+        sign_response(doc) if @sign_with
       end
     end
 
     private
 
-    def root
-      REXML::Element.new("samlp:Response").tap do |r|
-        r.add_namespace("samlp", SAML_PROTOCOL_NS)
-        r.add_namespace("saml", SAML_ASSERTION_NS)
-        r.add_attribute("ID", ID.generate)
-        r.add_attribute("Version", "2.0")
-        r.add_attribute("IssueInstant", Time.now.utc.iso8601)
-        r.add_attribute("Destination", @destination) if @destination
-        r.add_attribute("InResponseTo", @in_response_to) if @in_response_to
-        r.add_element("saml:Issuer").text = @issuer
-        r.add_element(status)
-        r.add_element(assertion_element)
-        Signature.new(r, @sign_with).sign! if @sign_with
+    def build_response(doc)
+      doc.create_element("Response").tap do |r|
+        @samlp = r.add_namespace_definition("samlp", SAML_PROTOCOL_NS)
+        @saml = r.add_namespace_definition("saml", SAML_ASSERTION_NS)
+
+        r.namespace = @samlp
+        r["ID"] = ID.generate
+        r["Version"] = "2.0"
+        r["IssueInstant"] = Time.now.utc.iso8601
+        r["Destination"] = @destination if @destination
+        r["InResponseTo"] = @in_response_to if @in_response_to
+
+        r.add_child(doc.create_element("Issuer")).tap do |i|
+          i.namespace = @saml
+          i.content = @issuer
+        end
+
+        r.add_child(build_status(doc))
+        r.add_child(build_assertion_element(doc))
+      end
+    end
+
+    def build_assertion_element(doc)
+      assertion_doc = @assertion.document
+      element = assertion_doc.root
+
+      if @encrypt_with
+        Signature.new(element, @sign_with).sign! if @sign_with
+        Encryption.new(element, @encrypt_with).encrypt
+      else
+        element
       end
     end
 
-    def assertion_element
-      element = @assertion.document.root
-      Signature.new(element, @sign_with).sign! if @sign_with
-      return element unless @encrypt_with
-      Encryption.new(element, @encrypt_with).encrypt
+    def sign_assertion(doc)
+      ns = { "saml" => SAML_ASSERTION_NS }
+      assertion = doc.at_xpath("//saml:Assertion", ns)
+      Signature.new(assertion, @sign_with).sign!
     end
 
-    def status
-      REXML::Element.new("samlp:Status").tap do |s|
-        sc = s.add_element("samlp:StatusCode")
-        sc.add_attribute("Value", STATUS_SUCCESS)
+    def sign_response(doc)
+      Signature.new(doc.root, @sign_with).sign!
+    end
+
+    def build_status(doc)
+      doc.create_element("Status").tap do |s|
+        s.namespace = @samlp
+
+        s.add_child(doc.create_element("StatusCode")).tap do |sc|
+          sc.namespace = @samlp
+          sc["Value"] = STATUS_SUCCESS
+        end
       end
     end
   end