outline_vpn_api 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c9711c3976ab3430f3a9c4a2d22987fab3ff9ae28fc30a88e86df35957d8a9b
-  data.tar.gz: bdfc5e017c2f264329f44eb87b2a8e4cc3e62586174b227a2297ba59fe4732c1
+  metadata.gz: bb2abf38d1d43c103dfd54f5bf1a77310c60e507a4c4c5f2b9bd7a314b8d1f64
+  data.tar.gz: a655bf162c53f6f5aed16dd51337927cf7c0e4c9858adca7803af0c83e7e5ab4
 SHA512:
-  metadata.gz: 50af08ed6369f0b5280049af3cfc7ffb767f9d2f7d399657009dea3f79caba5716eba485097cb4e4cd2463113390cb607fc62fe175e641713d2ec36ed15f230e
-  data.tar.gz: e3698a273dff671a1bc32848339d74f5ae079525cacf3c3196aaa0b899d225012a749e912f3b9bd7c3adc0e52c511e63f6173fdf87e5904bb4d321c8738cc273
+  metadata.gz: 2194448999c1d61ce195ebf09f7c1bb844b1d4e20c8e85b515bcfafc7d871fd644a8ced697522b6b0fc639164c818704b589ac9311570332147ee17549658a90
+  data.tar.gz: dbdf4e26219962c39f157b2d2d405cd3176c2b50b0a228a595686e80df5aff68c0477690c671a5677221eacef28766694617e87417c3157c98b82e3bf8959320

data/.rubocop.yml

@@ -1,8 +1,8 @@
-require:
+plugins:
   - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.4
   NewCops: enable
   SuggestExtensions: false
 
@@ -19,3 +19,13 @@ Style/StringLiteralsInInterpolation:
 
 Layout/LineLength:
   Max: 125
+
+Metrics:
+  Exclude:
+    - "spec/**/*"
+
+RSpec/ExampleLength:
+  Max: 10
+
+RSpec/MultipleExpectations:
+  Max: 3

data/.ruby-version

@@ -1 +1 @@
-3.2.2
+4.0.6

data/README.md

@@ -5,7 +5,7 @@ It provides a simple interface to manage and retrieve information about VPN keys
 
 ## Installation
 
-Ensure you have the required gems installed:
+Requires Ruby 3.4 or newer.
 
 ```bash
 gem install outline_vpn_api
@@ -21,6 +21,25 @@ To start using the client, initialize it with the API URL:
 client = OutlineVpnApi.new('YOUR_API_URL')
 ```
 
+Outline servers present a self-signed certificate, so by default the client does
+not verify it. Pass the `certSha256` fingerprint that Outline Manager shows next
+to the API URL to pin the certificate instead:
+
+```ruby
+client = OutlineVpnApi.new('YOUR_API_URL', cert_sha256: 'AB:CD:...')
+```
+
+With a fingerprint set, a connection to any other certificate is rejected with
+`OutlineVpnApi::CertificateError`. Without one the connection can be
+intercepted, and since the API key is part of the URL an interceptor gains full
+control of the server — pinning is strongly recommended.
+
+Requests time out after 30 seconds by default:
+
+```ruby
+client = OutlineVpnApi.new('YOUR_API_URL', timeout: 10)
+```
+
 ### Methods
 
 #### `keys_list`
@@ -49,7 +68,7 @@ new_key = client.create_key
 
 #### `set_limit(key_id, limit)`
 
-Sets a data limit for a specific key:
+Sets a data limit for a specific key. Returns `true`:
 
 ```ruby
 client.set_limit('KEY_ID', LIMIT_IN_BYTES)
@@ -57,7 +76,7 @@ client.set_limit('KEY_ID', LIMIT_IN_BYTES)
 
 #### `rename_key(key_id, name)`
 
-Renames a specific key:
+Renames a specific key. Returns `true`:
 
 ```ruby
 client.rename_key('KEY_ID', 'NEW_NAME')
@@ -65,15 +84,34 @@ client.rename_key('KEY_ID', 'NEW_NAME')
 
 #### `delete_key(key_id)`
 
-Deletes a specific key:
+Deletes a specific key. Returns `true`:
 
 ```ruby
 client.delete_key('KEY_ID')
 ```
 
+## Errors
+
+All errors inherit from `OutlineVpnApi::Error`:
+
+- `OutlineVpnApi::ResponseError` — the server replied with a non-2xx status, or
+  with a body that is not valid JSON. Exposes `#code` and `#body`.
+- `OutlineVpnApi::ConnectionError` — the server could not be reached, or the
+  request timed out.
+- `OutlineVpnApi::CertificateError` — a pinned fingerprint was given and the
+  server's certificate did not match it. Subclass of `ConnectionError`.
+
+```ruby
+begin
+  client.keys_list
+rescue OutlineVpnApi::ResponseError => e
+  warn "Outline returned #{e.code}: #{e.body}"
+end
+```
+
 ## Dependencies
 
-- `httparty`: Used for making HTTP requests.
+- `httparty` (>= 0.24.0): Used for making HTTP requests.
 - `json`: Used for parsing JSON responses.
 
 ## Contributing

data/lib/outline_vpn_api/client.rb

@@ -2,70 +2,90 @@
 
 require "httparty"
 require "json"
+require "openssl"
+
+require_relative "errors"
+require_relative "pinned_connection_adapter"
 
 module OutlineVpnApi
   class Client
-    include HTTParty
-    headers "Content-Type" => "application/json"
-    default_options.update(verify: false)
+    DEFAULT_TIMEOUT = 30
+
+    CONNECTION_ERRORS = [
+      SocketError,
+      SystemCallError,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      HTTParty::RedirectionTooDeep
+    ].freeze
 
-    def initialize(api_url)
-      self.class.base_uri(api_url)
+    def initialize(api_url, cert_sha256: nil, timeout: DEFAULT_TIMEOUT)
+      @base_uri = api_url.to_s.chomp("/")
+      @options = {
+        headers: { "Content-Type" => "application/json" },
+        timeout: timeout
+      }.merge(ssl_options(cert_sha256))
     end
 
     def keys_list
-      get("/access-keys")["accessKeys"]
+      request(:get, "/access-keys")["accessKeys"]
     end
 
     def transferred_data_by_id
-      get("/metrics/transfer")
+      request(:get, "/metrics/transfer")
     end
 
     def create_key
-      post("/access-keys")
+      request(:post, "/access-keys")
     end
 
     def set_limit(key_id, limit)
-      body = { limit: { bytes: limit } }.to_json
-      put("/access-keys/#{key_id}/data-limit", body, "Limit for key_id: #{key_id} is #{limit} bytes")
+      request(:put, "/access-keys/#{key_id}/data-limit", body: { limit: { bytes: limit } })
     end
 
     def rename_key(key_id, name)
-      body = { name: }.to_json
-      put("/access-keys/#{key_id}/name", body, "key_id: #{key_id}, renamed to #{name}")
+      request(:put, "/access-keys/#{key_id}/name", body: { name: })
     end
 
     def delete_key(key_id)
-      response = self.class.delete("/access-keys/#{key_id}")
-      handle_response(response, "key_id: #{key_id}, deleted")
+      request(:delete, "/access-keys/#{key_id}")
     end
 
     private
 
-    def get(endpoint)
-      parse_response(self.class.get(endpoint))
-    end
+    attr_reader :base_uri, :options
 
-    def post(endpoint, body = {})
-      parse_response(self.class.post(endpoint, body:))
+    def request(verb, endpoint, body: nil)
+      request_options = body.nil? ? options : options.merge(body: body.to_json)
+      handle(HTTParty.public_send(verb, "#{base_uri}#{endpoint}", **request_options))
+    rescue OpenSSL::SSL::SSLError => e
+      raise CertificateError, e.message
+    rescue *CONNECTION_ERRORS => e
+      raise ConnectionError, e.message
     end
 
-    def put(endpoint, body, success_message)
-      response = self.class.put(endpoint, body:)
-      handle_response(response, success_message)
+    def handle(response)
+      code = response.code.to_i
+      raise ResponseError.new(code, response.body) unless code.between?(200, 299)
+      return true if response.body.nil? || response.body.empty?
+
+      parse(response.body, code)
     end
 
-    def parse_response(response)
-      JSON.parse(response.body)
+    def parse(body, code)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise ResponseError.new(code, body, "Outline API returned malformed JSON (HTTP #{code})")
     end
 
-    def handle_response(response, success_message)
-      if response.code.to_i == 204
-        puts(success_message)
-        nil
-      else
-        parse_response(response)
-      end
+    def ssl_options(cert_sha256)
+      return { verify: false } if cert_sha256.nil?
+
+      {
+        verify: true,
+        cert_sha256: cert_sha256,
+        connection_adapter: PinnedConnectionAdapter
+      }
     end
   end
 end

data/lib/outline_vpn_api/errors.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OutlineVpnApi
+  class Error < StandardError; end
+
+  class ConnectionError < Error; end
+
+  class CertificateError < ConnectionError; end
+
+  class ResponseError < Error
+    attr_reader :code, :body
+
+    def initialize(code, body, message = nil)
+      @code = code
+      @body = body
+      super(message || "Outline API returned HTTP #{code}")
+    end
+  end
+end

data/lib/outline_vpn_api/pinned_connection_adapter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "httparty"
+require "openssl"
+
+module OutlineVpnApi
+  class PinnedConnectionAdapter < HTTParty::ConnectionAdapter
+    def connection
+      http = super
+      return http unless http.use_ssl?
+
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+      http.verify_hostname = false
+      http.verify_callback = ->(_preverify_ok, store_context) { pinned?(store_context.current_cert) }
+      http
+    end
+
+    private
+
+    def pinned?(certificate)
+      OpenSSL::Digest::SHA256.hexdigest(certificate.to_der) == expected_fingerprint
+    end
+
+    def expected_fingerprint
+      @expected_fingerprint ||= options.fetch(:cert_sha256).to_s.delete(":").downcase
+    end
+  end
+end

data/lib/outline_vpn_api/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OutlineVpnApi
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/outline_vpn_api.rb

@@ -4,10 +4,11 @@ require "httparty"
 require "json"
 
 require_relative "outline_vpn_api/version"
+require_relative "outline_vpn_api/errors"
 require_relative "outline_vpn_api/client"
 
 module OutlineVpnApi
-  def self.new(api_url)
-    OutlineVpnApi::Client.new(api_url)
+  def self.new(api_url, **)
+    OutlineVpnApi::Client.new(api_url, **)
   end
 end

data/outline_vpn_api.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |spec|
   spec.description = "Ruby API wrapper for Outline VPN Server https://getoutline.org/"
   spec.homepage = "https://github.com/vlasikhin/outline_vpn_api"
   spec.license = "MIT"
-  spec.required_ruby_version = ">= 3.2.0"
+  spec.required_ruby_version = ">= 3.4.0"
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
       (File.expand_path(f) == __FILE__) || f.start_with?(
-        *%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile]
+        *%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile CLAUDE.md]
       )
     end
   end
@@ -29,6 +29,6 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_dependency("httparty")
+  spec.add_dependency("httparty", ">= 0.24.0")
   spec.metadata["rubygems_mfa_required"] = "true"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: outline_vpn_api
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Pavel Vlasikhin
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-27 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -16,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.24.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.24.0
 description: Ruby API wrapper for Outline VPN Server https://getoutline.org/
 email:
 - pavel.vlasikhin@gmail.com
@@ -40,6 +39,8 @@ files:
 - Rakefile
 - lib/outline_vpn_api.rb
 - lib/outline_vpn_api/client.rb
+- lib/outline_vpn_api/errors.rb
+- lib/outline_vpn_api/pinned_connection_adapter.rb
 - lib/outline_vpn_api/version.rb
 - outline_vpn_api.gemspec
 homepage: https://github.com/vlasikhin/outline_vpn_api
@@ -49,7 +50,6 @@ metadata:
   homepage_uri: https://github.com/vlasikhin/outline_vpn_api
   source_code_uri: https://github.com/vlasikhin/outline_vpn_api
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -57,15 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.4.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby API wrapper for Outline VPN Server
 test_files: []