lyrebird 1.0.0.alpha1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01f50b61e7c1cf3b9417c22f495bfc6cd37c15cdd5bb6989147a4462c10ce7ca
-  data.tar.gz: ee3ff1a24a14319f978685696a73df8f6dd0a321a9907ef0e0c47cb5b2344fdf
+  metadata.gz: 61005075359475ff6b492db62c80f7fea1724bb059c03f19a3f9d04c1f37871f
+  data.tar.gz: 0e44c46fe69c8701c7b5441f7a23b6bbf752ad957ae044e5f19d398c01a8db91
 SHA512:
-  metadata.gz: 98f2d39495b3f5db08e9f27e8663e9b9924ff55ee41b1b9a81a707aa91f6bfa452e823fb577702990bb05e9fdcd439e36573700f62ef30cbd4b48202cf7f4b98
-  data.tar.gz: c526d72406244c4da1ba6cc9abe80abdd11191c7cba023db2a1a2b1bbd647a519aeb1531e49d4e09bd6701e1c6164a5b7969f141d005ff3109fe213bd0de0f1d
+  metadata.gz: 1ccd8ff5e0c7a4f441dc275a6231924f8969993c7b670b83a60d01f16e4ebf8fff33ccedffaad21a45dc6bca056d1450c5b6566699f9fd733f71fc9342818bec
+  data.tar.gz: c0ebff2c3cc4134b84fb52327ee41c7d34bd9b2ab3d89ac7a50a3485bc912ca6936ad64388b04253001106a961f7f2caad313b88a2915e86c7bbd4c516eae673

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.
@@ -14,18 +18,19 @@ class SAMLTest < ActionDispatch::IntegrationTest
   test "consume creates a session" do
     user = users(:alice)
 
-    response = Lyrebird::Response.new(
-      issuer: "https://idp.example.com",
-      destination: saml_consume_url,
-      recipient: saml_consume_url,
-      audience: root_url,
-      name_id: user.email,
-      attributes: {
-        email: user.email,
-        first_name: user.first_name,
-        last_name: user.last_name
-      }
-    )
+    response = Lyrebird::Response.build do |r|
+      r.issuer = "https://idp.example.com"
+      r.destination = saml_consume_url
+      r.recipient = saml_consume_url
+      r.audience = root_url
+      r.name_id = user.email
+
+      r.attributes do |a|
+        a.email = user.email
+        a.first_name = user.first_name
+        a.last_name = user.last_name
+      end
+    end
 
     post saml_consume_path, params: { SAMLResponse: response.mimic }
 
@@ -36,45 +41,76 @@ end
 ```
 
 ## Response
-Creates complete SAML responses with embedded assertions.
+Builds complete SAML responses with embedded assertions.
 
-### Creating a response
+### Building a response
+Defaults produce an SP-initiated response. See
+[IdP-initiated SSO](#idp-initiated-sso) to omit `InResponseTo` and
+`Destination`.
 ```ruby
-# With defaults
-response = Lyrebird::Response.new
+# With defaults (SP-initiated)
+response = Lyrebird::Response.build
 
 # With options
-response = Lyrebird::Response.new(
-  issuer: "https://idp.example.com",
-  destination: "https://sp.example.com/acs",
-  in_response_to: "_request_id",
-  name_id: "user@example.com",
-  name_id_format: Lyrebird::NAMEID_EMAIL,
-  recipient: "https://sp.example.com/acs",
-  audience: "https://sp.example.com",
-  valid_for: 300, # seconds
-  attributes: {
-    email: "user@example.com",
-    groups: ["admin", "users"]
-  }
-)
+response = Lyrebird::Response.build do |r|
+  r.issuer = "https://idp.example.com"
+  r.destination = "https://sp.example.com/acs"
+  r.in_response_to = "_request_id"
+  r.name_id = "user@example.com"
+  r.name_id_format = Lyrebird::NAMEID_EMAIL
+  r.recipient = "https://sp.example.com/acs"
+  r.audience = "https://sp.example.com"
+  r.authn_context = "urn:oasis:names:tc:SAML:2.0:ac:classes:Password"
+  r.not_before = Time.now.utc
+  r.valid_for = 300 # seconds
+  r.sign_with = idp_cert
+  r.encrypt_with = sp_cert
+
+  r.attributes do |a|
+    a.email = "user@example.com"
+    a.groups = ["admin", "users"]
+  end
+end
+```
+
+### IdP-initiated SSO
+For unsolicited (IdP-initiated) flows where there is no AuthnRequest,
+set `in_response_to` and `destination` to `nil` to omit them from the
+XML entirely:
+```ruby
+response = Lyrebird::Response.build do |r|
+  r.in_response_to = nil
+  r.destination = nil
+  r.name_id = "user@example.com"
+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
-cert = Lyrebird::Certificate.generate
+idp_cert = Lyrebird::Certificate.build
+response = Lyrebird::Response.build(sign_with: idp_cert)
+```
 
-response = Lyrebird::Response.new(
-  certificate: cert,
-  sign_assertion: true, # Sign the assertion (default: false)
-  sign_response: true   # Sign the response (default: false)
-)
+### Encryption
+Encrypt assertions using the SP's certificate so only the SP can decrypt them:
+```ruby
+sp_cert = Lyrebird::Certificate.build
+response = Lyrebird::Response.build(encrypt_with: sp_cert)
+```
+
+Signing and encryption can be combined:
+```ruby
+response = Lyrebird::Response.build do |r|
+  r.sign_with = idp_cert
+  r.encrypt_with = sp_cert
+end
 ```
 
 ### NameID Formats
@@ -89,46 +125,50 @@ 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(2026, 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.sign(data)   # Sign data with RSA-SHA256
+cert.base64       # Base64-encoded certificate (for SAML metadata)
+cert.fingerprint  # SHA256 fingerprint
 ```

data/lib/lyrebird/assertion.rb

@@ -8,19 +8,19 @@ module Lyrebird
       name_id_format: DEFAULTS.name_id_format,
       recipient: DEFAULTS.recipient,
       in_response_to: DEFAULTS.in_response_to,
+      not_before: nil,
       valid_for: DEFAULTS.valid_for,
       audience: DEFAULTS.audience,
       authn_context: DEFAULTS.authn_context,
       attributes: DEFAULTS.attributes
     )
-      @id = ID.generate
-      @session_index = ID.generate
       @issue_instant = Time.now.utc
       @issuer = issuer
       @name_id = name_id
       @name_id_format = name_id_format
       @recipient = recipient
       @in_response_to = in_response_to
+      @not_before = not_before || @issue_instant
       @not_on_or_after = @issue_instant + valid_for
       @audience = audience
       @authn_context = authn_context
@@ -28,74 +28,110 @@ module Lyrebird
     end
 
     def document
-      REXML::Document.new.tap do |d|
-        d.add_element(root)
+      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)
-        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)
+    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", @issue_instant.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", @session_index)
-        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,59 +2,71 @@
 
 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
-      @not_after = valid_until || Time.now + (valid_for * 24 * 60 * 60)
-      @certificate = certificate || build_certificate
+      @valid_for = valid_for
+      @valid_until = valid_until
+      @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
+
+    def sign(data)
+      @key.sign("SHA256", data)
     end
 
     private
 
-    def build_certificate
+    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 = Time.now
-        c.not_after = @not_after
-        c.sign(@private_key, OpenSSL::Digest::SHA256.new)
+        c.not_before = now
+        c.not_after = @valid_until || now + (@valid_for * 86_400)
+        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

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Encryption
+    def initialize(element, certificate)
+      @element = element
+      @certificate = certificate
+      @doc = element.document
+      @aes_key = SecureRandom.random_bytes(32)
+    end
+
+    def encrypt
+      build_encrypted_assertion
+    end
+
+    private
+
+    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 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 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 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 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)
+
+      @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 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_xml) + cipher.final
+
+      @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(iv + ciphertext)
+        end
+      end
+    end
+  end
+end

data/lib/lyrebird/namespaces.rb

@@ -11,4 +11,7 @@ module Lyrebird
   CM_BEARER = "urn:oasis:names:tc:SAML:2.0:cm:bearer"
   ATTR_NAME_FORMAT = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"
   STATUS_SUCCESS = "urn:oasis:names:tc:SAML:2.0:status:Success"
+  XMLENC_NS = "http://www.w3.org/2001/04/xmlenc#"
+  AES256_CBC = "http://www.w3.org/2001/04/xmlenc#aes256-cbc"
+  RSA_OAEP = "http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p"
 end