purl 1.0.0 → 1.1.0

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/package_url.rb

@@ -210,10 +210,18 @@ module Purl
     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
+    # Usage: new_purl = purl.with(version: "2.0.0", qualifiers: {"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)

data/lib/purl/registry_url.rb

@@ -24,29 +24,85 @@ module Purl
     end
 
     def self.build_pattern_config(type, config)
+      # Get the default registry for this type from parent config
+      type_config = load_types_config["types"][type]
+      default_registry = type_config["default_registry"]
+      
+      # Build full URLs from templates if we have a default registry
+      route_patterns = []
+      if default_registry
+        # Add all template variations
+        if config["path_template"]
+          route_patterns << default_registry + config["path_template"]
+        end
+        if config["namespace_path_template"]
+          route_patterns << default_registry + config["namespace_path_template"]
+        end
+        if config["version_path_template"]
+          route_patterns << default_registry + config["version_path_template"]
+        end
+        if config["namespace_version_path_template"]
+          route_patterns << default_registry + config["namespace_version_path_template"]
+        end
+      end
+      # Fall back to legacy route_patterns if available
+      route_patterns = config["route_patterns"] if route_patterns.empty? && config["route_patterns"]
+      
+      # Build reverse regex from template or use legacy format
+      reverse_regex = nil
+      if config["reverse_regex"]
+        if config["reverse_regex"].start_with?("/") && default_registry
+          # Domain-agnostic pattern - combine with default registry domain
+          domain_pattern = default_registry.sub(/^https?:\/\//, '').gsub('.', '\\.')
+          reverse_regex = Regexp.new("^https?://#{domain_pattern}" + config["reverse_regex"])
+        else
+          # Legacy full pattern
+          reverse_regex = Regexp.new(config["reverse_regex"])
+        end
+      end
+      
       {
-        base_url: config["base_url"],
-        route_patterns: config["route_patterns"] || [],
-        reverse_regex: config["reverse_regex"] ? Regexp.new(config["reverse_regex"]) : nil,
-        pattern: build_generation_lambda(type, config),
-        reverse_parser: config["reverse_regex"] ? build_reverse_parser(type, config) : nil
+        base_url: config["base_url"] || (default_registry ? default_registry + config["path_template"]&.split('/:').first : nil),
+        route_patterns: route_patterns,
+        reverse_regex: reverse_regex,
+        pattern: build_generation_lambda(type, config, default_registry),
+        reverse_parser: reverse_regex ? build_reverse_parser(type, config) : nil
       }
     end
 
-    def self.build_generation_lambda(type, config)
+    # Load types config (needed for accessing default_registry)
+    def self.load_types_config
+      @types_config ||= begin
+        config_path = File.join(__dir__, "..", "..", "purl-types.json")
+        require "json"
+        JSON.parse(File.read(config_path))
+      end
+    end
+
+    def self.build_generation_lambda(type, config, default_registry = nil)
+      # Use base_url from config, or build from default_registry + path_template base
+      if config["base_url"]
+        base_url = config["base_url"]
+      elsif default_registry && config["path_template"]
+        # Extract the base path from the template (everything before first :parameter)
+        base_path = config["path_template"].split('/:').first
+        base_url = default_registry + base_path
+      else
+        return nil
+      end
       case type
       when "npm"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "composer", "maven", "swift"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
             raise MissingRegistryInfoError.new(
               "#{type.capitalize} packages require a namespace",
@@ -58,42 +114,42 @@ module Purl
       when "golang"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "pypi"
-        ->(purl) { "#{config["base_url"]}/#{purl.name}/" }
+        ->(purl) { "#{base_url}/#{purl.name}/" }
       when "hackage"
         ->(purl) do
           if purl.version
-            "#{config["base_url"]}/#{purl.name}-#{purl.version}"
+            "#{base_url}/#{purl.name}-#{purl.version}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "deno"
         ->(purl) do
           if purl.version
-            "#{config["base_url"]}/#{purl.name}@#{purl.version}"
+            "#{base_url}/#{purl.name}@#{purl.version}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "clojars"
         ->(purl) do
           if purl.namespace
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}"
           else
-            "#{config["base_url"]}/#{purl.name}"
+            "#{base_url}/#{purl.name}"
           end
         end
       when "elm"
         ->(purl) do
           if purl.namespace
             version = purl.version || "latest"
-            "#{config["base_url"]}/#{purl.namespace}/#{purl.name}/#{version}"
+            "#{base_url}/#{purl.namespace}/#{purl.name}/#{version}"
           else
             raise MissingRegistryInfoError.new(
               "Elm packages require a namespace",
@@ -103,7 +159,7 @@ module Purl
           end
         end
       else
-        ->(purl) { "#{config["base_url"]}/#{purl.name}" }
+        ->(purl) { "#{base_url}/#{purl.name}" }
       end
     end
 
@@ -177,6 +233,67 @@ module Purl
           version = match[3] unless match[3] == "latest"
           { type: type, namespace: namespace, name: name, version: version }
         end
+      when "cocoapods"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "composer"
+        ->(match) do
+          namespace = match[1]
+          name = match[2]
+          { type: type, namespace: namespace, name: name, version: nil }
+        end
+      when "conda"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "cpan"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "hex"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "nuget"
+        ->(match) do
+          name = match[1]
+          version = match[2] # from /version pattern
+          { type: type, namespace: nil, name: name, version: version }
+        end
+      when "pub"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "swift"
+        ->(match) do
+          namespace = match[1]
+          name = match[2]
+          { type: type, namespace: namespace, name: name, version: nil }
+        end
+      when "bioconductor"
+        ->(match) do
+          name = match[1]
+          { type: type, namespace: nil, name: name, version: nil }
+        end
+      when "clojars"
+        ->(match) do
+          if match[1] && match[2]
+            # Has namespace: clojars.org/namespace/name
+            namespace = match[1]
+            name = match[2]
+          else
+            # No namespace: clojars.org/name
+            namespace = nil
+            name = match[1] || match[2]
+          end
+          { type: type, namespace: namespace, name: name, version: nil }
+        end
       else
         ->(match) do
           { type: type, namespace: nil, name: match[1], version: nil }
@@ -187,8 +304,8 @@ module Purl
     # Registry patterns loaded from JSON configuration
     REGISTRY_PATTERNS = load_registry_patterns.freeze
 
-    def self.generate(purl)
-      new(purl).generate
+    def self.generate(purl, base_url: nil)
+      new(purl).generate(base_url: base_url)
     end
 
     def self.supported_types
@@ -199,9 +316,49 @@ module Purl
       REGISTRY_PATTERNS.key?(type.to_s.downcase)
     end
 
-    def self.from_url(registry_url)
-      # Try to parse the registry URL back into a PURL
-      REGISTRY_PATTERNS.each do |type, config|
+    def self.from_url(registry_url, type: nil)
+      # If type is specified, try that specific type first with domain-agnostic parsing
+      if type
+        normalized_type = type.to_s.downcase
+        config = REGISTRY_PATTERNS[normalized_type]
+        
+        if config && config[:reverse_regex] && config[:reverse_parser]
+          # Create a domain-agnostic version of the regex by replacing the base domain
+          original_regex = config[:reverse_regex].source
+          
+          # For simplified JSON patterns that start with /, create domain-agnostic regex
+          domain_agnostic_regex = nil
+          if original_regex.start_with?("/")
+            # Domain-agnostic pattern - match any domain with this path
+            domain_agnostic_regex = Regexp.new("^https?://[^/]+" + original_regex)
+          else
+            # Legacy full regex pattern
+            if original_regex =~ /\^https?:\/\/[^\/]+(.+)$/
+              path_pattern = $1
+              # Create domain-agnostic regex that matches any domain with the same path structure
+              domain_agnostic_regex = Regexp.new("^https?://[^/]+" + path_pattern)
+            end
+          end
+            
+          if domain_agnostic_regex
+            match = registry_url.match(domain_agnostic_regex)
+            if match
+              parsed_data = config[:reverse_parser].call(match)
+              return PackageURL.new(
+                type: parsed_data[:type],
+                namespace: parsed_data[:namespace],
+                name: parsed_data[:name],
+                version: parsed_data[:version]
+              )
+            end
+          end
+        end
+        
+        # If specified type didn't work, fall through to normal domain-matching logic
+      end
+      
+      # Try to parse the registry URL back into a PURL using domain matching
+      REGISTRY_PATTERNS.each do |registry_type, config|
         next unless config[:reverse_regex] && config[:reverse_parser]
         
         match = registry_url.match(config[:reverse_regex])
@@ -216,8 +373,15 @@ module Purl
         end
       end
       
+      error_message = if type
+        "Unable to parse registry URL: #{registry_url} as type '#{type}'. " +
+        "URL structure doesn't match expected pattern for this type."
+      else
+        "Unable to parse registry URL: #{registry_url}. No matching pattern found."
+      end
+      
       raise UnsupportedTypeError.new(
-        "Unable to parse registry URL: #{registry_url}. No matching pattern found.",
+        error_message,
         supported_types: REGISTRY_PATTERNS.keys.select { |k| REGISTRY_PATTERNS[k][:reverse_regex] }
       )
     end
@@ -247,7 +411,7 @@ module Purl
       @purl = purl
     end
 
-    def generate
+    def generate(base_url: nil)
       pattern_config = REGISTRY_PATTERNS[@purl.type.downcase]
       
       unless pattern_config
@@ -259,7 +423,13 @@ module Purl
       end
 
       begin
-        pattern_config[:pattern].call(@purl)
+        if base_url
+          # Use custom base URL with the same URL structure
+          generate_with_custom_base_url(base_url, pattern_config)
+        else
+          # Use default base URL
+          pattern_config[:pattern].call(@purl)
+        end
       rescue MissingRegistryInfoError
         raise
       rescue => e
@@ -267,23 +437,87 @@ module Purl
       end
     end
 
-    def generate_with_version
-      base_url = generate
+    def generate_with_version(base_url: nil)
+      registry_url = generate(base_url: base_url)
       
       case @purl.type.downcase
       when "npm"
-        @purl.version ? "#{base_url}/v/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/v/#{@purl.version}" : registry_url
       when "pypi"
-        @purl.version ? "#{base_url}#{@purl.version}/" : base_url
+        @purl.version ? "#{registry_url}#{@purl.version}/" : registry_url
       when "gem"
-        @purl.version ? "#{base_url}/versions/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/versions/#{@purl.version}" : registry_url
       when "maven"
-        @purl.version ? "#{base_url}/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/#{@purl.version}" : registry_url
       when "nuget"
-        @purl.version ? "#{base_url}/#{@purl.version}" : base_url
+        @purl.version ? "#{registry_url}/#{@purl.version}" : registry_url
       else
         # For other types, just return the base URL since version-specific URLs vary
-        base_url
+        registry_url
+      end
+    end
+
+    private
+
+    def generate_with_custom_base_url(custom_base_url, pattern_config)
+      
+      # Replace the base URL in the pattern lambda
+      case @purl.type.downcase
+      when "npm"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "composer", "maven", "swift"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          raise MissingRegistryInfoError.new(
+            "#{@purl.type.capitalize} packages require a namespace",
+            type: @purl.type,
+            missing: "namespace"
+          )
+        end
+      when "golang"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "pypi"
+        "#{custom_base_url}/#{@purl.name}/"
+      when "hackage"
+        if @purl.version
+          "#{custom_base_url}/#{@purl.name}-#{@purl.version}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "deno"
+        if @purl.version
+          "#{custom_base_url}/#{@purl.name}@#{@purl.version}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "clojars"
+        if @purl.namespace
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}"
+        else
+          "#{custom_base_url}/#{@purl.name}"
+        end
+      when "elm"
+        if @purl.namespace
+          version = @purl.version || "latest"
+          "#{custom_base_url}/#{@purl.namespace}/#{@purl.name}/#{version}"
+        else
+          raise MissingRegistryInfoError.new(
+            "Elm packages require a namespace",
+            type: @purl.type,
+            missing: "namespace"
+          )
+        end
+      else
+        "#{custom_base_url}/#{@purl.name}"
       end
     end
 
@@ -294,12 +528,12 @@ module Purl
 
   # Add registry URL generation methods to PackageURL
   class PackageURL
-    def registry_url
-      RegistryURL.generate(self)
+    def registry_url(base_url: nil)
+      RegistryURL.generate(self, base_url: base_url)
     end
 
-    def registry_url_with_version
-      RegistryURL.new(self).generate_with_version
+    def registry_url_with_version(base_url: nil)
+      RegistryURL.new(self).generate_with_version(base_url: base_url)
     end
 
     def supports_registry_url?

data/lib/purl/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Purl
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/purl.rb

@@ -26,8 +26,10 @@ module Purl
   end
 
   # Convenience method for parsing registry URLs back to PURLs
-  def self.from_registry_url(registry_url)
-    RegistryURL.from_url(registry_url)
+  # @param registry_url [String] The registry URL to parse
+  # @param type [String, Symbol, nil] Optional type hint for custom domains
+  def self.from_registry_url(registry_url, type: nil)
+    RegistryURL.from_url(registry_url, type: type)
   end
 
   # Returns all known PURL types
@@ -56,6 +58,9 @@ module Purl
     {
       type: normalized_type,
       known: known_type?(normalized_type),
+      description: type_description(normalized_type),
+      default_registry: default_registry(normalized_type),
+      examples: type_examples(normalized_type),
       registry_url_generation: RegistryURL.supports?(normalized_type),
       reverse_parsing: RegistryURL.supported_reverse_types.include?(normalized_type),
       route_patterns: RegistryURL.route_patterns_for(normalized_type)
@@ -95,6 +100,14 @@ module Purl
     config ? config["description"] : nil
   end
 
+  # Get examples for a type
+  def self.type_examples(type)
+    config = type_config(type)
+    return [] unless config
+    
+    config["examples"] || []
+  end
+
   # Get registry configuration for a type
   def self.registry_config(type)
     config = type_config(type)
@@ -103,6 +116,14 @@ module Purl
     config["registry_config"]
   end
 
+  # Get default registry URL for a type
+  def self.default_registry(type)
+    config = type_config(type)
+    return nil unless config
+    
+    config["default_registry"]
+  end
+
   # Get metadata about the types configuration
   def self.types_config_metadata
     config = load_types_config
@@ -112,7 +133,8 @@ module Purl
       source: config["source"],
       last_updated: config["last_updated"],
       total_types: config["types"].keys.length,
-      registry_supported_types: config["types"].select { |_, v| v["registry_config"] }.keys.length
+      registry_supported_types: config["types"].select { |_, v| v["registry_config"] }.keys.length,
+      types_with_default_registry: config["types"].select { |_, v| v["default_registry"] }.keys.length
     }
   end
 end