purl 1.0.0 → 1.1.1

data/SECURITY.md

@@ -0,0 +1,164 @@
+# Security Policy
+
+## Supported Versions
+
+We actively support and provide security updates for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+The Purl team takes security seriously. If you discover a security vulnerability, please follow these steps:
+
+### 1. Do NOT Create a Public Issue
+
+Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
+
+### 2. Report Privately
+
+Send a detailed report to **andrew@ecosyste.ms** with:
+
+- **Subject**: `[SECURITY] Purl Ruby - [Brief Description]`
+- **Description** of the vulnerability
+- **Steps to reproduce** the issue
+- **Potential impact** assessment
+- **Suggested fix** (if you have one)
+- **Your contact information** for follow-up
+
+### 3. What to Include
+
+Please provide as much information as possible:
+
+```
+- Affected versions
+- Attack vectors
+- Proof of concept (if safe to share)
+- Environmental details (Ruby version, OS, etc.)
+- Any relevant configuration details
+```
+
+## Response Process
+
+### Initial Response
+
+- **24-48 hours**: We will acknowledge receipt of your report
+- **Initial assessment**: Within 1 week of acknowledgment
+- **Status updates**: Weekly until resolution
+
+### Investigation
+
+We will:
+1. **Confirm** the vulnerability exists
+2. **Assess** the severity and impact
+3. **Develop** a fix and mitigation strategy
+4. **Test** the fix thoroughly
+5. **Coordinate** disclosure timeline
+
+### Resolution
+
+- **High/Critical**: Immediate fix and release
+- **Medium**: Fix within 30 days
+- **Low**: Fix in next regular release cycle
+
+## Security Considerations
+
+### Input Validation
+
+The Purl library processes Package URL strings and performs:
+
+- **Scheme validation**: Ensures proper `pkg:` prefix
+- **Component parsing**: Validates type, namespace, name, version
+- **URI encoding**: Handles percent-encoded characters
+- **Qualifier parsing**: Processes key-value parameters
+
+### Potential Risk Areas
+
+Areas that warrant security attention:
+
+1. **URL Parsing**: Malformed URLs could cause parsing errors
+2. **Regular Expressions**: Complex patterns may be vulnerable to ReDoS
+3. **JSON Processing**: Configuration files require safe parsing
+4. **Network Requests**: Registry URL generation involves external URLs
+
+### Safe Usage Practices
+
+When using Purl in applications:
+
+- **Validate input**: Don't trust user-provided PURL strings
+- **Handle errors**: Properly catch and handle parsing exceptions
+- **Sanitize output**: Be careful when displaying parsed components
+- **Rate limiting**: If parsing many PURLs, implement appropriate limits
+
+## Disclosure Policy
+
+### Coordinated Disclosure
+
+We follow coordinated disclosure principles:
+
+1. **Private reporting** allows us to fix issues before public disclosure
+2. **Reasonable timeline** for fixes (typically 90 days maximum)
+3. **Credit and recognition** for responsible reporters
+4. **Public disclosure** after fixes are available
+
+### Public Disclosure
+
+After a fix is released:
+
+1. **Security advisory** published on GitHub
+2. **CVE requested** if applicable
+3. **Release notes** include security information
+4. **Community notification** through appropriate channels
+
+## Security Updates
+
+### Notification Channels
+
+Security updates are announced through:
+
+- **GitHub Security Advisories**
+- **RubyGems security alerts**
+- **Release notes and CHANGELOG**
+- **Project README updates**
+
+### Update Recommendations
+
+To stay secure:
+
+- **Monitor** our security advisories
+- **Update regularly** to the latest version
+- **Review** release notes for security fixes
+- **Subscribe** to GitHub notifications for this repository
+
+## Bug Bounty
+
+Currently, we do not offer a formal bug bounty program. However, we deeply appreciate security researchers who help improve the project's security posture.
+
+### Recognition
+
+Contributors who responsibly disclose security issues will be:
+
+- **Credited** in security advisories (with permission)
+- **Mentioned** in release notes
+- **Recognized** in project documentation
+- **Thanked** publicly (unless anonymity is requested)
+
+## Contact Information
+
+**Security Contact**: andrew@ecosyste.ms
+
+**PGP Key**: Available upon request for encrypted communications
+
+**Response Time**: We aim to acknowledge security reports within 24-48 hours
+
+## Additional Resources
+
+- [PURL Specification Security Considerations](https://github.com/package-url/purl-spec)
+- [Ruby Security Best Practices](https://guides.rubyonrails.org/security.html)
+- [OWASP Secure Coding Practices](https://owasp.org/www-project-secure-coding-practices-quick-reference-guide/)
+
+---
+
+Thank you for helping keep Purl and its users safe!

data/lib/purl/errors.rb

@@ -5,9 +5,31 @@ module Purl
   class Error < StandardError; end
 
   # Validation errors for PURL components
+  #
+  # Contains additional context about which component failed validation
+  # and what rule was violated.
+  #
+  # @example
+  #   begin
+  #     PackageURL.new(type: "123invalid", name: "test")
+  #   rescue ValidationError => e
+  #     puts e.component  # :type
+  #     puts e.rule       # "cannot start with number" 
+  #   end
   class ValidationError < Error
-    attr_reader :component, :value, :rule
+    # @return [Symbol, nil] the PURL component that failed validation
+    attr_reader :component
+    
+    # @return [Object, nil] the value that failed validation
+    attr_reader :value
+    
+    # @return [String, nil] the validation rule that was violated
+    attr_reader :rule
 
+    # @param message [String] error message
+    # @param component [Symbol, nil] component that failed validation
+    # @param value [Object, nil] value that failed validation  
+    # @param rule [String, nil] validation rule that was violated
     def initialize(message, component: nil, value: nil, rule: nil)
       super(message)
       @component = component
@@ -19,40 +41,71 @@ module Purl
   # Parsing errors for malformed PURL strings
   class ParseError < Error; end
 
-  # Specific validation errors
+  # Specific validation errors for PURL components
+  
+  # Raised when a PURL type is invalid
   class InvalidTypeError < ValidationError; end
+  
+  # Raised when a PURL name is invalid
   class InvalidNameError < ValidationError; end
+  
+  # Raised when a PURL namespace is invalid
   class InvalidNamespaceError < ValidationError; end
+  
+  # Raised when a PURL qualifier is invalid
   class InvalidQualifierError < ValidationError; end
+  
+  # Raised when a PURL version is invalid
   class InvalidVersionError < ValidationError; end
+  
+  # Raised when a PURL subpath is invalid
   class InvalidSubpathError < ValidationError; end
 
   # Parsing-specific errors
+  
+  # Raised when a PURL string doesn't start with "pkg:"
   class InvalidSchemeError < ParseError; end
+  
+  # Raised when a PURL string is malformed
   class MalformedUrlError < ParseError; end
 
   # Registry URL generation errors
+  #
+  # Contains additional context about which type caused the error.
   class RegistryError < Error
+    # @return [String, nil] the PURL type that caused the error
     attr_reader :type
 
+    # @param message [String] error message
+    # @param type [String, nil] PURL type that caused the error
     def initialize(message, type: nil)
       super(message)
       @type = type
     end
   end
 
+  # Raised when trying to generate registry URLs for unsupported types
   class UnsupportedTypeError < RegistryError
+    # @return [Array<String>] list of supported types
     attr_reader :supported_types
 
+    # @param message [String] error message
+    # @param type [String, nil] unsupported type
+    # @param supported_types [Array<String>] list of supported types
     def initialize(message, type: nil, supported_types: [])
       super(message, type: type)
       @supported_types = supported_types
     end
   end
 
+  # Raised when required registry information is missing
   class MissingRegistryInfoError < RegistryError
+    # @return [String, nil] the missing information (e.g., "namespace")
     attr_reader :missing
 
+    # @param message [String] error message
+    # @param type [String, nil] PURL type
+    # @param missing [String, nil] what information is missing
     def initialize(message, type: nil, missing: nil)
       super(message, type: type)
       @missing = missing
@@ -60,5 +113,6 @@ module Purl
   end
 
   # Legacy compatibility - matches packageurl-ruby's exception name
+  # @deprecated Use {ParseError} instead
   InvalidPackageURL = ParseError
 end

data/lib/purl/package_url.rb

@@ -3,12 +3,74 @@
 require "uri"
 
 module Purl
+  # Represents a Package URL (PURL) - a mostly universal standard to reference 
+  # a software package in a uniform way across many tools, programming languages
+  # and ecosystems.
+  #
+  # A PURL has the following components:
+  # - +type+: the package type (e.g., "gem", "npm", "maven")
+  # - +namespace+: optional namespace/scope (e.g., "@babel" for npm)
+  # - +name+: the package name (required)
+  # - +version+: optional version
+  # - +qualifiers+: optional key-value pairs
+  # - +subpath+: optional path within the package
+  #
+  # @example Creating a PackageURL
+  #   purl = PackageURL.new(
+  #     type: "gem",
+  #     name: "rails", 
+  #     version: "7.0.0"
+  #   )
+  #   puts purl.to_s  # "pkg:gem/rails@7.0.0"
+  #
+  # @example Parsing a PURL string
+  #   purl = PackageURL.parse("pkg:npm/@babel/core@7.0.0")
+  #   puts purl.namespace  # "@babel"
+  #   puts purl.name       # "core"
+  #
+  # @see https://github.com/package-url/purl-spec PURL Specification
   class PackageURL
-    attr_reader :type, :namespace, :name, :version, :qualifiers, :subpath
+    # @return [String] the package type (e.g., "gem", "npm", "maven")
+    attr_reader :type
+    
+    # @return [String, nil] the package namespace/scope
+    attr_reader :namespace
+    
+    # @return [String] the package name
+    attr_reader :name
+    
+    # @return [String, nil] the package version
+    attr_reader :version
+    
+    # @return [Hash<String, String>, nil] key-value qualifier pairs
+    attr_reader :qualifiers
+    
+    # @return [String, nil] subpath within the package
+    attr_reader :subpath
 
     VALID_TYPE_CHARS = /\A[a-zA-Z0-9\.\+\-]+\z/
     VALID_QUALIFIER_KEY_CHARS = /\A[a-zA-Z0-9\.\-_]+\z/
 
+    # Create a new PackageURL instance
+    #
+    # @param type [String, Symbol] the package type (required)
+    # @param name [String] the package name (required)
+    # @param namespace [String, nil] optional namespace/scope
+    # @param version [String, nil] optional version
+    # @param qualifiers [Hash, nil] optional key-value qualifier pairs
+    # @param subpath [String, nil] optional subpath within package
+    #
+    # @raise [InvalidTypeError] if type is invalid
+    # @raise [InvalidNameError] if name is invalid
+    # @raise [ValidationError] if any component fails type-specific validation
+    #
+    # @example
+    #   purl = PackageURL.new(
+    #     type: "npm",
+    #     namespace: "@babel",
+    #     name: "core",
+    #     version: "7.0.0"
+    #   )
     def initialize(type:, name:, namespace: nil, version: nil, qualifiers: nil, subpath: nil)
       @type = validate_and_normalize_type(type)
       @name = validate_name(name)
@@ -21,6 +83,25 @@ module Purl
       validate_type_specific_rules
     end
 
+    # Parse a PURL string into a PackageURL object
+    #
+    # @param purl_string [String] PURL string starting with "pkg:"
+    # @return [PackageURL] parsed package URL object
+    # @raise [InvalidSchemeError] if string doesn't start with "pkg:"
+    # @raise [MalformedUrlError] if string is malformed
+    # @raise [ValidationError] if parsed components fail validation
+    #
+    # @example Basic parsing
+    #   purl = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   puts purl.type     # "gem"
+    #   puts purl.name     # "rails"
+    #   puts purl.version  # "7.0.0"
+    #
+    # @example Complex parsing with all components
+    #   purl = PackageURL.parse("pkg:npm/@babel/core@7.0.0?arch=x64#lib/index.js")
+    #   puts purl.namespace   # "@babel"
+    #   puts purl.qualifiers  # {"arch" => "x64"}
+    #   puts purl.subpath     # "lib/index.js"
     def self.parse(purl_string)
       raise InvalidSchemeError, "PURL must start with 'pkg:'" unless purl_string.start_with?("pkg:")
 
@@ -134,6 +215,13 @@ module Purl
       )
     end
 
+    # Convert the PackageURL to its canonical string representation
+    #
+    # @return [String] canonical PURL string
+    #
+    # @example
+    #   purl = PackageURL.new(type: "gem", name: "rails", version: "7.0.0")
+    #   puts purl.to_s  # "pkg:gem/rails@7.0.0"
     def to_s
       result = "pkg:#{type.downcase}"
       
@@ -183,6 +271,15 @@ module Purl
       result
     end
 
+    # Convert the PackageURL to a hash representation
+    #
+    # @return [Hash<Symbol, Object>] hash with component keys and values
+    #
+    # @example
+    #   purl = PackageURL.new(type: "gem", name: "rails", version: "7.0.0")
+    #   hash = purl.to_h
+    #   # => {:type=>"gem", :namespace=>nil, :name=>"rails", :version=>"7.0.0", 
+    #   #     :qualifiers=>nil, :subpath=>nil}
     def to_h
       {
         type: type,
@@ -194,26 +291,75 @@ module Purl
       }
     end
 
+    # Compare two PackageURL objects for equality
+    #
+    # Two PURLs are equal if their canonical string representations are identical.
+    #
+    # @param other [Object] object to compare with
+    # @return [Boolean] true if equal, false otherwise
+    #
+    # @example
+    #   purl1 = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   purl2 = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   puts purl1 == purl2  # true
     def ==(other)
       return false unless other.is_a?(PackageURL)
       
       to_s == other.to_s
     end
 
+    # Generate hash code for the PackageURL
+    #
+    # @return [Integer] hash code based on canonical string representation
     def hash
       to_s.hash
     end
 
     # Pattern matching support for Ruby 2.7+
+    #
+    # Allows destructuring PackageURL in pattern matching.
+    #
+    # @return [Array] array of [type, namespace, name, version, qualifiers, subpath]
+    #
+    # @example Ruby 2.7+ pattern matching
+    #   case purl
+    #   in ["gem", nil, name, version, nil, nil]
+    #     puts "Simple gem: #{name} v#{version}"
+    #   end
     def deconstruct
       [type, namespace, name, version, qualifiers, subpath]
     end
 
+    # Pattern matching support for Ruby 2.7+ (hash patterns)
+    #
+    # @param keys [Array<Symbol>, nil] keys to extract, or nil for all keys
+    # @return [Hash<Symbol, Object>] hash with requested keys
+    #
+    # @example Ruby 2.7+ hash pattern matching
+    #   case purl
+    #   in {type: "gem", name:, version:}
+    #     puts "Gem #{name} version #{version}"
+    #   end
     def deconstruct_keys(keys)
-      to_h.slice(*keys) if keys
+      return to_h.slice(*keys) if keys
       to_h
     end
 
+    # Create a new PackageURL with modified attributes
+    #
+    # @param changes [Hash] attributes to change
+    # @return [PackageURL] new PackageURL instance with changes applied
+    #
+    # @example
+    #   purl = PackageURL.parse("pkg:gem/rails@7.0.0")
+    #   new_purl = purl.with(version: "7.1.0", qualifiers: {"arch" => "x64"})
+    #   puts new_purl.to_s  # "pkg:gem/rails@7.1.0?arch=x64"
+    def with(**changes)
+      current_attrs = to_h
+      new_attrs = current_attrs.merge(changes)
+      self.class.new(**new_attrs)
+    end
+
     private
 
     def validate_and_normalize_type(type)