blog_verification 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4e30db2372c43909004ba3957b8b16395fe38612a58d42729d8436b4a352295
+  data.tar.gz: de9120839b129627959fd1ee8009edf77a18946619819b8b0079b65c1808de61
+SHA512:
+  metadata.gz: 1e0e7a2a96f8e3cf95d3b299d6081c9105d82389541a2588d38940070eaf03bbbcb683303f8f47c9e2bdfa9e529a80946ccf5b8794e0b46246c1cc0ec05b46e5
+  data.tar.gz: 251e21438613a10575b486fe5d9c28912d8af49c9d9fe92382d6917b66deca802faa1dac5f0274efb8b8eab9913956ca7dd382231d5563cc8b76835882e17011

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blog Verification Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,413 @@
+# BlogVerification — Ruby Gem
+
+A robust, lightweight Ruby Gem for verifying whether a submitted blog URL belongs to the expected author, was published in the current quarter, contains sufficient article length, and matches expected topic, summary, and tag metadata.
+
+Built for **Ruby on Rails** applications and standalone Ruby backends.
+
+Supports **Medium** and **DEV Community (`dev.to`)**.
+
+---
+
+## Key Features
+
+- **Strict Ruby 2.7.8+ Compatibility**: Compatible with Ruby 2.7.8 through modern Ruby 3.x, tested across standard MRI runtimes.
+- **Identical Input & Output Contract**: Produces the exact same structured JSON/Hash responses, error codes, and field checks as the original Node.js REST API.
+- **Rails Integration**:
+  - Direct helper: `BlogVerification.verify(params)`
+  - ActiveModel / ActiveRecord validation: `validates :url, blog_verification: { ... }`
+- **Platform Adapters**:
+  - **DEV Community**: Official Forem API integration with canonical author extraction, tag lists, publication timestamps, and excerpts.
+  - **Medium**: Parses JSON-LD structured data (`NewsArticle`/`BlogPosting`) to extract canonical author identifiers (`author.identifier`, `@id`, `url`), publication timestamps, tags, and body content.
+- **Current Quarter Verification**:
+  - Automatically verifies whether the blog was created in the current quarter:
+    - **Quarter 1**: April 1 – June 30
+    - **Quarter 2**: July 1 – September 30
+    - **Quarter 3**: October 1 – December 31
+    - **Quarter 4**: January 1 – March 31
+  - Out-of-quarter articles fail with `NOT_IN_CURRENT_QUARTER`.
+  - Supports optional `reference_date` (`YYYY-MM-DD`) for deterministic testing.
+- **Article Word Count (Length Check)**:
+  - Strips HTML tags and markdown formatting to count body words.
+  - Verifies minimum word count (default: 500 words). Articles under 500 words fail with `INSUFFICIENT_CONTENT_LENGTH`.
+- **SSRF & Outbound Security**:
+  - Validates URL syntax, protocols (HTTPS), and approved hosts.
+  - Verifies destination IP addresses against private and loopback CIDR blocks before connecting.
+  - Safely follows HTTP redirects up to a maximum depth of 5, re-validating destination hosts and IPs at every hop.
+
+---
+
+## Installation
+
+### In a Ruby on Rails Application
+
+Add this line to your application's `Gemfile`:
+
+```ruby
+gem 'blog_verification'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+### In Plain Ruby or CLI
+
+Install directly via RubyGems:
+
+```bash
+gem install blog_verification
+```
+
+---
+
+## Usage in Ruby on Rails
+
+### 1. In Controllers or Service Objects
+
+You can call `BlogVerification.verify` using either **symbols** or **strings** for keys:
+
+```ruby
+class BlogSubmissionsController < ApplicationController
+  def verify
+    result = BlogVerification.verify(
+      platform: params[:platform],                      # 'medium' or 'devto'
+      url: params[:url],                                # Full article URL
+      username: params[:username],                      # Expected author username
+      published_at: params[:published_at],              # 'YYYY-MM-DD'
+      tags: params[:tags],                              # Optional array of strings
+      topic: params[:topic],                            # 'Backend Development'
+      summary: params[:summary],                        # Expected description
+      min_word_count: 500                               # Optional, defaults to 500
+    )
+
+    case result['status']
+    when 'valid'
+      render json: { success: true, message: 'Blog verified successfully!', data: result['data'] }
+    when 'invalid'
+      render json: { success: false, errors: result['errors'], data: result['data'] }, status: :unprocessable_entity
+    when 'unverified'
+      render json: { success: false, message: 'Upstream platform unavailable.', errors: result['errors'] }, status: :service_unavailable
+    else
+      render json: { success: false, errors: result['errors'] }, status: :bad_request
+    end
+  end
+end
+```
+
+### 2. In ActiveRecord Models (Custom Validator)
+
+The gem comes with an ActiveModel validator out-of-the-box:
+
+```ruby
+class ArticleSubmission < ApplicationRecord
+  # Attributes: platform, url, author_username, publication_date, topic, summary, tags
+
+  validates :url, presence: true, blog_verification: {
+    platform: :platform,
+    username: :author_username,
+    published_at: :publication_date,
+    topic: :topic,
+    summary: :summary,
+    tags: :tags,
+    min_word_count: 500
+  }
+end
+```
+
+When calling `article_submission.valid?`, the validator automatically performs the verification. Any verification errors (e.g. `AUTHOR_MISMATCH`, `NOT_IN_CURRENT_QUARTER`, `INSUFFICIENT_CONTENT_LENGTH`) are appended to `article_submission.errors[:url]`.
+
+---
+
+## Configuration
+
+You can configure global gem settings via an initializer (e.g. `config/initializers/blog_verification.rb` in Rails):
+
+```ruby
+BlogVerification.configure do |config|
+  config.request_timeout = 5.0      # Outbound request timeout in seconds (default: 5.0)
+  config.max_redirects = 5          # Maximum redirects to follow (default: 5)
+  config.require_https = true       # Require HTTPS URLs in production (default: true)
+  config.skip_dns_check = false     # Set true only in offline/mock testing environments
+end
+```
+
+---
+
+## Input & Output Specification
+
+### Input Hash
+
+Both `camelCase` and `snake_case` keys are supported:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `platform` | String | **Yes** | `"devto"` or `"medium"` |
+| `url` | String | **Yes** | Article HTTPS URL |
+| `username` | String | **Yes** | Expected canonical author username |
+| `published_at` / `publishedAt` | String | **Yes** | Original publication date in `YYYY-MM-DD` |
+| `tags` | Array of strings | No | Expected tags; omitting or `[]` skips validation |
+| `topic` | String | **Yes** | Expected topic matching taxonomy |
+| `summary` | String | **Yes** | Expected official description or excerpt |
+| `min_word_count` / `minWordCount` | Integer | No | Minimum required word count (default: `500`) |
+| `reference_date` / `referenceDate` | String | No | Custom reference date (`YYYY-MM-DD`) for quarterly verification (default: today) |
+
+---
+
+### Output Hash Examples
+
+#### 1. Valid Blog Verification
+
+```json
+{
+  "success": true,
+  "status": "valid",
+  "message": "Blog verification completed successfully.",
+  "data": {
+    "platform": "medium",
+    "url": "https://medium.com/@thedevankit/mastering-clean-architecture-in-nodejs-abc12345",
+    "checks": {
+      "url": { "status": "passed" },
+      "username": {
+        "status": "passed",
+        "expected": "thedevankit",
+        "actual": "thedevankit"
+      },
+      "publishedAt": {
+        "status": "passed",
+        "expected": "2026-10-15",
+        "actual": "2026-10-15"
+      },
+      "quarter": {
+        "status": "passed",
+        "currentQuarter": "October - December 2026",
+        "blogQuarter": "October - December 2026",
+        "message": "Blog publication date is in the current quarter (October - December 2026)."
+      },
+      "tags": {
+        "status": "passed",
+        "expected": ["architecture", "express", "nodejs"],
+        "actual": ["architecture", "express", "nodejs"]
+      },
+      "topic": {
+        "status": "passed",
+        "expected": "Backend Development",
+        "actual": "Backend Development"
+      },
+      "summary": { "status": "passed" },
+      "contentLength": {
+        "status": "passed",
+        "wordCount": 850,
+        "minRequired": 500,
+        "message": "Blog length passed (850 words >= 500 words)."
+      }
+    }
+  }
+}
+```
+
+#### 2. Failed Verification (Mismatch / Out of Quarter / Short Length)
+
+```json
+{
+  "success": true,
+  "status": "invalid",
+  "message": "Blog verification failed.",
+  "errors": [
+    {
+      "code": "NOT_IN_CURRENT_QUARTER",
+      "field": "publishedAt",
+      "message": "Blog publication date is not in the current quarter. Expected October - December 2026, but blog was published in April - June 2026.",
+      "expected": "October - December 2026",
+      "actual": "April - June 2026"
+    },
+    {
+      "code": "INSUFFICIENT_CONTENT_LENGTH",
+      "field": "contentLength",
+      "message": "The blog content does not meet the minimum required length of 500 words.",
+      "expected": 500,
+      "actual": 250
+    }
+  ],
+  "data": {
+    "platform": "medium",
+    "url": "https://medium.com/@thedevankit/mastering-clean-architecture-in-nodejs-abc12345",
+    "checks": {
+      "url": { "status": "passed" },
+      "username": { "status": "passed" },
+      "publishedAt": { "status": "passed" },
+      "quarter": { "status": "failed" },
+      "tags": { "status": "passed" },
+      "topic": { "status": "passed" },
+      "summary": { "status": "passed" },
+      "contentLength": { "status": "failed", "wordCount": 250, "minRequired": 500 }
+    }
+  }
+}
+```
+
+---
+
+## Error Codes
+
+| Error Code | Meaning |
+|---|---|
+| `INVALID_REQUEST` | Input payload or date format is malformed |
+| `MISSING_REQUIRED_FIELD` | A required field (`platform`, `url`, `username`, `publishedAt`, `topic`, `summary`) is missing |
+| `INVALID_PLATFORM` | Platform is not `'medium'` or `'devto'` |
+| `INVALID_URL` | URL is malformed, uses an unsupported host, or targets an index/profile page |
+| `UNSAFE_URL` | URL or redirect targets loopback or private network (SSRF protection) |
+| `ARTICLE_NOT_FOUND` | Source platform confirms article does not exist |
+| `ARTICLE_ACCESS_DENIED` | Article is restricted, paywalled, or private |
+| `AUTHOR_MISMATCH` | Expected username does not match canonical platform username |
+| `PUBLICATION_DATE_MISMATCH` | Expected date does not match source publication date (UTC) |
+| `NOT_IN_CURRENT_QUARTER` | Blog publication date is outside the current quarter |
+| `INSUFFICIENT_CONTENT_LENGTH` | Article word count is under the required minimum (default 500) |
+| `TAGS_MISMATCH` | Supplied tags do not match article tags |
+| `TOPIC_MISMATCH` | Expected topic does not match verified topic |
+| `SUMMARY_MISMATCH` | Expected summary does not match description |
+| `SOURCE_RATE_LIMITED` | Source platform rate limited the request |
+| `SOURCE_TIMEOUT` | Upstream platform timed out |
+| `SOURCE_UNAVAILABLE` | Upstream platform is down |
+
+---
+
+# Step-by-Step Guide to Uploading the Gem to RubyGems.org
+
+Follow these instructions to build, package, and publish `blog_verification` to the official RubyGems library ([rubygems.org](https://rubygems.org)).
+
+### Step 1: Create a RubyGems.org Account
+
+1. Go to [https://rubygems.org/sign_up](https://rubygems.org/sign_up) and register an account.
+2. Verify your email address.
+3. Enable Multi-Factor Authentication (MFA) in your account settings (RubyGems now requires MFA for gem maintainers).
+
+---
+
+### Step 2: Configure RubyGems API Credentials on Your Machine
+
+Open your terminal and run:
+
+```bash
+gem signin
+```
+
+Enter your RubyGems email and password. When prompted, enter your MFA code. This will save your API key securely into `~/.gem/credentials`.
+
+Alternatively, you can manually set your API key:
+
+```bash
+curl -u <your-username> https://rubygems.org/api/v1/api_key.yaml > ~/.gem/credentials
+chmod 0600 ~/.gem/credentials
+```
+
+---
+
+### Step 3: Verify Gem Metadata
+
+Open `blog_verification.gemspec` and ensure the following fields are personalized:
+
+- `spec.name`: Must be unique on RubyGems.org. If `blog_verification` is already taken, you can name it `blog_verification_api` or `my_org_blog_verification`.
+- `spec.version`: Ensure `lib/blog_verification/version.rb` is set (e.g. `'1.0.0'`).
+- `spec.authors`: Your name or organization.
+- `spec.email`: Your contact email.
+- `spec.homepage`: Your repository URL (e.g. GitHub URL).
+
+---
+
+### Step 4: Run the Test Suite
+
+Before releasing, execute the test suite to ensure all tests pass:
+
+```bash
+bundle install
+bundle exec rspec
+```
+
+All unit and integration specs should pass.
+
+---
+
+### Step 5: Build the Gem Package
+
+In the `rubyGeM` root directory, run:
+
+```bash
+gem build blog_verification.gemspec
+```
+
+Output:
+```text
+  Successfully built RubyGem
+  Name: blog_verification
+  Version: 1.0.0
+  File: blog_verification-1.0.0.gem
+```
+
+This creates the packaged binary file: `blog_verification-1.0.0.gem`.
+
+---
+
+### Step 6: Test the Gem Locally (Optional but Recommended)
+
+You can install the newly built gem locally to verify that it installs and loads cleanly:
+
+```bash
+gem install ./blog_verification-1.0.0.gem
+```
+
+Test it in `irb`:
+
+```ruby
+require 'blog_verification'
+
+BlogVerification::VERSION
+# => "1.0.0"
+```
+
+---
+
+### Step 7: Push the Gem to RubyGems.org
+
+Publish your gem to the global Ruby community with:
+
+```bash
+gem push blog_verification-1.0.0.gem
+```
+
+If your account has MFA enabled, you will be prompted for your OTP code:
+
+```text
+Pushing gem to https://rubygems.org...
+Enter your MFA code: 123456
+Successfully registered gem: blog_verification (1.0.0)
+```
+
+---
+
+### Step 8: Verify Your Published Gem
+
+Your gem will be immediately live and indexable! Visit:
+
+```
+https://rubygems.org/gems/blog_verification
+```
+
+Now any developer in the world can install your gem with:
+
+```bash
+gem install blog_verification
+```
+
+Or add it to their Rails `Gemfile`:
+
+```ruby
+gem 'blog_verification', '~> 1.0'
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/blog_verification.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'lib/blog_verification/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'blog_verification'
+  spec.version       = BlogVerification::VERSION
+  spec.authors       = ['Ankitkumar Singh (thedevankit)']
+  spec.email         = ['thedevankit@gmail.com']
+
+  spec.summary       = 'Lightweight blog verification library for Medium and DEV Community'
+  spec.description   = 'Verifies whether a submitted blog URL belongs to the claimed author, matches publication date and quarter, meets minimum word length, and matches expected topic and summary metadata.'
+  spec.homepage      = 'https://github.com/thedevankit/blog_verification'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = '>= 2.7.8'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    Dir.glob('lib/**/*', File::FNM_DOTMATCH).reject { |f| File.directory?(f) } +
+      %w[LICENSE.txt README.md blog_verification.gemspec]
+  end
+
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Runtime dependencies
+  # nokogiri is used for robust HTML / JSON-LD parsing; supported on Ruby >= 2.7.8
+  spec.add_dependency 'nokogiri', '>= 1.13.0', '< 2.0'
+
+  # Development dependencies
+  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'webmock', '~> 3.18'
+end

data/lib/blog_verification/adapters/base_adapter.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module BlogVerification
+  module Adapters
+    class BaseAdapter
+      attr_reader :platform
+
+      def initialize(platform)
+        @platform = platform.to_s
+      end
+
+      # Retrieves and normalizes article metadata from the source platform.
+      # Returns a Hash containing:
+      # - canonical_url
+      # - platform
+      # - author: { username: ..., display_name: ... }
+      # - published_at
+      # - updated_at
+      # - tags
+      # - topic
+      # - description
+      # - content
+      # - word_count
+      # - raw_metadata
+      def get_article_metadata(_url, _options = {})
+        raise NotImplementedError, "#{self.class}#get_article_metadata must be implemented."
+      end
+    end
+  end
+end

data/lib/blog_verification/adapters/devto_adapter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative 'base_adapter'
+require_relative '../utils/url_security'
+require_relative '../utils/normalizer'
+require_relative '../errors'
+require_relative '../constants/error_codes'
+
+module BlogVerification
+  module Adapters
+    class DevtoAdapter < BaseAdapter
+      def initialize
+        super('devto')
+      end
+
+      # Builds the official Forem / DEV.to API endpoint URL for an article URL
+      def build_api_url(url_string)
+        parsed = Utils::UrlSecurity.validate_article_url(url_string, 'devto')
+        path = (parsed.path || '').gsub(%r{/+\z}, '')
+        segments = path.split('/').reject(&:empty?)
+
+        if segments.length >= 2
+          return "https://dev.to/api/articles/#{segments[0]}/#{segments[1]}"
+        end
+
+        raise UpstreamError.new(ErrorCodes::INVALID_URL, 'Could not determine DEV.to article path.')
+      end
+
+      # Retrieves metadata for a DEV.to article using the official Forem API
+      def get_article_metadata(url, _options = {})
+        api_url = build_api_url(url)
+
+        response = Utils::UrlSecurity.safe_fetch(
+          api_url,
+          {
+            headers: {
+              'Accept' => 'application/json',
+              'User-Agent' => BlogVerification.configuration.user_agent
+            }
+          },
+          'devto'
+        )
+
+        case response.status
+        when 404
+          raise UpstreamError.new(ErrorCodes::ARTICLE_NOT_FOUND, 'The specified article does not exist on DEV Community.', 404)
+        when 401, 403
+          raise UpstreamError.new(ErrorCodes::ARTICLE_ACCESS_DENIED, 'Access to the DEV Community article is restricted.', response.status)
+        when 429
+          raise UpstreamError.new(ErrorCodes::SOURCE_RATE_LIMITED, 'DEV Community API rate limit exceeded.', 429)
+        else
+          if response.status >= 500
+            raise UpstreamError.new(ErrorCodes::SOURCE_UNAVAILABLE, "DEV Community returned HTTP #{response.status}.", response.status)
+          elsif !response.ok?
+            raise UpstreamError.new(ErrorCodes::SOURCE_RESPONSE_INVALID, "DEV Community returned unexpected status #{response.status}.", response.status)
+          end
+        end
+
+        data = response.json
+        unless data.is_a?(Hash)
+          raise UpstreamError.new(ErrorCodes::SOURCE_RESPONSE_INVALID, 'Malformed JSON payload from DEV Community.')
+        end
+
+        # Extract tags
+        tags = if data['tag_list'].is_a?(Array)
+                 data['tag_list']
+               elsif data['tags'].is_a?(Array)
+                 data['tags']
+               elsif data['tags'].is_a?(String)
+                 data['tags'].split(',').map(&:strip).reject(&:empty?)
+               end
+
+        # Extract body content and word count
+        content = data['body_markdown'] || data['body_html']
+        word_count = content ? Utils::Normalizer.count_words(content) : nil
+
+        user_hash = data['user'].is_a?(Hash) ? data['user'] : {}
+
+        {
+          canonical_url: data['canonical_url'] || data['url'] || url,
+          platform: 'devto',
+          author: {
+            username: user_hash['username'],
+            display_name: user_hash['name']
+          },
+          published_at: data['published_at'],
+          updated_at: data['edited_at'],
+          tags: tags,
+          topic: nil, # Resolved via taxonomy mapping
+          description: data['description'],
+          content: content,
+          word_count: word_count,
+          raw_metadata: data
+        }
+      end
+    end
+  end
+end