linkveil 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2660cc23fbe2efa8b9b65511016571049fec3337856de39e4a57887c7ce04728
+  data.tar.gz: c1009d5aef352c18f2331f5ff68c5c860e07c6c669129d749d183f99ee956d3e
+SHA512:
+  metadata.gz: 4877a27de5b607cd7bf9191d9aa823aa43145861794ca592ec975da3569e69a6ddacb70a73c0bcab5136bcf14a7fefb7e081d19cc23bdad25156e26e00b352f3
+  data.tar.gz: db45583ec5a8e27159bffec17e259deb8fed9e41e1c785967b01fc6db063aec36ce78e83d1314e8b3ef5cf38d701f1591e25f8bea32cd5f351cbf2ee8399f956

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby }}
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: ["3.2", "3.3", "3.4", "4.0"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+
+      - name: Run RSpec
+        run: bundle exec rspec

data/.github/workflows/release.yml

@@ -0,0 +1,72 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: release
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "4.0"
+          bundler-cache: true
+
+      - name: Authenticate with RubyGems
+        shell: bash
+        env:
+          RUBYGEMS_OWNER: "197318"
+        run: |
+          set -euo pipefail
+
+          : "${ACTIONS_ID_TOKEN_REQUEST_URL:?Missing OIDC URL}"
+          : "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:?Missing OIDC token}"
+
+          oidc_response=$(curl --fail-with-body -sS \
+            -H "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
+            "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=rubygems.org")
+
+          jwt=$(jq -er '.value' <<< "$oidc_response")
+
+          payload=$(jq -n \
+            --arg jwt "$jwt" \
+            --arg owner "$RUBYGEMS_OWNER" \
+            '{jwt: $jwt, owner: $owner}')
+
+          http_code=$(curl -sS \
+            -o /tmp/rubygems-response.json \
+            -w '%{http_code}' \
+            -H 'Content-Type: application/json' \
+            -H 'Accept: application/json' \
+            --data-binary "$payload" \
+            https://rubygems.org/api/v1/oidc/trusted_publisher/exchange_token)
+
+          if [[ "$http_code" != "200" && "$http_code" != "201" ]]; then
+            echo "RubyGems OIDC exchange failed: HTTP $http_code"
+            exit 1
+          fi
+
+          response=$(cat /tmp/rubygems-response.json)
+
+          key=$(jq -er '.rubygems_api_key' <<< "$response")
+          echo "::add-mask::$key"
+          echo "GEM_HOST_API_KEY=$key" >> "$GITHUB_ENV"
+
+      - name: Build gem
+        run: gem build linkveil.gemspec
+
+      - name: Publish gem
+        run: gem push linkveil-0.1.0.gem

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Nelly Simkova
+
+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,128 @@
+# Linkveil
+
+Linkveil is a lightweight Ruby gem that removes tracking parameters from shared URLs while preserving unrelated query parameters.
+
+## Features
+
+- Remove platform-specific tracking parameters.
+- Preserve unrelated query parameters and their original encoding.
+- Support YouTube, Spotify, and TikTok.
+- Keep unknown domains unchanged.
+- Use Linkveil as a Ruby library or command-line tool.
+- Extend supported platforms with a simple sanitizer DSL.
+
+## Installation
+
+Add Linkveil to your Gemfile:
+
+```ruby
+gem 'linkveil'
+```
+
+Then run:
+
+```sh
+bundle install
+```
+
+Or install it directly:
+
+```sh
+gem install linkveil
+```
+
+## Usage
+
+### Ruby API
+
+```ruby
+require 'linkveil'
+
+Linkveil.clean('https://youtu.be/abc?si=secret&t=120')
+# => "https://youtu.be/abc?t=120"
+
+Linkveil.clean('https://open.spotify.com/track/abc123?si=secret')
+# => "https://open.spotify.com/track/abc123"
+
+Linkveil.clean('https://example.com/?foo=bar')
+# => "https://example.com/?foo=bar"
+```
+
+### Command-line interface
+
+```sh
+linkveil 'https://youtu.be/abc?si=secret&t=120'
+```
+
+Output:
+
+```text
+https://youtu.be/abc?t=120
+```
+
+If no URL is provided, Linkveil prints usage instructions to stderr and exits with a non-zero status.
+
+**Windows note:** Depending on your shell and the RubyGems-generated `.bat` launcher, URLs containing `&` may require special handling. When developing from source, you can run:
+
+```powershell
+ruby exe/linkveil 'https://youtu.be/abc?si=secret&t=120'
+```
+
+## Supported platforms
+
+| Platform | Domains                     | Removed parameters                |
+| -------- | --------------------------- | --------------------------------- |
+| YouTube  | `youtube.com`, `youtu.be`   | `si`, `feature`                   |
+| Spotify  | `open.spotify.com`          | `si`                              |
+| TikTok   | `tiktok.com` and subdomains | `is_from_webapp`, `sender_device` |
+
+Linkveil only removes explicitly configured parameters. All other query parameters are preserved.
+
+## Adding a sanitizer
+
+Linkveil uses a small DSL to define platform-specific sanitizers.
+
+```ruby
+module Linkveil
+  module Sanitizers
+    class Example < Linkveil::Sanitizer
+      domains 'example.com'
+      remove_params 'tracking_id', 'ref'
+    end
+  end
+end
+```
+
+Each sanitizer declares the domains it supports and the query parameters it removes.
+
+## Development
+
+Clone the repository:
+
+```sh
+git clone https://github.com/sk8higher/linkveil.git
+cd linkveil
+bundle install
+```
+
+Run the test suite:
+
+```sh
+bundle exec rspec
+```
+
+Build the gem locally:
+
+```sh
+gem build linkveil.gemspec
+```
+
+## Contributing
+
+Bug reports, suggestions, and pull requests are welcome.
+
+When adding support for a new platform, please include tests demonstrating that tracking parameters are removed and unrelated parameters are preserved.
+
+## License
+
+Linkveil is available under the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/linkveil

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative '../lib/linkveil'
+
+url = ARGV.first
+
+if url.nil? || url.empty?
+  warn 'Usage: linkveil <url>'
+  exit 1
+end
+
+puts Linkveil.clean(url)

data/lib/linkveil/platform_detector.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Linkveil
+  module PlatformDetector
+    DOMAINS_LIST = {
+      youtube: ['youtube.com', 'youtu.be'],
+      tiktok: ['tiktok.com'],
+      spotify: ['spotify.com']
+    }.freeze
+
+    def self.detect(host)
+      return nil if host.nil?
+
+      host = host.downcase
+
+      DOMAINS_LIST.each do |platform, domains|
+        return platform if domains.any? { |domain| matches_domain?(host, domain) }
+      end
+
+      nil
+    end
+
+    def self.matches_domain?(host, domain)
+      host == domain || host.end_with?(".#{domain}")
+    end
+  end
+end

data/lib/linkveil/query_cleaner.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Linkveil
+  module QueryCleaner
+    def self.clean(uri, remove:)
+      return uri.to_s if uri.query.nil?
+
+      fragments = uri.query.split('&', -1)
+
+      filtered = fragments.reject do |fragment|
+        key = fragment.partition('=').first
+        decoded_key = URI.decode_www_form_component(key)
+
+        remove.include?(decoded_key)
+      end
+
+      new_query = filtered.join('&')
+
+      uri.query = new_query.empty? ? nil : new_query
+      uri.to_s
+    end
+  end
+end

data/lib/linkveil/sanitizer.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Linkveil
+  class Sanitizer
+    @registry = []
+
+    class << self
+      attr_reader :registry
+
+      def inherited(subclass)
+        Linkveil::Sanitizer.registry << subclass
+        super
+      end
+
+      def domains(*names)
+        if names.any?
+          @domains = names
+        else
+          @domains
+        end
+      end
+
+      def remove_params(*names)
+        if names.any?
+          @remove_params = names
+        else
+          @remove_params
+        end
+      end
+
+      def find_for(host)
+        return nil if host.nil?
+
+        host = host.downcase
+
+        @registry.find do |sanitizer|
+          Array(sanitizer.domains).any? do |domain|
+            PlatformDetector.matches_domain?(host, domain)
+          end
+        end
+      end
+
+      def clean(uri)
+        QueryCleaner.clean(uri, remove: remove_params)
+      end
+    end
+  end
+end

data/lib/linkveil/sanitizers/spotify.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Linkveil
+  module Sanitizers
+    class Spotify < Sanitizer
+      domains 'open.spotify.com'
+      remove_params 'si'
+    end
+  end
+end

data/lib/linkveil/sanitizers/tiktok.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Linkveil
+  module Sanitizers
+    class TikTok < Linkveil::Sanitizer
+      domains 'tiktok.com'
+      remove_params 'is_from_webapp', 'sender_device'
+    end
+  end
+end

data/lib/linkveil/sanitizers/youtube.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Linkveil
+  module Sanitizers
+    class YouTube < Linkveil::Sanitizer
+      domains 'youtube.com', 'youtu.be'
+      remove_params 'si', 'feature'
+    end
+  end
+end

data/lib/linkveil/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Linkveil
+  VERSION = "0.1.0"
+end

data/lib/linkveil.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'uri'
+require_relative 'linkveil/version'
+require_relative 'linkveil/query_cleaner'
+require_relative 'linkveil/platform_detector'
+
+require_relative 'linkveil/sanitizer'
+require_relative 'linkveil/sanitizers/youtube'
+require_relative 'linkveil/sanitizers/spotify'
+require_relative 'linkveil/sanitizers/tiktok'
+
+module Linkveil
+  def self.clean(url)
+    uri = URI.parse(url)
+
+    sanitizer = Sanitizer.find_for(uri.host)
+
+    return url if sanitizer.nil?
+
+    sanitizer.clean(uri)
+  rescue URI::InvalidURIError
+    url
+  end
+end

data/sig/linkveil.rbs

@@ -0,0 +1,4 @@
+module Linkveil
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: linkveil
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Nelly Simkova
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: Linkveil is a lightweight Ruby gem that removes tracking parameters from
+  URLs while preserving unrelated query parameters. It supports YouTube, Spotify,
+  and TikTok, and provides a simple command-line interface.
+email:
+- sk8high3r@ya.ru
+executables:
+- linkveil
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".github/workflows/release.yml"
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/linkveil
+- lib/linkveil.rb
+- lib/linkveil/platform_detector.rb
+- lib/linkveil/query_cleaner.rb
+- lib/linkveil/sanitizer.rb
+- lib/linkveil/sanitizers/spotify.rb
+- lib/linkveil/sanitizers/tiktok.rb
+- lib/linkveil/sanitizers/youtube.rb
+- lib/linkveil/version.rb
+- sig/linkveil.rbs
+homepage: https://github.com/sk8higher/linkveil
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sk8higher/linkveil
+  source_code_uri: https://github.com/sk8higher/linkveil
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: Remove tracking parameters from shared URLs
+test_files: []