mythic-beasts 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b734cfcdd42c515ebf9d1c11d0ccc95067f0da9912fbbe62742de3865265f426
-  data.tar.gz: a53d53c0eaf241086e37cf25bad093156e5777edacabf90b291ffadfb43187d9
+  metadata.gz: d494ca87fec6261eef7a30bb03ca7fdab2d34c1b589de1d5cc19caaf543dfb77
+  data.tar.gz: ed5f8c6e915764a76e71d502e7210b850d78ce672699d34b04a33610605c1bef
 SHA512:
-  metadata.gz: e464d4d61ac8a68ae5c2615c235e6a0357e1dcf4253a8f6bb961b690b0b97164f8dde32f486f637c29ce77893b6d83f3a0b6e314dd55a8e82a956d4567e5ebf0
-  data.tar.gz: 580d8c412f04e39a4a8a3f25604beed9d540655ab83ce7766f60df2dd05752655003105f399b8cd6b1b79c44ba7c9bf6bef1424a76032dd773f386a6f237622b
+  metadata.gz: 583a0776da3cdff5fabd1ba06f2b3eab45ca6c458564c546323e8f077f4e42eb356304e9d43c0ce601914cd33d1b4366f46ba99cdb1e995f0ec80f348e2a1ac0
+  data.tar.gz: ac6d3815a942466222b0d536e82c7d378b1fc020a58a9892b0ba6053e2434353f62b2822b149e0cb17f69efa2802440243fac450a7074c4892cf2af1b2926757

data/CHANGELOG.md

@@ -7,7 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.2.0] - 2025-11-09
+## [1.0.0] - 2026-03-12
+
+### Added in 1.0.0
+
+- Email authentication verification (`verify_email_auth`, `verify_spf`, `verify_dmarc`, `verify_dkim`)
+  - Validates SPF records: syntax, lookup count (RFC 7208 limit of 10), multiple record detection
+  - Validates DMARC records: version tag, policy tag, aggregate report configuration
+  - Validates DKIM records: version tag, public key presence and base64 encoding
+  - Returns structured `Result` and `CheckResult` objects for programmatic use
+- New example scripts:
+  - `examples/list_dns.rb` - List all DNS records for a zone
+  - `examples/sync_dns.rb` - Generic DNS sync from YAML with dry run/apply
+  - `examples/sync_from_octodns.rb` - OctoDNS zone file sync with conflict detection
+  - `examples/verify_email_auth.rb` - CLI for email authentication verification
+- README documentation for email authentication verification and DNS examples
+
+## [0.2.0] - 2025-11-23
 
 ### Added in 0.2.0
 
@@ -19,7 +35,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Convenience method `create_simple` for quick proxy setup
   - Full CRUD operations on proxy endpoints by domain/hostname/address
 - DNS record verification after proxy configuration
-- DNS management integration in manage-vps tool
+- DNS management integration in `manage-vps` tool
+- Comprehensive test coverage improvements:
+  - Added tests for VPS newer API endpoints: `servers()`, `server()`, `reboot()`, `update()`, `unprovision()`, `iso_images()`, `create_with_identifier()`
+  - Added test for Client PATCH method
+  - Added test for Proxy client initialization
+  - Test suite now contains 73 examples with 100% pass rate
 
 ### Changed in 0.2.0
 

data/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Otaina Limited
+Copyright (c) 2025-2026 James Inman, Otaina Limited
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -84,6 +84,34 @@ MythicBeasts.client.dns.delete_records(
 MythicBeasts.client.dns.dynamic_update('home.example.com')
 ```
 
+### Email Authentication Verification
+
+Verify SPF, DKIM, and DMARC records are correctly configured for a domain:
+
+```ruby
+dns = MythicBeasts.client.dns
+
+# Verify all email auth records at once
+result = dns.verify_email_auth('example.com', dkim_selectors: ['google', 'mailchimp'])
+
+result.valid?    # => true if no errors across all checks
+result.errors    # => ["No DKIM record found for selector 'mailchimp'"]
+result.warnings  # => ["DMARC record missing 'rua' tag (no aggregate reports)"]
+
+# Access individual check results
+result.spf.record                # => "v=spf1 include:_spf.google.com ~all"
+result.spf.details[:lookup_count] # => 1
+result.dmarc.details[:policy]    # => "reject"
+result.dkim['google'].valid?     # => true
+
+# Or verify individual record types
+spf = dns.verify_spf('example.com')
+dmarc = dns.verify_dmarc('example.com')
+dkim = dns.verify_dkim('example.com', 'google')
+```
+
+See `examples/verify_email_auth.rb` for a complete CLI script.
+
 ### VPS Management
 
 #### Interactive CLI Tool (Recommended)
@@ -100,7 +128,12 @@ export MYTHIC_BEASTS_API_SECRET="your_secret"
 mythic-beasts-provision
 ```
 
-The CLI will guide you through selecting options by number:
+The gem ships two interactive CLI tools:
+
+- `mythic-beasts-provision` - provision a new VPS with guided setup
+- `mythic-beasts-manage-vps` - manage existing servers (DNS, proxy, controls)
+
+The provisioning CLI guides you through selecting options by number:
 
 - Selecting product (VPS size)
 - Choosing datacenter/zone
@@ -210,7 +243,17 @@ Available error classes:
 
 See the `examples/` directory for complete working examples:
 
+**DNS:**
+
+- `examples/list_dns.rb` - List all DNS records for a zone
+- `examples/sync_dns.rb` - Sync DNS records from a YAML file (with dry run/apply)
+- `examples/sync_from_octodns.rb` - Sync DNS from OctoDNS zone files (with conflict detection)
+- `examples/verify_email_auth.rb` - Verify SPF, DKIM, and DMARC records
+
+**VPS:**
+
 - `examples/list_zones_and_types.rb` - List available zones and VPS types
+- `examples/list_vps_options.rb` - List all VPS configuration options
 - `examples/provision_vps.rb` - Provision a new VPS server
 - `examples/ipv6_only_vps.rb` - Provision an IPv6-only VPS with proxy setup guide
 
@@ -219,7 +262,8 @@ Run examples with:
 ```bash
 export MYTHIC_BEASTS_API_KEY=your_key
 export MYTHIC_BEASTS_API_SECRET=your_secret
-ruby examples/list_zones_and_types.rb
+ruby examples/list_dns.rb example.com
+ruby examples/verify_email_auth.rb example.com google,mailchimp
 ```
 
 ## Development
@@ -253,7 +297,18 @@ bundle exec bundler-audit check --update    # Run security audit
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/tastybamboo/mythic-beasts.
+Bug reports and pull requests are welcome on GitHub at
+[tastybamboo/mythic-beasts](https://github.com/tastybamboo/mythic-beasts).
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b my-feature`)
+3. Run the test suite (`bundle exec rspec`)
+4. Ensure linting passes (`bundle exec standardrb`)
+5. Commit your changes
+6. Push to the branch and open a Pull Request
+
+This project is intended to be a safe, welcoming space for collaboration.
+Contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## Author
 
@@ -266,7 +321,7 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/tastyb
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
-Copyright © 2025, Otaina Limited
+Copyright © 2025-2026, James Inman, Otaina Limited
 
 ## Resources
 

data/lib/mythic_beasts/dns/email_auth.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+module MythicBeasts
+  class DNS
+    # Validates SPF, DKIM, and DMARC DNS records for a domain
+    #
+    # Uses the Mythic Beasts DNS API to fetch TXT records and validate
+    # email authentication configuration. Returns structured results
+    # rather than printing output, so callers can format as needed.
+    #
+    # @example Verify all email auth records
+    #   result = client.dns.verify_email_auth("example.com", dkim_selectors: ["google", "mailchimp"])
+    #   result.valid?      # => true/false
+    #   result.errors       # => ["No SPF record found"]
+    #   result.spf.record   # => "v=spf1 include:_spf.google.com ~all"
+    #
+    # @see https://www.mythic-beasts.com/support/api/dnsv2
+    class EmailAuth
+      # Aggregated result of all email authentication checks
+      Result = Struct.new(:spf, :dmarc, :dkim, :errors, :warnings, keyword_init: true) do
+        # @return [Boolean] true if no errors were found across all checks
+        def valid?
+          errors.empty?
+        end
+      end
+
+      # Result of an individual check (SPF, DMARC, or DKIM)
+      CheckResult = Struct.new(:record, :valid, :errors, :warnings, :details, keyword_init: true) do
+        # @return [Boolean] true if this individual check passed
+        def valid?
+          valid
+        end
+      end
+
+      SPF_LOOKUP_MECHANISMS = %w[include a mx ptr exists redirect].freeze
+      VALID_DMARC_POLICIES = %w[none quarantine reject].freeze
+
+      # @param dns [MythicBeasts::DNS] the DNS client instance
+      # @param zone [String] the domain/zone to verify
+      def initialize(dns, zone)
+        @dns = dns
+        @zone = zone
+      end
+
+      # Run all email authentication checks
+      #
+      # @param dkim_selectors [Array<String>] DKIM selectors to check (e.g., ["google", "mailchimp"])
+      # @return [Result] aggregated result with per-check details
+      def verify(dkim_selectors: [])
+        spf_result = verify_spf
+        dmarc_result = verify_dmarc
+        dkim_results = dkim_selectors.map { |selector| [selector, verify_dkim(selector)] }.to_h
+
+        all_errors = spf_result.errors + dmarc_result.errors +
+          dkim_results.values.flat_map(&:errors)
+        all_warnings = spf_result.warnings + dmarc_result.warnings +
+          dkim_results.values.flat_map(&:warnings)
+
+        Result.new(
+          spf: spf_result,
+          dmarc: dmarc_result,
+          dkim: dkim_results,
+          errors: all_errors,
+          warnings: all_warnings
+        )
+      end
+
+      # Verify SPF record for the zone
+      #
+      # Fetches TXT records at the zone root and filters for v=spf1 records.
+      # Validates against RFC 7208: single record, valid syntax, <=10 DNS lookups.
+      #
+      # @return [CheckResult] with :lookup_count in details
+      def verify_spf
+        errors = []
+        warnings = []
+
+        txt_records = fetch_txt_records("@")
+        spf_records = txt_records.select { |r| r.start_with?("v=spf1") }
+
+        if spf_records.empty?
+          return CheckResult.new(record: nil, valid: false,
+            errors: ["No SPF record found"], warnings: [], details: {})
+        end
+
+        if spf_records.length > 1
+          return CheckResult.new(record: spf_records, valid: false,
+            errors: ["Multiple SPF records found (RFC 7208 violation)"],
+            warnings: [], details: {})
+        end
+
+        spf = spf_records.first
+
+        # Validate syntax
+        if spf.match?(/\ball\b/) && !spf.match?(/[~\-+?]all\s*$/)
+          warnings << "SPF 'all' mechanism should be at the end"
+        end
+
+        if spf.include?(";")
+          warnings << "SPF record contains semicolons (check if intentional)"
+        end
+
+        # Count DNS lookups
+        lookup_count = count_spf_lookups(spf)
+        if lookup_count > 10
+          errors << "SPF has #{lookup_count} DNS lookups (max 10 allowed per RFC 7208)"
+        elsif lookup_count > 8
+          warnings << "SPF has #{lookup_count} DNS lookups (approaching limit of 10)"
+        end
+
+        CheckResult.new(
+          record: spf, valid: errors.empty?, errors: errors, warnings: warnings,
+          details: {lookup_count: lookup_count}
+        )
+      end
+
+      # Verify DMARC record for the zone
+      #
+      # Fetches TXT records at _dmarc.{zone} and validates syntax,
+      # required p= tag, and recommended rua= tag.
+      #
+      # @return [CheckResult] with :policy and :tags in details
+      def verify_dmarc
+        errors = []
+        warnings = []
+
+        txt_records = fetch_txt_records("_dmarc")
+
+        if txt_records.empty?
+          return CheckResult.new(record: nil, valid: true,
+            errors: [],
+            warnings: ["No DMARC record found (recommended for email authentication)"],
+            details: {})
+        end
+
+        if txt_records.length > 1
+          return CheckResult.new(record: txt_records, valid: false,
+            errors: ["Multiple DMARC records found"], warnings: [], details: {})
+        end
+
+        dmarc = txt_records.first
+
+        unless dmarc.start_with?("v=DMARC1")
+          return CheckResult.new(record: dmarc, valid: false,
+            errors: ["DMARC record doesn't start with 'v=DMARC1'"],
+            warnings: [], details: {})
+        end
+
+        tags = parse_dmarc_tags(dmarc)
+
+        if tags["p"]
+          unless VALID_DMARC_POLICIES.include?(tags["p"])
+            errors << "Invalid DMARC policy: #{tags["p"]}"
+          end
+        else
+          errors << "DMARC record missing required 'p' tag"
+        end
+
+        unless tags["rua"]
+          warnings << "DMARC record missing 'rua' tag (no aggregate reports)"
+        end
+
+        CheckResult.new(
+          record: dmarc, valid: errors.empty?, errors: errors, warnings: warnings,
+          details: {policy: tags["p"], tags: tags}
+        )
+      end
+
+      # Verify DKIM record for a specific selector
+      #
+      # Fetches TXT records at {selector}._domainkey.{zone} and validates
+      # the presence of v=DKIM1 and a valid base64 public key.
+      #
+      # @param selector [String] the DKIM selector (e.g., "google", "mailchimp")
+      # @return [CheckResult]
+      def verify_dkim(selector)
+        errors = []
+        warnings = []
+
+        txt_records = fetch_txt_records("#{selector}._domainkey")
+
+        if txt_records.empty?
+          return CheckResult.new(record: nil, valid: false,
+            errors: ["No DKIM record found for selector '#{selector}'"],
+            warnings: [], details: {selector: selector})
+        end
+
+        dkim = txt_records.join
+
+        unless dkim.match?(/v=DKIM1/i)
+          return CheckResult.new(record: dkim, valid: false,
+            errors: ["DKIM record doesn't contain 'v=DKIM1'"],
+            warnings: warnings, details: {selector: selector})
+        end
+
+        key_match = dkim.match(/p=([A-Za-z0-9+\/=]+)/)
+        unless key_match
+          return CheckResult.new(record: dkim, valid: false,
+            errors: ["DKIM record missing or invalid public key (p= tag)"],
+            warnings: warnings, details: {selector: selector})
+        end
+
+        # Validate base64 encoding (without requiring the base64 gem)
+        key = key_match[1]
+        unless valid_base64?(key)
+          errors << "DKIM public key is not valid base64"
+        end
+
+        CheckResult.new(
+          record: dkim, valid: errors.empty?, errors: errors, warnings: warnings,
+          details: {selector: selector, key_length: key.length}
+        )
+      end
+
+      private
+
+      # Fetch TXT record data from the DNS API
+      #
+      # @param host [String] the hostname within the zone
+      # @return [Array<String>] array of TXT record data values
+      def fetch_txt_records(host)
+        response = @dns.get_record(@zone, host, "TXT")
+        records = response["records"] || []
+        records.map { |r| r["data"] }
+      rescue MythicBeasts::NotFoundError
+        []
+      end
+
+      # Count DNS lookup mechanisms in an SPF record
+      #
+      # @param spf [String] the SPF record text
+      # @return [Integer] number of DNS-querying mechanisms
+      def count_spf_lookups(spf)
+        SPF_LOOKUP_MECHANISMS.sum { |mechanism| spf.scan(/\b#{mechanism}[:\s]/i).length }
+      end
+
+      # Validate strict base64 encoding without requiring the base64 gem
+      #
+      # @param str [String] the string to validate
+      # @return [Boolean] true if valid base64
+      def valid_base64?(str)
+        return false if str.empty?
+        return false unless str.match?(/\A[A-Za-z0-9+\/]*={0,2}\z/)
+        str.length % 4 == 0
+      end
+
+      # Parse DMARC tag-value pairs
+      #
+      # @param dmarc [String] the DMARC record text
+      # @return [Hash<String, String>] tag => value pairs
+      def parse_dmarc_tags(dmarc)
+        tags = {}
+        dmarc.gsub(/v=DMARC1;?\s*/, "").split(";").each do |tag|
+          next if tag.strip.empty?
+          key, value = tag.split("=", 2).map(&:strip)
+          tags[key] = value if key && value
+        end
+        tags
+      end
+    end
+  end
+end

data/lib/mythic_beasts/dns.rb

@@ -1,3 +1,5 @@
+require_relative "dns/email_auth"
+
 module MythicBeasts
   class DNS
     attr_reader :client
@@ -72,5 +74,39 @@ module MythicBeasts
     def create_txt_record(zone, host, text, ttl: 300)
       create_records(zone, [{host: host, ttl: ttl, type: "TXT", data: text}])
     end
+
+    # Verify all email authentication records (SPF, DKIM, DMARC) for a zone
+    #
+    # @param zone [String] the domain to verify
+    # @param dkim_selectors [Array<String>] DKIM selectors to check
+    # @return [MythicBeasts::DNS::EmailAuth::Result]
+    def verify_email_auth(zone, dkim_selectors: [])
+      EmailAuth.new(self, zone).verify(dkim_selectors: dkim_selectors)
+    end
+
+    # Verify SPF record for a zone
+    #
+    # @param zone [String] the domain to verify
+    # @return [MythicBeasts::DNS::EmailAuth::CheckResult]
+    def verify_spf(zone)
+      EmailAuth.new(self, zone).verify_spf
+    end
+
+    # Verify DMARC record for a zone
+    #
+    # @param zone [String] the domain to verify
+    # @return [MythicBeasts::DNS::EmailAuth::CheckResult]
+    def verify_dmarc(zone)
+      EmailAuth.new(self, zone).verify_dmarc
+    end
+
+    # Verify DKIM record for a specific selector
+    #
+    # @param zone [String] the domain to verify
+    # @param selector [String] the DKIM selector
+    # @return [MythicBeasts::DNS::EmailAuth::CheckResult]
+    def verify_dkim(zone, selector)
+      EmailAuth.new(self, zone).verify_dkim(selector)
+    end
   end
 end

data/lib/mythic_beasts/version.rb

@@ -1,3 +1,3 @@
 module MythicBeasts
-  VERSION = "0.2.0"
+  VERSION = "1.0.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mythic-beasts
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - James Inman
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +178,7 @@ files:
 - lib/mythic_beasts/auth.rb
 - lib/mythic_beasts/client.rb
 - lib/mythic_beasts/dns.rb
+- lib/mythic_beasts/dns/email_auth.rb
 - lib/mythic_beasts/errors.rb
 - lib/mythic_beasts/proxy.rb
 - lib/mythic_beasts/version.rb
@@ -189,7 +204,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.7.2
+rubygems_version: 4.0.7
 specification_version: 4
 summary: Ruby client for Mythic Beasts API
 test_files: []