lyrebird 0.0.0 → 1.0.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9634bd5e47288132993ae694000573ebe7a74035a43628f74053a68eb26ea785
-  data.tar.gz: 0d733419004764bdf5b5d60cd2ed55fd6b7d4c7531c5fc37725e5c13a6e5eae9
+  metadata.gz: 01f50b61e7c1cf3b9417c22f495bfc6cd37c15cdd5bb6989147a4462c10ce7ca
+  data.tar.gz: ee3ff1a24a14319f978685696a73df8f6dd0a321a9907ef0e0c47cb5b2344fdf
 SHA512:
-  metadata.gz: 6053439212105edd8ab7b977c42d38a95678ed2f692f6fa19048b0e3dc3b8f822e0896e3a557fc59b3248d0040c71bc766252e2dcfe388b604a0feb0e953a8ad
-  data.tar.gz: 75421cfad59640abbbe5f73729dca6df1dc14b400066cc6e281e0cd6432c8c94fe42cdc647adb25adccf4ffc232a240f6c069d27c6be7bc5008205d6675a8a24
+  metadata.gz: 98f2d39495b3f5db08e9f27e8663e9b9924ff55ee41b1b9a81a707aa91f6bfa452e823fb577702990bb05e9fdcd439e36573700f62ef30cbd4b48202cf7f4b98
+  data.tar.gz: c526d72406244c4da1ba6cc9abe80abdd11191c7cba023db2a1a2b1bbd647a519aeb1531e49d4e09bd6701e1c6164a5b7969f141d005ff3109fe213bd0de0f1d

data/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+      - name: Run tests
+        run: bundle exec rake test

data/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+      - name: Build gem
+        run: gem build lyrebird.gemspec
+      - name: Publish to RubyGems
+        run: gem push lyrebird-*.gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}

data/README.md

@@ -1,35 +1,134 @@
 # Lyrebird
+A Ruby gem for mimicking SAML Identity Provider (IdP) responses in test
+environments.
 
-TODO: Delete this and the text below, and describe your gem
+## Installation
+```ruby
+gem "lyrebird", group: :test
+```
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/lyrebird`. To experiment with that code, run `bin/console` for an interactive prompt.
+## Basic example
+```ruby
+# test/integration/saml_test.rb
+class SAMLTest < ActionDispatch::IntegrationTest
+  test "consume creates a session" do
+    user = users(:alice)
 
-## Installation
+    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
+      }
+    )
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+    post saml_consume_path, params: { SAMLResponse: response.mimic }
 
-Install the gem and add to the application's Gemfile by executing:
+    assert_redirected_to dashboard_path
+    assert_equal user.id, session[:user_id]
+  end
+end
+```
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Response
+Creates complete SAML responses with embedded assertions.
+
+### Creating a response
+```ruby
+# With defaults
+response = Lyrebird::Response.new
+
+# 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"]
+  }
+)
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+### Getting the encoded response
+```ruby
+response.mimic    # Base64-encoded SAML response (for POST binding)
+response.document # REXML::Document for inspection
+```
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+### Signing
+```ruby
+cert = Lyrebird::Certificate.generate
+
+response = Lyrebird::Response.new(
+  certificate: cert,
+  sign_assertion: true, # Sign the assertion (default: false)
+  sign_response: true   # Sign the response (default: false)
+)
 ```
 
-## Usage
+### NameID Formats
+```ruby
+Lyrebird::NAMEID_EMAIL       # emailAddress (default)
+Lyrebird::NAMEID_PERSISTENT  # persistent
+Lyrebird::NAMEID_TRANSIENT   # transient
+Lyrebird::NAMEID_UNSPECIFIED # unspecified
+```
 
-TODO: Write usage instructions here
+## Configuring defaults
+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" }
+```
 
-## Development
+## Certificate
+Generates and manages X.509 certificates for signing SAML responses.
 
-After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Generating a new certificate
+```ruby
+# With defaults
+cert = Lyrebird::Certificate.generate
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+# 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)
+)
+```
 
-## Contributing
+### Loading an existing certificate
+```ruby
+cert = Lyrebird::Certificate.load(
+  private_key_pem: File.read("private_key.pem"),
+  certificate_pem: File.read("certificate.pem")
+)
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/lyrebird.
+### Exporting
+```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
+```

data/Rakefile

@@ -1,4 +1,11 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-task default: %i[]
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs.push("test")
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task default: :test

data/lib/lyrebird/assertion.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Assertion
+    def initialize(
+      issuer: DEFAULTS.issuer,
+      name_id: DEFAULTS.name_id,
+      name_id_format: DEFAULTS.name_id_format,
+      recipient: DEFAULTS.recipient,
+      in_response_to: DEFAULTS.in_response_to,
+      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_on_or_after = @issue_instant + valid_for
+      @audience = audience
+      @authn_context = authn_context
+      @attributes = attributes
+    end
+
+    def document
+      REXML::Document.new.tap do |d|
+        d.add_element(root)
+      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?
+      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)
+      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)
+      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
+      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
+      end
+    end
+
+    def attribute_statement
+      REXML::Element.new("saml:AttributeStatement").tap do |as|
+        @attributes.each do |name, values|
+          a = as.add_element("saml:Attribute")
+          a.add_attribute("Name", name)
+          a.add_attribute("NameFormat", ATTR_NAME_FORMAT)
+
+          Array(values).each do |value|
+            a.add_element("saml:AttributeValue").text = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lyrebird/certificate.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Certificate
+    attr_reader :private_key, :certificate
+
+    def self.generate(bits: 2048, **options)
+      new(OpenSSL::PKey::RSA.new(bits), **options)
+    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)
+    end
+
+    def initialize(
+      private_key,
+      cn: nil,
+      o: nil,
+      valid_for: 365,
+      valid_until: nil,
+      certificate: 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
+    end
+
+    def private_key_pem
+      @private_key.to_pem
+    end
+
+    def certificate_pem
+      @certificate.to_pem
+    end
+
+    def fingerprint
+      OpenSSL::Digest::SHA256.hexdigest(@certificate.to_der)
+    end
+
+    def base64
+      Base64.strict_encode64(@certificate.to_der)
+    end
+
+    private
+
+    def build_certificate
+      OpenSSL::X509::Certificate.new.tap do |c|
+        c.public_key = @private_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)
+      end
+    end
+
+    def build_subject
+      OpenSSL::X509::Name.new.tap do |name|
+        name.add_entry("CN", @common_name) if @common_name
+        name.add_entry("O", @organization) if @organization
+      end
+    end
+  end
+end

data/lib/lyrebird/defaults.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  NAMEID_EMAIL = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
+  NAMEID_PERSISTENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
+  NAMEID_TRANSIENT = "urn:oasis:names:tc:SAML:2.0:nameid-format:transient"
+  NAMEID_UNSPECIFIED = "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
+
+  class Defaults
+    attr_accessor :issuer
+    attr_accessor :name_id
+    attr_accessor :name_id_format
+    attr_accessor :recipient
+    attr_accessor :in_response_to
+    attr_accessor :valid_for
+    attr_accessor :audience
+    attr_accessor :authn_context
+    attr_accessor :attributes
+
+    def initialize
+      @issuer = "https://idp.example.com"
+      @name_id = "user@example.com"
+      @name_id_format = NAMEID_EMAIL
+      @recipient = "https://sp.example.com/acs"
+      @in_response_to = "_request_id"
+      @valid_for = 300 # 5 minutes
+      @audience = "https://sp.example.com"
+
+      @authn_context =
+        "urn:oasis:names:tc:SAML:2.0:ac:classes:" \
+        "PasswordProtectedTransport"
+
+      @attributes = {
+        first_name: "Test",
+        last_name: "User",
+      }
+    end
+  end
+
+  DEFAULTS = Defaults.new
+end

data/lib/lyrebird/id.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  module ID
+    def self.generate
+      "_#{SecureRandom.uuid}"
+    end
+  end
+end

data/lib/lyrebird/namespaces.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  SAML_ASSERTION_NS = "urn:oasis:names:tc:SAML:2.0:assertion"
+  SAML_PROTOCOL_NS = "urn:oasis:names:tc:SAML:2.0:protocol"
+  XMLDSIG_NS = "http://www.w3.org/2000/09/xmldsig#"
+  ENVELOPED_SIG = "http://www.w3.org/2000/09/xmldsig#enveloped-signature"
+  EXC_C14N = "http://www.w3.org/2001/10/xml-exc-c14n#"
+  SHA256_DIGEST = "http://www.w3.org/2001/04/xmlenc#sha256"
+  RSA_SHA256 = "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"
+  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"
+end

data/lib/lyrebird/response.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Response
+    def initialize(
+      issuer: DEFAULTS.issuer,
+      destination: DEFAULTS.recipient,
+      in_response_to: DEFAULTS.in_response_to,
+      certificate: nil,
+      sign_assertion: false,
+      sign_response: false,
+      **assertion_options
+    )
+      @id = ID.generate
+      @issue_instant = Time.now.utc
+      @issuer = issuer
+      @destination = destination
+      @in_response_to = in_response_to
+      @certificate = certificate
+      @sign_assertion = sign_assertion
+      @sign_response = sign_response
+
+      @assertion = Assertion.new(
+        issuer: issuer,
+        in_response_to: in_response_to,
+        **assertion_options
+      )
+    end
+
+    def mimic
+      Base64.strict_encode64(document.to_s)
+    end
+
+    def document
+      REXML::Document.new.tap do |d|
+        d.add_element(root)
+      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)
+        r.add_attribute("Version", "2.0")
+        r.add_attribute("IssueInstant", @issue_instant.iso8601)
+        r.add_attribute("Destination", @destination)
+        r.add_attribute("InResponseTo", @in_response_to)
+        r.add_element("saml:Issuer").text = @issuer
+        r.add_element(status)
+        a = r.add_element(@assertion.document.root)
+        Signature.new(a, certificate: @certificate).sign! if @sign_assertion
+        Signature.new(r, certificate: @certificate).sign! if @sign_response
+      end
+    end
+
+    def status
+      REXML::Element.new("samlp:Status").tap do |s|
+        sc = s.add_element("samlp:StatusCode")
+        sc.add_attribute("Value", STATUS_SUCCESS)
+      end
+    end
+  end
+end

data/lib/lyrebird/signature.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Lyrebird
+  class Signature
+    def initialize(element, certificate:)
+      @element = element
+      @certificate = certificate
+      @element_id = @element.attributes["ID"]
+    end
+
+    def sign!
+      issuer = @element.elements["saml:Issuer"]
+      @element.insert_after(issuer, signature_element)
+    end
+
+    private
+
+    def signature_element
+      REXML::Element.new("ds:Signature").tap do |sig|
+        sig.add_namespace("ds", XMLDSIG_NS)
+        sig.add_element(signed_info)
+        sig.add_element(signature_value)
+        sig.add_element(key_info)
+      end
+    end
+
+    def signed_info
+      REXML::Element.new("ds:SignedInfo").tap do |si|
+        cm = si.add_element("ds:CanonicalizationMethod")
+        cm.add_attribute("Algorithm", EXC_C14N)
+        sm = si.add_element("ds:SignatureMethod")
+        sm.add_attribute("Algorithm", RSA_SHA256)
+        si.add_element(reference)
+      end
+    end
+
+    def signature_value
+      REXML::Element.new("ds:SignatureValue").tap do |sv|
+        sig = @certificate.private_key.sign("SHA256", signed_info.to_s)
+        sv.text = Base64.strict_encode64(sig)
+      end
+    end
+
+    def key_info
+      REXML::Element.new("ds:KeyInfo").tap do |ki|
+        x = ki.add_element("ds:X509Data")
+        x.add_element("ds:X509Certificate").text = @certificate.base64
+      end
+    end
+
+    def reference
+      REXML::Element.new("ds:Reference").tap do |ref|
+        ref.add_attribute("URI", "##{@element_id}")
+        ref.add_element(transforms)
+        dm = ref.add_element("ds:DigestMethod")
+        dm.add_attribute("Algorithm", SHA256_DIGEST)
+        ref.add_element("ds:DigestValue").text = compute_digest(@element)
+      end
+    end
+
+    def transforms
+      REXML::Element.new("ds:Transforms").tap do |t|
+        enveloped = t.add_element("ds:Transform")
+        enveloped.add_attribute("Algorithm", ENVELOPED_SIG)
+        c14n = t.add_element("ds:Transform")
+        c14n.add_attribute("Algorithm", EXC_C14N)
+      end
+    end
+
+    def compute_digest(element)
+      digest = OpenSSL::Digest::SHA256.digest(element.to_s)
+      Base64.strict_encode64(digest)
+    end
+  end
+end

data/lib/lyrebird/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Lyrebird
-  VERSION = "0.0.0"
+  VERSION = "1.0.0.alpha1"
 end

data/lib/lyrebird.rb

@@ -1,8 +1,20 @@
 # frozen_string_literal: true
 
+require "base64"
+require "openssl"
+require "rexml"
+require "securerandom"
+require "time"
+
+require_relative "lyrebird/assertion"
+require_relative "lyrebird/certificate"
+require_relative "lyrebird/defaults"
+require_relative "lyrebird/id"
+require_relative "lyrebird/namespaces"
+require_relative "lyrebird/response"
+require_relative "lyrebird/signature"
 require_relative "lyrebird/version"
 
 module Lyrebird
   class Error < StandardError; end
-  # Your code goes here...
 end

data/lyrebird.gemspec

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require_relative "lib/lyrebird/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "lyrebird"
+  spec.version = Lyrebird::VERSION
+  spec.authors = ["Josh"]
+
+  spec.summary = "Mimics SAML Identity Provider (IdP) responses for testing"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.files = `git ls-files -z`.split("\x0")
+  spec.files.delete("Gemfile")
+  spec.files.delete(".gitignore")
+  spec.files.reject! { |f| f.start_with?("bin/") }
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "base64"
+  spec.add_dependency "rexml"
+
+  spec.add_development_dependency "minitest"
+  spec.add_development_dependency "rake"
+end