schleuder-cli 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ac4d12688077b4652cfd1a4022bbb09446ad196cf8de8f030a5cd7d751715080
+  data.tar.gz: 3e6a4e4cf966c2424a1259020c2c58da392c770e49194c99aae8f3b694030b22
+SHA512:
+  metadata.gz: 6739403ab27f9bb7b065c5595f1726270786d144488e1efc40615a1722ad584cdf5ce535f8ad148fff9625702ca38a55d3139340fcd7c167133d80bbf71bf446
+  data.tar.gz: bc85f015ecc4d1c58ae91d8a64147b38f5f62c143f4a71040f8cdd22d38b58b543fd37a65191de55c90dbbbd652d60e978ba71efd330bbf864b092758693bdc7

data/README.md

@@ -0,0 +1,111 @@
+Schleuder-cli
+==============
+
+A command line tool to create and manage schleuder-lists.
+
+Schleuder-cli enables creating, configuring, and deleting lists, subscriptions, keys, etc. It uses the Schleuder API, provided by schleuder-api-daemon (part of Schleuder).
+
+Authentication and TLS-verification are mandatory. You need an API-key and the fingerprint of the TLS-certificate of the Schleuder API, respectively. Both should be provided by the API operators.
+
+schleuder-cli does *not* authorize access. Only people who are supposed to have full access to all lists should be allowed to use it on/with your server.
+
+
+Requirements
+------------
+* ruby  >=2.7
+* thor
+
+Installation
+------------
+
+1. Download [the gem](https://0xacab.org/schleuder/schleuder-cli/raw/main/gems/schleuder-cli-0.2.0.gem) and [the OpenPGP-signature](https://0xacab.org/schleuder/schleuder-cli/raw/main/gems/schleuder-cli-0.2.0.gem.sig) and verify:
+   ```
+   gpg --recv-key 0xB3D190D5235C74E1907EACFE898F2C91E2E6E1F3
+   gpg --verify schleuder-cli-0.2.0.gem.sig
+   ```
+
+2. If all went well install the gem:
+   ```
+   gem install schleuder-cli-0.2.0.gem
+   ```
+
+You probably want to install [schleuder](https://0xacab.org/schleuder/schleuder), too. Without schleuder, this software is very useless.
+
+Configuration
+-------------
+
+SchleuderCli reads its settings from a file that it by default expects at `$HOME/.schleuder-cli/schleuder-cli.yml`. To make it read a different file set the environment variable `SCHLEUDER_CLI_CONFIG` to the path to your file. E.g.:
+
+    SCHLEUDER_CLI_CONFIG=/usr/local/etc/schleuder-cli.yml schleuder-cli ...
+
+The configuration file specifies how to connect to the Schleuder API. If it doesn't exist, it will be filled with the default settings.
+
+The default settings will work out of the box with the default settings of Schleuder if both are running on the same host.
+
+**Options**
+
+These are the configuration file options and their default values:
+
+ * `host`: The hostname (or IP-address) to connect to. Default: `localhost`.
+ * `port`: The port to connect to. Default: `4443`.
+ * `tls_fingerprint`: TLS-fingerprint of the Schleuder API. To be fetched from the API operators. Default: empty.
+ * `api_key`: Key to authenticate with against the Schleuder API. To be fetched from the API operators. Default: empty.
+
+
+Usage
+-----
+See `schleuder-cli help`.
+
+E.g.:
+
+    Commands:
+      schleuder-cli help [COMMAND]     # Describe available commands or one specific command
+      schleuder-cli keys ...           # Manage OpenPGP-keys
+      schleuder-cli lists ...          # Create and configure lists
+      schleuder-cli subscriptions ...  # Create and manage subscriptions
+      schleuder-cli version            # Show version of schleuder-cli or Schleuder.
+
+
+
+Contributing
+------------
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+
+Mission statement
+-----------------
+
+We summarized our motivation in [MISSION_STATEMENT.md](MISSION_STATEMENT.md).
+
+
+Code of Conduct
+---------------
+
+We adopted a code of conduct. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+
+License
+-------
+
+GNU GPL 3.0. Please see [LICENSE.txt](LICENSE.txt).
+
+Tests
+-----
+To run the integration tests, you must have a schleuder-api-daemon running locally (in test mode, preferably). From the root directory of the schleuder-repo execute this:
+
+```
+SCHLEUDER_ENV=test SCHLEUDER_CONFIG=spec/schleuder.yml SCHLEUDER_LIST_DEFAULTS=etc/list-defaults.yml bundle exec ./bin/schleuder-api-daemon
+```
+
+Then you can run the tests:
+
+```
+bundle exec rspec
+```
+
+
+Alternative Download
+--------------------
+
+Alternatively to the gem-files you can download the latest release as [a tarball](https://0xacab.org/schleuder/schleuder-cli/raw/main/gems/schleuder-cli-0.2.0.tar.gz) and [its OpenPGP-signature](https://0xacab.org/schleuder/schleuder-cli/raw/main/gems/schleuder-cli-0.2.0.tar.gz.sig).

data/bin/schleuder-cli

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+
+require_relative '../lib/schleuder-cli'
+
+trap("INT") { exit 1 }
+
+SchleuderCli::Base.start

data/lib/schleuder-cli/base.rb

@@ -0,0 +1,37 @@
+module SchleuderCli
+  class Base < Thor
+    include Helper
+
+    register(Subscriptions,
+             'subscriptions',
+             'subscriptions ...',
+             'Create and manage subscriptions')
+
+    register(Keys,
+             'keys',
+             'keys ...',
+             'Manage OpenPGP-keys')
+
+    register(Lists,
+             'lists',
+             'lists ...',
+             'Create and configure lists')
+
+    map '-v' => :version
+    desc 'version', "Show version of schleuder-cli or Schleuder."
+    method_option :remote, aliases: '-r', banner: '', desc: "Show version of Schleuder at the server."
+    def version
+      if options.remote
+        say get('/version.json')['version']
+      else
+        say VERSION
+      end
+    end
+
+    # This tells Thor to go with its new behaviour since v1.0.0, which is
+    # exiting in case of failures.
+    def self.exit_on_failure?
+      true
+    end
+  end
+end

data/lib/schleuder-cli/conf.rb

@@ -0,0 +1,103 @@
+module SchleuderCli
+  class Conf
+    include Singleton
+
+    FINGERPRINT_REGEXP = /\A0?x?[a-f0-9]{32,}\z/i
+
+    DEFAULTS = {
+        'host' => 'localhost',
+        'port' => 4443,
+        'tls_fingerprint' => nil,
+        'api_key' => nil
+      }
+
+    def config
+      @config ||= load_config(ENV['SCHLEUDER_CLI_CONFIG'])
+    end
+
+    def self.host
+      instance.config['host'].to_s
+    end
+
+    def self.port
+      instance.config['port'].to_s
+    end
+
+    def self.tls_fingerprint
+      instance.config['tls_fingerprint'].to_s
+    end
+
+    def self.api_key
+      instance.config['api_key'].to_s
+    end
+
+    def self.remote_cert_file
+      path = instance.config['remote_cert_file'].to_s
+      if path.empty?
+        fatal "Error: remote_cert_file is empty, can't verify remote server without it (in #{ENV['SCHLEUDER_CLI_CONFIG']})."
+      end
+      file = Pathname.new(path).expand_path
+      if ! file.readable?
+        fatal "Error: remote_cert_file is set to a not readable file (in #{ENV['SCHLEUDER_CLI_CONFIG']})."
+      end
+      file.to_s
+    end
+
+
+    private
+
+
+    def load_config(filename)
+      file = Pathname.new(filename)
+      if file.exist?
+        load_config_file(file)
+      else
+        write_defaults_to_config_file(file)
+      end
+    end
+
+
+    def load_config_file(file)
+      if ! file.readable?
+        fatal "Error: #{file} is not readable."
+      end
+      yaml = YAML.load(file.read)
+      if ! yaml.is_a?(Hash)
+        fatal "Error: #{file} cannot be parsed correctly, please fix it. (To get a new default configuration file remove the current one and run again.)"
+      end
+      # Test for old, nested config
+      if ! yaml['api'].nil?
+        self.class.fatal "Your configuration file is outdated, please fix it: Remove the first level key called 'api', and move the keys below it to the first level. It should look like this (possibly with different values):\n\n#{defaults_as_yaml}"
+      end
+      yaml
+    end
+
+    def write_defaults_to_config_file(file)
+      dir = file.dirname
+      if dir.dirname.writable?
+        dir.mkdir(0700)
+      else
+        fatal "Error: '#{dir}' is not writable, cannot write default config to '#{file}'."
+      end
+      file.open('w', 0600) do |fh|
+        fh.puts defaults_as_yaml
+      end
+      puts "NOTE: A default configuration file has been written to #{file}."
+      DEFAULTS
+    end
+
+    def fatal(msg)
+      self.class.fatal(msg)
+    end
+
+    def self.fatal(msg)
+      $stderr.puts msg
+      exit 1
+    end
+
+    def defaults_as_yaml
+      # Strip the document starting dashes. We don't need them, they only confuse people.
+      DEFAULTS.to_yaml.lines[1..-1].join
+    end
+  end
+end

data/lib/schleuder-cli/helper.rb

@@ -0,0 +1,279 @@
+module SchleuderCli
+  module Helper
+
+    def api
+      @http ||= begin
+          http = Net::HTTP.new(Conf.host, Conf.port)
+          http.use_ssl = true
+          http.verify_mode = OpenSSL::SSL::VERIFY_PEER
+          http.verify_callback = lambda { |*a| ssl_verify_callback(*a) }
+          #http.ca_file = Conf.remote_cert_file
+          http
+        end
+    end
+
+    def url(*args)
+      if args.last.is_a?(Hash)
+        params = args.pop
+      end
+      u = "/#{args.join('/')}.json"
+      if params
+        paramstring  = params.map do |k,v|
+          "#{CGI.escape(k.to_s)}=#{CGI.escape(v.to_s)}"
+        end.join('&')
+        u << "?#{paramstring}"
+      end
+      u
+    end
+
+    def get(url)
+      req = Net::HTTP::Get.new(url)
+      request(req)
+    end
+
+    def post(url, payload, &block)
+      req = Net::HTTP::Post.new(url)
+      req.body = payload.to_json
+      req.content_type = 'application/json'
+      request(req, &block)
+    end
+
+    def patch(url, payload)
+      req = Net::HTTP::Patch.new(url)
+      req.body = payload.to_json
+      req.content_type = 'application/json'
+      request(req)
+    end
+
+    def delete_req(url)
+      req = Net::HTTP::Delete.new(url)
+      request(req)
+    end
+
+    def debug(msg)
+      if $DEBUG
+        $stderr.puts "SchleuderCli: #{msg}"
+      end
+    end
+
+    def request(req, &block)
+      test_mandatory_config
+      req.basic_auth 'schleuder', Conf.api_key
+      debug "Request to API: #{req.inspect}"
+      debug "API request path: #{req.path.inspect}"
+      debug "API request headers: #{req.to_hash.inspect}"
+      debug "API request body: #{req.body.inspect}"
+      if block
+        resp = block.call(api, req)
+      else
+        resp = api.request(req)
+      end
+      debug "Response from API: #{resp.inspect}"
+      debug "API response headers: #{resp.to_hash.inspect}"
+      debug "API response body: #{resp.body}"
+      handle_response_errors(resp)
+      handle_response_messages(resp)
+      parse_body(resp.body)
+    rescue Errno::ECONNREFUSED
+      fatal "Error: Cannot connect to Schleuder API at #{api.address}:#{api.port}, please check if it's running."
+    rescue Net::ReadTimeout => exc
+      error "Error: Timeout while waiting for server."
+      # If you set the timeout explicitly you'll have the exception passed on
+      # in order to react explicitly, too.
+      if timeout.to_i > 0
+        raise exc
+      end
+    rescue OpenSSL::SSL::SSLError => exc
+      case exc.message
+      when /certificate verify failed/
+        fatal exc.message.split('state=').last.capitalize
+      else
+        fatal exc.message
+      end
+    rescue => exc
+      fatal exc.message
+    end
+
+    def handle_response_errors(response)
+      case response.code.to_i
+      when 404
+        fatal "Schleuder could not find the requested resource, please check your input."
+      when 401
+        fatal "Authentication failed, please check your API key."
+      when 400
+        if body = parse_body(response.body)
+          fatal "Error: #{body['errors']}"
+        else
+          fatal "Unknown error"
+        end
+      when 500
+        fatal 'Server error, try again later'
+      end
+    end
+
+    def handle_response_messages(response)
+      messages = response.header['X-Messages'].to_s.split(' // ')
+      if ! messages.empty?
+        say "\n"
+        messages.each do |message|
+          say " ! #{message}"
+        end
+        say "\n"
+      end
+    end
+
+    def parse_body(body)
+      if body.to_s.empty?
+        nil
+      else
+        JSON.parse(body)
+      end
+    end
+
+    def fatal(msgs)
+      Array(msgs).each do |msg|
+        error msg
+      end
+      exit 1
+    end
+
+    def check_option_presence(hash, option)
+      if ! hash.has_key?(option)
+        fatal "No such option"
+      end
+    end
+
+    def show_value(value)
+      case value
+      when Array, Hash
+        say value.inspect
+      else
+        say value
+      end
+      exit
+    end
+
+    def ok
+      say "Ok."
+      exit 0
+    end
+
+    def say_key_import_stati(import_stati)
+      Array(import_stati).each do |import_status|
+        say "Key #{import_status['fpr']}: #{import_status['action']}"
+      end
+    end
+
+    def say_key_import_result(keys)
+      keys.each do |key|
+        if key['import_action'] == 'error'
+          say "Unexpected error while importing key #{key['fingerprint']}"
+        else
+          say "#{key['import_action'].capitalize}: #{key['summary']}"
+        end
+      end
+    end
+
+    def import_key_and_find_fingerprint(listname, keyfile)
+      return nil if keyfile.to_s.empty?
+
+      fingerprints = import_key(listname, keyfile)
+
+      if fingerprints.size == 1
+        fingerprints.first
+      else
+        say "#{keyfile} contains more than one key, cannot determine which fingerprint to use. Please set it manually!"
+        nil
+      end
+    end
+
+    def import_key(listname, keyfile)
+      test_file(keyfile)
+      keydata = File.binread(keyfile)
+      if ! keydata.match('BEGIN PGP')
+        keydata = Base64.encode64(keydata)
+      end
+      result = post(url(:keys, {list_id: listname}), {keymaterial: keydata})
+      if result.has_key?("keys")
+        # API is v5 or later.
+        num = result["keys"].size
+        if num == 0
+          say "#{keyfile} did not contain any keys!"
+          return nil
+        end
+        say_key_import_result(result["keys"])
+        result["keys"].map { |key| key["fingerprint"] }
+      else
+        # API is v4 or earlier.
+        num = result["considered"]
+        if num == 0
+          say "#{keyfile} did not contain any keys!"
+          return nil
+        end
+        say_key_import_stati(result['imports'])
+        result['imports'].map { |import| import['fpr'] }
+      end
+    end
+
+    def test_file(filename)
+      if ! File.readable?(filename)
+        fatal "File not found: #{filename}"
+      end
+    end
+
+    def subscribe(listname, email, fingerprint, adminflag=false)
+      res = post(url(:subscriptions, {list_id: listname}), {
+          email: email,
+          fingerprint: fingerprint.to_s,
+          admin: adminflag.to_s
+        })
+      if res && res['errors']
+        print "Error subscribing #{email}: "
+        show_errors(res['errors'])
+      end
+      text = "#{email} subscribed to #{listname} "
+      if fingerprint
+        text << "with fingerprint #{fingerprint}."
+      else
+        text << "without setting a fingerprint."
+      end
+      say text
+    end
+
+    def show_errors(errors)
+      Array(errors).each do |k,v|
+        if v
+          say "#{k.capitalize} #{v.join(', ')}"
+        else
+          say k
+        end
+      end
+      exit 1
+    end
+
+    def ssl_verify_callback(pre_ok, cert_store)
+      cert = cert_store.chain[0]
+      # Only really compare if we're looking at the last cert in the chain.
+      if cert.to_der != cert_store.current_cert.to_der
+        return true
+      end
+      fingerprint = OpenSSL::Digest::SHA256.new(cert.to_der).to_s
+      fingerprint == Conf.tls_fingerprint
+    end
+
+    def test_mandatory_config
+      if Conf.host.empty?
+        fatal "Error: 'host' is empty, can't connect (in #{ENV['SCHLEUDER_CLI_CONFIG']})."
+      end
+      if Conf.port.empty?
+        fatal "Error: 'port' is empty, can't connect (in #{ENV['SCHLEUDER_CLI_CONFIG']})."
+      end
+      if Conf.tls_fingerprint.empty?
+        fatal "Error: 'tls_fingerprint' is empty but required (in #{ENV['SCHLEUDER_CLI_CONFIG']})."
+      end
+      if Conf.api_key.empty?
+        fatal "Error: 'api_key' is empty but required (in #{ENV['SCHLEUDER_CLI_CONFIG']})."
+      end
+    end
+  end
+end

data/lib/schleuder-cli/keys.rb

@@ -0,0 +1,39 @@
+module SchleuderCli
+  class Keys < Thor
+    extend SubcommandFix
+    include Helper
+
+    desc 'import <list@hostname> </path/to/keyfile>', "Import a key into a list's keyring."
+    def import(listname, keyfile)
+      import_key(listname, keyfile)
+    end
+
+    desc 'export <list@hostname> <fingerprint>', "Get the key exported from the list's keyring."
+    def export(listname, fingerprint)
+      if hash = get(url(:keys, fingerprint, {list_id: listname}))
+        say hash['ascii']
+      end
+    end
+
+    desc 'list <list@hostname>', "List keys available to list."
+    def list(listname)
+      if keys = get(url(:keys, {list_id: listname}))
+        keys.each do |hash|
+          say "#{hash['fingerprint']} #{hash['email']}"
+        end
+      end
+    end
+
+    desc 'delete <list@hostname> <fingerprint>', "Delete key from list."
+    def delete(listname, fingerprint)
+      delete_req(url(:keys, fingerprint, {list_id: listname})) || ok
+    end
+
+    desc 'check <list@hostname>', "Check for expiring or unusable keys."
+    def check(listname)
+      resp = get(url(:keys, :check_keys, {list_id: listname}))
+      say resp['result']
+    end
+  end
+end
+

data/lib/schleuder-cli/lists.rb

@@ -0,0 +1,80 @@
+module SchleuderCli
+  class Lists < Thor
+    include Helper
+    extend SubcommandFix
+
+    desc 'list', 'List all known lists.'
+    def list
+      get(url(:lists)).each do |list|
+        say list['email']
+      end
+    end
+
+    desc 'new <list@hostname> <adminaddress> [</path/to/publickeys.asc>]', 'Create a new schleuder list.'
+    def new(listname, adminaddress, keyfile=nil)
+      res = post(url(:lists), {email: listname}) do |http, request|
+        test_file(keyfile) if keyfile
+        http.read_timeout = 120
+        begin
+          http.request(request)
+        rescue Net::ReadTimeout
+          fatal "Error: Timeout while waiting for Schleuder API!\n\nThe Schleuder API didn't answer in time. This happens sometimes when creating a new list because generating a new OpenPGP key-pair requires a lot of randomness — if that's not given, GnuPG just waits until there's more.\nUnfortunately we can't know what the issue really is. But chances are that the list was created just fine and in a few minutes the new OpenPGP key-pair will have been generated, too. So please wait a little while and then have a look if your list was created."
+        end
+      end
+
+      if res && res['errors']
+        show_errors(res['errors'])
+      else
+        say "List #{listname} successfully created! Don't forget to hook it into your MTA."
+      end
+
+      fingerprint = import_key_and_find_fingerprint(listname, keyfile)
+      subscribe(listname, adminaddress, fingerprint, true)
+    end
+
+    desc 'list-options', 'List available options for lists.'
+    def list_options()
+      say get(url(:lists, 'configurable_attributes')).join("\n")
+    end
+
+    desc 'show <list@hostname> <option>', 'Get the value of a list-option.'
+    def show(listname, option)
+      list = get(url(:lists, listname))
+      check_option_presence(list, option)
+      show_value(list[option])
+    end
+
+    desc 'set <list@hostname> <option> <value>', 'Get or set the value of a list-option.'
+    def set(listname, option, value)
+      if option.start_with?('headers_to_meta', 'keywords_admin_notify', 'keywords_admin_only', 'bounces_drop_on_headers')
+        begin
+          value = JSON.parse(value)
+        rescue => exc
+          error "Parsing value as JSON failed: #{exc.message}"
+          fatal "Input must be valid JSON."
+        end
+      end
+      patch(url(:lists, listname), {option => value})
+      show_value(value)
+    end
+
+    desc 'delete <list@hostname> [--YES]', "Delete the list. To skip confirmation use --YES"
+    def delete(listname, dontask=nil)
+      if dontask != '--YES'
+        answer = ask "Really delete list including all its data? [yN] "
+        if answer.downcase != 'y'
+          say "Not deleted."
+          exit 0
+        end
+      end
+      say delete_req(url(:lists, listname))
+    end
+
+    desc 'send-list-key-to-subscriptions <list@hostname>', "Triggers the sending of the list's public key to all subscriptions."
+    def send_list_key_to_subscriptions(listname)
+      response = post(url(:lists, :send_list_key_to_subscriptions, {list_id: listname}), :irrelevant)
+      say response['result']
+    end
+
+  end
+end

data/lib/schleuder-cli/openssl_ssl_patch.rb

@@ -0,0 +1,12 @@
+# Monkey-patch OpenSSL to skip checking the hostname of the remote certificate.
+# We need to enable VERIFY_PEER in order to get hands on the remote certificate
+# to check the fingerprint. But we don't care for the matching of the
+# hostnames. Unfortunately this patch is apparently the only way to achieve
+# that.
+module OpenSSL
+  module SSL
+    def self.verify_certificate_identity(peer_cert, hostname)
+      true
+    end
+  end
+end

data/lib/schleuder-cli/subcommand_fix.rb

@@ -0,0 +1,11 @@
+module SchleuderCli
+  module SubcommandFix
+
+    # Fixing a bug in Thor where the actual subcommand wouldn't show up
+    # with some invocations of the help-output.
+    def banner(task, namespace = true, subcommand = true)
+      "#{basename} #{task.formatted_usage(self, true, subcommand).split(':').join(' ')}"
+    end
+
+  end
+end