well_known 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 17b812b145ef2ea1ad10949c21c2b440086f208867733d3719c2568546d0444a
+  data.tar.gz: a9d6084c1f1a33f845ee31fbfb001cf6e6d8b0ba5df7992f64d376abe2ac3b52
+SHA512:
+  metadata.gz: dadcad1d3461db7d1210baee18b24a492aad3fae4cdcee26a9d2234f14895ad21919c32725f680ab886401de950ded3e3c9e358901ababe1117230a59b527994
+  data.tar.gz: 35709dd5e37484e4d2d9245c9c6fd680ac5eec54d2e9026029fb8c8560b80a082c940dbceca3c39486fbf4acf5d1e72661f354edf7e64ffc81518e769d2f8e14

data/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this gem uses to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-02-18
+
+### Added
+
+- Initial release
+- Client for fetching `/.well-known/{suffix}` URLs from any domain
+- Full IANA well-known URI registry (96 entries)
+- Registry lookup via `.registered?`, `.find`, `.entries`, `.suffixes`
+- Response object with body, status, content_type, headers
+- Thorough test suite

data/README.md

@@ -0,0 +1,181 @@
+# WellKnown
+
+A Ruby gem client for discovering and fetching
+[well-known URLs](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml)
+(RFC 8615) from any domain.
+Includes the full IANA well-known URI registry.
+
+## Features
+
+- Pure Ruby  - Works with any Ruby framework or plain scripts
+- Client     - Fetch `/.well-known/{suffix}` from any domain
+- Registry   - Full IANA well-known URI registry (96 entries)
+- Lookup     - Check if a URI suffix is IANA-registered
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'well_known'
+```
+
+And then execute:
+
+```ruby
+bundle install
+```
+
+Or install it yourself as:
+
+```ruby
+gem install well_known
+```
+
+## Usage
+
+### Client
+
+Fetch well-known URLs from any domain:
+
+```ruby
+require 'well_known'
+
+client = WellKnown::Client.new
+
+# Fetch nodeinfo
+response = client.fetch 'mastodon.social', 'nodeinfo'
+puts response.status       # => 200
+puts response.body         # => '{"links":[...]}'
+puts response.content_type # => 'application/json'
+
+# Fetch host-meta
+response = client.fetch 'mastodon.social', 'host-meta'
+puts response.content_type # => 'application/xrd+xml'
+
+# Fetch security.txt
+response = client.fetch 'example.com', 'security.txt'
+puts response.body # => 'Contact: security@example.com'
+```
+
+#### Build URLs Without Fetching
+
+```ruby
+client = WellKnown::Client.new
+
+client.url_for 'mastodon.social', 'nodeinfo'
+# => 'https://mastodon.social/.well-known/nodeinfo'
+
+client.url_for 'example.com', 'webfinger'
+# => 'https://example.com/.well-known/webfinger'
+```
+
+#### Client Options
+
+```ruby
+# Custom timeout (default: 10 seconds)
+client = WellKnown::Client.new timeout: 5
+
+# Disable redirect following (default: true)
+client = WellKnown::Client.new follow_redirects: false
+```
+
+#### Convenience Method
+
+```ruby
+client   = WellKnown.client
+response = client.fetch 'example.com', 'nodeinfo'
+```
+
+### Registry
+
+Check the IANA well-known URI registry:
+
+```ruby
+require 'well_known'
+
+# Check if a suffix is registered
+WellKnown::Registry.registered? 'nodeinfo'  # => true
+WellKnown::Registry.registered? 'webfinger' # => true
+WellKnown::Registry.registered? 'made-up'   # => false
+
+# Get details for a registered suffix
+WellKnown::Registry.find 'nodeinfo'
+# => { change_controller: 'NodeInfo Developer Community', reference: 'NodeInfo Diaspora' }
+
+WellKnown::Registry.find 'webfinger'
+# => { change_controller: 'IETF', reference: 'RFC 7033' }
+
+# List all registered suffixes
+WellKnown::Registry.suffixes
+# => ['acme-challenge', 'agent-card.json', 'amphtml', ...]
+
+# Get the full registry
+WellKnown::Registry.entries
+# => { 'acme-challenge' => { ... }, 'agent-card.json' => { ... }, ... }
+```
+
+### Response Object
+
+The `WellKnown::Response` object wraps the HTTP response:
+
+```ruby
+response = client.fetch 'example.com', 'nodeinfo'
+
+response.body         # => String - the response body
+response.status       # => Integer - HTTP status code (e.g., 200)
+response.content_type # => String - MIME type (e.g., 'application/json')
+response.headers      # => Hash - all response headers
+response.success?     # => Boolean - true if status is 2xx
+```
+
+## Error Handling
+
+```ruby
+begin
+  response = client.fetch 'example.com', 'nodeinfo'
+rescue WellKnown::FetchError => e
+  puts "Could not fetch: #{e.message}"
+rescue WellKnown::Error => e
+  puts "WellKnown error: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies.
+Then, run `rake spec` to run the tests.
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+### Running Tests
+
+```ruby
+bundle exec rspec
+```
+
+### Running RuboCop
+
+```ruby
+bundle exec rubocop
+```
+
+### Running All Checks
+
+```ruby
+bundle exec rake
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at the
+https://github.com/xoengineering/well_known repo.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).
+
+## References
+
+- [RFC 8615 - Well-Known URIs](https://tools.ietf.org/html/rfc8615)
+- [IANA Well-Known URI Registry](https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml)

data/lib/well_known/client.rb

@@ -0,0 +1,78 @@
+require 'http'
+require 'uri'
+
+module WellKnown
+  # Client for fetching well-known URLs from any domain
+  #
+  # @example Fetch nodeinfo
+  #   client = WellKnown::Client.new
+  #   response = client.fetch("mastodon.social", "nodeinfo")
+  #   puts response.body
+  class Client
+    WELL_KNOWN_PREFIX = '/.well-known/'.freeze
+
+    attr_reader :timeout, :follow_redirects
+
+    # Initialize a new client
+    # @param timeout [Integer] HTTP timeout in seconds (default: 10)
+    # @param follow_redirects [Boolean] Whether to follow HTTP redirects (default: true)
+    def initialize timeout: 10, follow_redirects: true
+      @timeout = timeout
+      @follow_redirects = follow_redirects
+    end
+
+    # Fetch a well-known URL for a domain
+    # @param domain [String] The domain to fetch from (e.g., "mastodon.social")
+    # @param suffix [String] The well-known URI suffix (e.g., "nodeinfo")
+    # @return [WellKnown::Response]
+    # @raise [WellKnown::FetchError] If the request fails
+    def fetch domain, suffix
+      url = url_for domain, suffix
+      response = http_client.get url
+
+      raise FetchError, "HTTP #{response.code}" unless response.status.success?
+
+      Response.new body:         response.body.to_s,
+                   status:       response.code,
+                   content_type: response.content_type.mime_type,
+                   headers:      response.headers.to_h
+    rescue HTTP::Error => e
+      raise FetchError, "HTTP request failed: #{e.message}"
+    end
+
+    # Discover all well-known URLs that respond successfully on a domain
+    # @param domain [String] The domain to scan (e.g., "mastodon.social")
+    # @param suffixes [Array<String>] URI suffixes to try (default: all IANA-registered suffixes)
+    # @return [Hash{String => WellKnown::Response}] suffix => response for each successful fetch
+    def discover_all domain, suffixes: Registry.suffixes
+      suffixes.each_with_object({}) do |suffix, results|
+        results[suffix] = fetch domain, suffix
+      rescue FetchError
+        next
+      end
+    end
+
+    # Build the well-known URL for a domain and suffix
+    # @param domain [String] The domain (e.g., "mastodon.social")
+    # @param suffix [String] The URI suffix (e.g., "nodeinfo")
+    # @return [String] The full URL
+    def url_for domain, suffix
+      domain = domain.delete_prefix 'https://'
+      domain = domain.delete_prefix 'http://'
+      domain = domain.chomp '/'
+
+      host = URI.parse("https://#{domain}").host
+      path = [WELL_KNOWN_PREFIX, suffix].join
+
+      URI::HTTPS.build(host: host, path: path).to_s
+    end
+
+    private
+
+    def http_client
+      client = HTTP.timeout timeout
+      client = client.follow if follow_redirects
+      client
+    end
+  end
+end

data/lib/well_known/errors.rb

@@ -0,0 +1,7 @@
+module WellKnown
+  # Base error class for all WellKnown errors
+  class Error < StandardError; end
+
+  # Raised when fetching a well-known URL fails
+  class FetchError < Error; end
+end

data/lib/well_known/registry.rb

@@ -0,0 +1,30 @@
+require 'yaml'
+
+module WellKnown
+  # IANA Well-Known URI registry
+  # https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml
+  module Registry
+    YAML_FILE = YAML.load_file File.expand_path 'registry.yml', __dir__
+    ENTRIES   = YAML_FILE.transform_values { it.transform_keys(&:to_sym) }.freeze
+
+    class << self
+      # Check if a URI suffix is registered in the IANA registry
+      # @param suffix [String]
+      # @return [Boolean]
+      def registered?(suffix) = ENTRIES.key? suffix
+
+      # Return all registered entries
+      # @return [Hash]
+      def entries = ENTRIES
+
+      # Find entry details for a given URI suffix
+      # @param suffix [String]
+      # @return [Hash, nil]
+      def find(suffix) = ENTRIES[suffix]
+
+      # Return all registered URI suffixes
+      # @return [Array<String>]
+      def suffixes = ENTRIES.keys
+    end
+  end
+end

data/lib/well_known/registry.yml

@@ -0,0 +1,376 @@
+---
+acme-challenge:
+  change_controller: IETF
+  reference: RFC 8555, Section 8.3
+
+agent-card.json:
+  change_controller: Linux Foundation
+  reference: A2A Project Specification
+
+amphtml:
+  change_controller: AMP Project (OpenJS Foundation)
+  reference: Google AMP Cache Update
+
+api-catalog:
+  change_controller: IETF
+  reference: RFC 9727
+
+appspecific:
+  change_controller: Bruce Leban
+  reference: well-known-uri-appspecific
+
+ashrae:
+  change_controller: ASHRAE
+  reference: BACnet Addenda Add-135-2012am
+
+assetlinks.json:
+  change_controller: Google Inc.
+  reference: Digital Asset Links
+
+broadband-labels:
+  change_controller: BITAG
+  reference: BITAG Broadband Labels
+
+brski:
+  change_controller: IETF
+  reference: RFC 8995
+
+caldav:
+  change_controller: IETF
+  reference: RFC 6764
+
+carddav:
+  change_controller: IETF
+  reference: RFC 6764
+
+change-password:
+  change_controller: W3C
+  reference: W3C WebAppSec Change Password
+
+cmp:
+  change_controller: IETF
+  reference: RFC 9811, RFC 9482
+
+coap:
+  change_controller: IETF
+  reference: RFC 8323
+
+coap-eap:
+  change_controller: IETF
+  reference: RFC 9820
+
+core:
+  change_controller: IETF
+  reference: RFC 6690
+
+csaf:
+  change_controller: OASIS Open
+  reference: CSAF Version 2.0
+
+csaf-aggregator:
+  change_controller: OASIS Open
+  reference: CSAF Version 2.0
+
+csvm:
+  change_controller: W3C
+  reference: W3C Tabular Data Model
+
+did.json:
+  change_controller: W3C CCG
+  reference: DID Method Web
+
+did-configuration.json:
+  change_controller: DIF
+  reference: DID Configuration
+
+dnt:
+  change_controller: W3C
+  reference: W3C Tracking DNT Status
+
+dnt-policy.txt:
+  change_controller: EFF
+  reference: EFF DNT Policy
+
+dots:
+  change_controller: IETF
+  reference: RFC 9132
+
+easy-proxy:
+  change_controller: The G3 Project
+  reference: G3 Project
+
+ecips:
+  change_controller: Wei Tang
+  reference: ECIPS URI Specification
+
+edhoc:
+  change_controller: IETF
+  reference: RFC 9528
+
+enterprise-network-security:
+  change_controller: ETSI TC CYBER
+  reference: ETSI TS 103 523-5
+
+enterprise-transport-security:
+  change_controller: ETSI TC CYBER
+  reference: ETSI TS 103 523-3
+
+est:
+  change_controller: IETF
+  reference: RFC 7030, RFC 9148
+
+funding-manifest-urls:
+  change_controller: floss.fund
+  reference: FundingJSON.org
+
+genid:
+  change_controller: W3C
+  reference: RDF 1.1 Concepts
+
+gnap-as-rs:
+  change_controller: IETF
+  reference: RFC 9767, Section 3.1
+
+gpc.json:
+  change_controller: Global Privacy Control Project
+  reference: GPC Specification
+
+gs1resolver:
+  change_controller: GS1
+  reference: GS1 Digital Link
+
+hoba:
+  change_controller: IETF
+  reference: RFC 7486, Section 6
+
+host-meta:
+  change_controller: IETF
+  reference: RFC 6415
+
+host-meta.json:
+  change_controller: IETF
+  reference: RFC 6415
+
+hosting-provider:
+  change_controller: Automattic Inc.
+  reference: Automattic Hosting Provider
+
+http-opportunistic:
+  change_controller: IETF
+  reference: RFC 8164 (OBSOLETED)
+
+ic-domains:
+  change_controller: DFINITY Foundation
+  reference: Internet Computer
+
+idp-proxy:
+  change_controller: IETF
+  reference: RFC 8827
+
+jmap:
+  change_controller: IETF
+  reference: RFC 8620, Section 2.2
+
+keybase.txt:
+  change_controller: The Keybase Project
+  reference: Keybase Well-Known
+
+knx:
+  change_controller: KNX Association
+  reference: KNX Cloud Specification
+
+looking-glass:
+  change_controller: M. Stubbig
+  reference: RFC 8522, Section 2
+
+masque:
+  change_controller: IETF
+  reference: RFC 9298, RFC 9484
+
+matrix:
+  change_controller: The Matrix.org Foundation C.I.C.
+  reference: Matrix Spec
+
+mercure:
+  change_controller: Les-Tilleuls.coop
+  reference: Mercure Protocol
+
+mta-sts.txt:
+  change_controller: IETF
+  reference: RFC 8461
+
+nfv-oauth-server-configuration:
+  change_controller: ETSI
+  reference: ETSI GS NFV-SEC 022
+
+ni:
+  change_controller: IETF
+  reference: RFC 6920
+
+nodeinfo:
+  change_controller: NodeInfo Developer Community
+  reference: NodeInfo Diaspora
+
+nostr.json:
+  change_controller: Nostr Developer Community
+  reference: Nostr NIP-05
+
+oauth-authorization-server:
+  change_controller: IESG
+  reference: RFC 8414, Section 3
+
+oauth-protected-resource:
+  change_controller: IETF
+  reference: RFC 9728, Section 3
+
+ohttp-gateway:
+  change_controller: IETF
+  reference: RFC 9540
+
+openid-federation:
+  change_controller: OpenID Foundation
+  reference: OpenID Federation 1.0
+
+open-resource-discovery:
+  change_controller: SAP SE
+  reference: SAP Open Resource Discovery
+
+openid-configuration:
+  change_controller: OpenID Foundation
+  reference: OpenID Connect Discovery 1.0
+
+openorg:
+  change_controller: Christopher Gutteridge
+  reference: Open Data Portal
+
+oslc:
+  change_controller: OASIS
+  reference: OSLC Core Version 3.0
+
+pki-validation:
+  change_controller: CA/Browser Forum
+  reference: Baseline Requirements
+
+posh:
+  change_controller: IETF
+  reference: RFC 7711
+
+privacy-sandbox-attestations.json:
+  change_controller: Google Inc.
+  reference: Privacy Sandbox Attestation
+
+private-token-issuer-directory:
+  change_controller: IETF
+  reference: RFC 9578
+
+probing.txt:
+  change_controller: IETF
+  reference: RFC 9511
+
+pvd:
+  change_controller: IETF
+  reference: RFC 8801
+
+rd:
+  change_controller: IETF
+  reference: RFC 9176
+
+related-website-set.json:
+  change_controller: Google Inc.
+  reference: Related Website Sets
+
+reload-config:
+  change_controller: IETF
+  reference: RFC 6940
+
+repute-template:
+  change_controller: IETF
+  reference: RFC 7072
+
+resourcesync:
+  change_controller: NISO
+  reference: Open Archives ResourceSync
+
+sbom:
+  change_controller: IETF
+  reference: RFC 9472
+
+security.txt:
+  change_controller: IETF
+  reference: RFC 9116
+
+ssf-configuration:
+  change_controller: OpenID Shared Signals WG
+  reference: OpenID Shared Signals Framework
+
+ssh-known-hosts:
+  change_controller: David Crawshaw
+  reference: C2SP Well-Known SSH Hosts
+
+sshfp:
+  change_controller: Cynthia Revström
+  reference: SSHFP Specification
+
+stun-key:
+  change_controller: IETF
+  reference: RFC 7635
+
+terraform.json:
+  change_controller: HashiCorp
+  reference: Terraform Remote Discovery
+
+thread:
+  change_controller: Thread Group Inc.
+  reference: Thread Group Specifications
+
+time:
+  change_controller: Poul-Henning Kamp
+  reference: FreeBSD Time Specification
+
+timezone:
+  change_controller: IESG
+  reference: RFC 7808
+
+tdmrep.json:
+  change_controller: W3C
+  reference: W3C TDM Report
+
+tor-relay:
+  change_controller: Tor Project
+  reference: Tor Relay Well-Known URI
+
+traffic-advice:
+  change_controller: Jeremy Roman
+  reference: Private Prefetch Proxy
+
+trust.txt:
+  change_controller: JournalList.net
+  reference: Trust.txt Reference
+
+uma2-configuration:
+  change_controller: Kantara UMA WG
+  reference: UMA 2.0 OAuth Grant
+
+void:
+  change_controller: W3C
+  reference: Vocabulary of Interlinked Data
+
+webauthn:
+  change_controller: W3C
+  reference: WebAuthn Level 3
+
+webfinger:
+  change_controller: IETF
+  reference: RFC 7033
+
+webhook-authorized-senders.json:
+  change_controller: Intempus ApS
+  reference: Webhook Authorization
+
+webweaver.json:
+  change_controller: DigiOnline GmbH
+  reference: WebWeaver Well-Known Resource
+
+wot:
+  change_controller: W3C WoT WG
+  reference: W3C WoT Discovery

data/lib/well_known/response.rb

@@ -0,0 +1,17 @@
+module WellKnown
+  # Wraps an HTTP response from a well-known URL fetch
+  class Response
+    attr_reader :body, :status, :content_type, :headers
+
+    def initialize body:, status:, content_type: nil, headers: {}
+      @body         = body
+      @status       = status
+      @content_type = content_type
+      @headers      = headers
+    end
+
+    def success?
+      (200...300).cover? status
+    end
+  end
+end

data/lib/well_known/version.rb

@@ -0,0 +1,3 @@
+module WellKnown
+  VERSION = '0.1.0'.freeze
+end

data/lib/well_known.rb

@@ -0,0 +1,21 @@
+require_relative 'well_known/version'
+require_relative 'well_known/errors'
+require_relative 'well_known/registry'
+require_relative 'well_known/response'
+require_relative 'well_known/client'
+
+# Discover and fetch well-known URLs (RFC 8615) for any domain
+#
+# @example Fetch a well-known URL
+#   client = WellKnown::Client.new
+#   response = client.fetch("mastodon.social", "nodeinfo")
+#
+# @example Check if a URI suffix is registered
+#   WellKnown::Registry.registered?("nodeinfo") # => true
+module WellKnown
+  class << self
+    # Create a new WellKnown client
+    # @return [WellKnown::Client]
+    def client = Client.new
+  end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: well_known
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shane Becker
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: |
+  A pure Ruby client for discovering and fetching well-known URLs (RFC 8615)
+  from any domain. Includes the full IANA well-known URI registry.
+email:
+- veganstraightedge@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/well_known.rb
+- lib/well_known/client.rb
+- lib/well_known/errors.rb
+- lib/well_known/registry.rb
+- lib/well_known/registry.yml
+- lib/well_known/response.rb
+- lib/well_known/version.rb
+homepage: https://github.com/xoengineering/well_known
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/xoengineering/well_known
+  changelog_uri: https://github.com/xoengineering/well_known/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Discover well-known URLs for any domain
+test_files: []