outline_vpn_api 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a705549d6c1f842aeee03e7a6f6ded562020fc7eb946493e2eda44b0f307e95b
-  data.tar.gz: 5ed19a71d4b574e2b4acd6e851a44d556aabc047479ef053cb3dfedb41b662a3
+  metadata.gz: bb2abf38d1d43c103dfd54f5bf1a77310c60e507a4c4c5f2b9bd7a314b8d1f64
+  data.tar.gz: a655bf162c53f6f5aed16dd51337927cf7c0e4c9858adca7803af0c83e7e5ab4
 SHA512:
-  metadata.gz: bb864456a7a6293a966406268dd66e82e364f1f3f3cc3842a54b1463f108cb0eb3f449a547ad896e2824a3ac217ba620d7297ff543151e88709cccde60221c8f
-  data.tar.gz: 495ee1dad45c93f6173e1a444af102526ae0a22056832bc98c5bc997067327bc745f50fea20606f31ee82985e5b74e4b088a4282ced952d3afc2e3c865713235
+  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

@@ -0,0 +1 @@
+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`
@@ -31,12 +50,12 @@ Fetches a list of all keys:
 keys = client.keys_list
 ```
 
-#### `transfered_data_by_id`
+#### `transferred_data_by_id`
 
 Fetches the transferred data metrics:
 
 ```ruby
-data = client.transfered_data_by_id
+data = client.transferred_data_by_id
 ```
 
 #### `create_key`
@@ -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,55 +2,90 @@
 
 require "httparty"
 require "json"
+require "openssl"
+
+require_relative "errors"
+require_relative "pinned_connection_adapter"
 
 module OutlineVpnApi
   class Client
-    include HTTParty
-    base_uri ""
-    default_options.update(verify: false)
-    headers "Content-Type" => "application/json"
+    DEFAULT_TIMEOUT = 30
 
-    def initialize(api_url)
-      self.class.base_uri(api_url)
-    end
+    CONNECTION_ERRORS = [
+      SocketError,
+      SystemCallError,
+      Net::OpenTimeout,
+      Net::ReadTimeout,
+      HTTParty::RedirectionTooDeep
+    ].freeze
 
-    attr_reader :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
-      parse_response(self.class.get("/access-keys"))["accessKeys"]
+      request(:get, "/access-keys")["accessKeys"]
     end
 
-    def transfered_data_by_id
-      parse_response(self.class.get("/metrics/transfer"))
+    def transferred_data_by_id
+      request(:get, "/metrics/transfer")
     end
 
     def create_key
-      parse_response(self.class.post("/access-keys"))
+      request(:post, "/access-keys")
     end
 
     def set_limit(key_id, limit)
-      response = self.class.put("/access-keys/#{key_id}/data-limit", body: { limit: { bytes: limit } }.to_json)
-      handle_response(response, "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)
-      response = self.class.put("/access-keys/#{key_id}/name", body: { name: }.to_json)
-      handle_response(response, "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 parse_response(response)
-      JSON.parse(response.body)
+    attr_reader :base_uri, :options
+
+    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 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 handle_response(response, success_message)
-      response.code.to_i == 204 ? puts(success_message) : parse_response(response)
+    def parse(body, code)
+      JSON.parse(body)
+    rescue JSON::ParserError
+      raise ResponseError.new(code, body, "Outline API returned malformed JSON (HTTP #{code})")
+    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.1.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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Pavel Vlasikhin
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-09-10 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
@@ -33,12 +32,15 @@ extra_rdoc_files: []
 files:
 - ".rspec"
 - ".rubocop.yml"
+- ".ruby-version"
 - CODE_OF_CONDUCT.md
 - LICENSE
 - README.md
 - 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
@@ -48,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
@@ -56,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.14
-signing_key:
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Ruby API wrapper for Outline VPN Server
 test_files: []