kstor 0.4.2 → 0.5.0

data/lib/kstor/store.rb

@@ -1,23 +1,74 @@
 # frozen_string_literal: true
 
+require 'mutex_m'
+
 require 'kstor/sql_connection'
 require 'kstor/model'
 require 'kstor/log'
 
 module KStor
+  # Simplistic cache for list of users and groups.
+  class StoreCache
+    # Create new cache.
+    def initialize
+      @cache = {}
+      @cache.extend(Mutex_m)
+    end
+
+    class << self
+      # @!macro [new] dsl_storecache_property
+      #   @!attribute $1
+      #     @return returns cached list of $1
+
+      # Declare a cached list of values.
+      #
+      # @param name [Symbol] name of list
+      def property(name)
+        define_method(name) do |&block|
+          @cache.synchronize do
+            return @cache[name] if @cache.key?(name)
+
+            @cache[name] = block.call
+          end
+        end
+
+        define_method("#{name}=".to_sym) do |list|
+          @cache.synchronize { @cache[name] = list }
+        end
+
+        define_method("forget_#{name}") do
+          @cache.synchronize { @cache.delete(name) }
+        end
+      end
+    end
+
+    # @!macro dsl_storecache_property
+    property :users
+    # @!macro dsl_storecache_property
+    property :groups
+  end
+
   # Store and fetch objects in an SQLite database.
   # rubocop:disable Metrics/MethodLength
   class Store
+    # Create a new store backed by the given SQLite database file.
+    #
+    # @param file_path [String] path to SQLite database file
+    # @return [KStor::Store] a data store
     def initialize(file_path)
       @file_path = file_path
       @db = SQLConnection.new(file_path)
-      @cache = {}
+      @cache = StoreCache.new
     end
 
+    # Execute the given block in a database transaction.
     def transaction(&)
       @db.transaction(&)
     end
 
+    # True if database contains any users.
+    #
+    # @return [Boolean] false if user table is empty
     def users?
       rows = @db.execute('SELECT count(*) AS n FROM users')
       count = Integer(rows.first['n'])
@@ -26,25 +77,33 @@ module KStor
       count.positive?
     end
 
+    # Create a new user in database.
+    #
+    # @param user [KStor::Model::User] the user to create
+    # @return [KStor::Model::User] the same user with a brand-new ID
     def user_create(user)
       @db.execute(<<-EOSQL, user.login, user.name, 'new')
         INSERT INTO users (login, name, status)
              VALUES (?, ?, ?)
       EOSQL
-      user.id = @db.last_insert_row_id
+      user_id = @db.last_insert_row_id
       Log.debug("store: stored new user #{user.login}")
       params = [user.kdf_params, user.pubk, user.encrypted_privk].map(&:to_s)
-      return user if params.any?(&:nil?)
+      return user_id if params.any?(&:nil?)
 
       @db.execute(<<-EOSQL, user.id, *params)
         INSERT INTO users_crypto_data (user_id, kdf_params, pubk, encrypted_privk)
              VALUES (?, ?, ?, ?)
       EOSQL
       Log.debug("store: stored user crypto data for #{user.login}")
+      @cache.forget_users
 
-      user
+      user_id
     end
 
+    # Update user name, status and keychain.
+    #
+    # @param user [KStor::Model::User] user to modify.
     def user_update(user)
       @db.execute(<<-EOSQL, user.name, user.status, user.id)
         UPDATE users SET name = ?, status = ?
@@ -60,6 +119,12 @@ module KStor
       EOSQL
     end
 
+    # Add a group private key to a user keychain.
+    #
+    # @param user_id [Integer] ID of an existing user
+    # @param group_id [Integer] ID of an existing group
+    # @param encrypted_privk [KStor::Crypto::ArmoredValue] group private key
+    #   encrypted with user public key
     def keychain_item_create(user_id, group_id, encrypted_privk)
       @db.execute(<<-EOSQL, user_id, group_id, encrypted_privk.to_s)
         INSERT INTO group_members (user_id, group_id, encrypted_privk)
@@ -67,64 +132,79 @@ module KStor
       EOSQL
     end
 
+    # Create a new group.
+    #
+    # Note that it doesn't store the group private key, as it must only exist
+    # in users keychains.
+    #
+    # @param name [String] Name of the new group (must be unique in database)
+    # @param pubk [KStor::Crypto::PublicKey] group public key
+    # @return [Integer] ID of the new group
     def group_create(name, pubk)
       @db.execute(<<-EOSQL, name, pubk.to_s)
         INSERT INTO groups (name, pubk)
              VALUES (?, ?)
       EOSQL
+      @cache.forget_groups
       @db.last_insert_row_id
     end
 
+    # List all groups.
+    #
+    # Note that this list is cached in memory, so calling this method multiple
+    # times should be cheap.
+    #
+    # @return [Array[KStor::Model::Group]] a list of all groups in database
     def groups
-      return @cache[:groups] if @cache.key?(:groups)
-
-      Log.debug('store: loading groups')
-      rows = @db.execute(<<-EOSQL)
-          SELECT id,
-                 name,
-                 pubk
-            FROM groups
-        ORDER BY name
-      EOSQL
-      @cache[:groups] = rows.to_h do |r|
-        a = []
-        a << r['id']
-        a << Model::Group.new(
-          id: r['id'], name: r['name'], pubk: Crypto::PublicKey.new(r['pubk'])
-        )
-        a
+      @cache.groups do
+        Log.debug('store: loading groups')
+        rows = @db.execute(<<-EOSQL)
+            SELECT id,
+                   name,
+                   pubk
+              FROM groups
+          ORDER BY name
+        EOSQL
+        rows.to_h do |r|
+          a = []
+          a << r['id']
+          a << Model::Group.new(
+            id: r['id'], name: r['name'], pubk: Crypto::PublicKey.new(r['pubk'])
+          )
+          a
+        end
       end
     end
 
+    # List all users.
+    #
+    # Note that this list is cached in memory, so calling this method multiple
+    # times should be cheap.
+    #
+    # @return [Array[KStor::Model::User]] a list of all users in database
     def users
-      return @cache[:users] if @cache.key?(:users)
-
-      Log.debug('store: loading users')
-      rows = @db.execute(<<-EOSQL)
-           SELECT u.id,
-                  u.login,
-                  u.name,
-                  u.status,
-                  c.pubk
-             FROM users u
-        LEFT JOIN users_crypto_data c ON (c.user_id = u.id)
-         ORDER BY u.login
-      EOSQL
+      @cache.users do
+        Log.debug('store: loading users')
+        rows = @db.execute(<<-EOSQL)
+             SELECT u.id,
+                    u.login,
+                    u.name,
+                    u.status,
+                    c.pubk
+               FROM users u
+          LEFT JOIN users_crypto_data c ON (c.user_id = u.id)
+           ORDER BY u.login
+        EOSQL
 
-      @cache[:users] = users_from_resultset(rows)
+        users_from_resultset(rows)
+      end
     end
 
-    # in: login
-    # out:
-    #   - ID
-    #   - name
-    #   - status
-    #   - public key
-    #   - key derivation function parameters
-    #   - encrypted private key
-    #   - keychain: hash of:
-    #     - group ID
-    #     - encrypted group private key
+    # Lookup user by login.
+    #
+    # @param login [String] User login
+    # @return [KStor::Model::User, nil] a user object instance with encrypted
+    #   private data, or nil if login was not found in database.
     def user_by_login(login)
       Log.debug("store: loading user by login #{login.inspect}")
       rows = @db.execute(<<-EOSQL, login)
@@ -142,14 +222,11 @@ module KStor
       user_from_resultset(rows, include_crypto_data: true)
     end
 
-    # in: user ID
-    # out:
-    #   - ID
-    #   - name
-    #   - status
-    #   - public key
-    #   - key derivation function parameters
-    #   - encrypted private key
+    # Lookup user by ID.
+    #
+    # @param user_id [Integer] User ID
+    # @return [KStor::Model::User, nil] a user object instance with encrypted
+    #   private data, or nil if login was not found in database.
     def user_by_id(user_id)
       Log.debug("store: loading user by ID ##{user_id}")
       rows = @db.execute(<<-EOSQL, user_id)
@@ -167,12 +244,11 @@ module KStor
       user_from_resultset(rows, include_crypto_data: true)
     end
 
-    # in: user ID
-    # out: array of:
-    #   - secret ID
-    #   - group ID common between user and secret
-    #   - secret encrypted metadata
-    #   - secret value and metadata author IDs
+    # List of all secrets that should be readable by a user.
+    #
+    # @param user_id [Integer] ID of user that will read the secrets
+    # @return [Array[KStor::Model::Secret]] A list of secrets, that may be
+    #   empty.
     def secrets_for_user(user_id)
       Log.debug("store: loading secrets for user ##{user_id}")
       rows = @db.execute(<<-EOSQL, user_id)
@@ -195,8 +271,12 @@ module KStor
       rows.map { |r| secret_from_row(r) }
     end
 
-    # in: secret ID, user ID
-    # out: encrypted value
+    # Fetch one secret by it's ID.
+    #
+    # @param secret_id [Integer] ID of secret
+    # @param user_id [Integer] ID of secret reader
+    # @return [KStor::Model::Secret, nil] A secret, or nil if secret_id was not
+    #   found or user_id can't read it.
     def secret_fetch(secret_id, user_id)
       Log.debug(
         "store: loading secret value ##{secret_id} for user ##{user_id}"
@@ -221,14 +301,16 @@ module KStor
       secret_from_row(rows.first)
     end
 
-    # in:
-    #   - user ID
-    #   - hash of:
-    #     - group ID
-    #     - array of:
-    #       - ciphertext
-    #       - encrypted metadata
-    # out: secret ID
+    # Create a new secret.
+    #
+    # Encrypted data should be a map of group_id to encrypted data for this
+    # group's key pair as a two-value array, first metadata and then value.
+    #
+    # @param author_id [Integer] ID of user that creates the new secret
+    # @param encrypted_data
+    #   [Array[Hash[Integer, Array[KStor::Crypto::ArmoredValue]]]] see above
+    #   description for shape of value.
+    # @return [Integer] ID of new secret
     def secret_create(author_id, encrypted_data)
       Log.debug("store: creating secret for user #{author_id}")
       @db.execute(<<-EOSQL, author_id, author_id)
@@ -242,6 +324,10 @@ module KStor
       secret_id
     end
 
+    # List of group IDs that can read this secret.
+    #
+    # @param secret_id [Integer] ID of secret
+    # @return [Array[KStor::Model::Group]] list of group ids
     def groups_for_secret(secret_id)
       Log.debug("store: loading group IDs for secret #{secret_id}")
       rows = @db.execute(<<-EOSQL, secret_id)
@@ -252,8 +338,13 @@ module KStor
       rows.map { |r| r['group_id'] }
     end
 
-    # in: secret ID, author ID, array of [group ID, encrypted_metadata]
-    # out: nil
+    # Overwrite secret metadata.
+    #
+    # @param secret_id [Integer] ID of secret to update
+    # @param user_id [Integer] ID of user that changes metadata
+    # @param group_encrypted_metadata
+    #   [Array[Hash[Integer, KStor::Crypt::ArmoredValue]]] map of group IDs to
+    #   encrypted metadata.
     def secret_setmeta(secret_id, user_id, group_encrypted_metadata)
       Log.debug("store: set metadata for secret ##{secret_id}")
       @db.execute(<<-EOSQL, user_id, secret_id)
@@ -269,6 +360,13 @@ module KStor
       end
     end
 
+    # Overwrite secret value.
+    #
+    # @param secret_id [Integer] ID of secret to update
+    # @param user_id [Integer] ID of user that changes the value
+    # @param group_ciphertexts
+    #   [Array[Hash[Integer, KStor::Crypt::ArmoredValue]]] map of group IDs to
+    #   encrypted values.
     def secret_setvalue(secret_id, user_id, group_ciphertexts)
       Log.debug("store: set value for secret ##{secret_id}")
       @db.execute(<<-EOSQL, user_id, secret_id)
@@ -284,6 +382,9 @@ module KStor
       end
     end
 
+    # Delete a secrete from database.
+    #
+    # @param secret_id [Integer] ID of secret
     def secret_delete(secret_id)
       Log.debug("store: delete secret ##{secret_id}")
       # Will cascade to secret_values:
@@ -318,6 +419,15 @@ module KStor
       users.to_h { |uu| [uu.id, uu] }
     end
 
+    # Create a new instance of {KStor::Model::User} from a query result rows.
+    #
+    # This will shift (consume) one row from provided array.
+    #
+    # @param rows [Array[Hash[String, Any]]] Array of query result rows
+    # @param include_crypto_data [Boolean] true if new user object should have
+    #   encrypted private key data and keychain
+    # @return [Array[KStor::Model], nil] A new user object, or nil if there
+    #   were no more rows
     def user_from_resultset(rows, include_crypto_data: true)
       return nil if rows.empty?
 

data/lib/kstor/systemd.rb

@@ -6,6 +6,9 @@ module KStor
   # Collection of methods for systemd integration.
   module Systemd
     class << self
+      # Get main socket from systemd
+      #
+      # @return [nil,Socket] The socket or nil if systemd didn't provide
       def socket
         listen_pid = ENV['LISTEN_PID'].to_i
         return nil unless Process.pid == listen_pid
@@ -13,10 +16,12 @@ module KStor
         Socket.for_fd(3)
       end
 
+      # Notify systemd that we're ready to serve clients.
       def service_ready
         SdNotify.ready
       end
 
+      # Notify systemd that we're stopping.
       def service_stopping
         SdNotify.stopping
       end

data/lib/kstor/version.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
 module KStor
-  VERSION = '0.4.2'
+  # Our version number.
+  VERSION = '0.5.0'
 end

data/lib/kstor.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
+require 'kstor/log'
 require 'kstor/config'
 require 'kstor/store'
 require 'kstor/controller'
 require 'kstor/server'
-require 'kstor/log'
 require 'kstor/session'
 require 'kstor/message'
 require 'kstor/version'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kstor
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Jérémie Pierson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-11-05 00:00:00.000000000 Z
+date: 2022-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: journald-logger
@@ -100,15 +100,36 @@ files:
 - lib/kstor/config.rb
 - lib/kstor/controller.rb
 - lib/kstor/controller/authentication.rb
+- lib/kstor/controller/base.rb
 - lib/kstor/controller/request_handler.rb
 - lib/kstor/controller/secret.rb
 - lib/kstor/controller/users.rb
 - lib/kstor/crypto.rb
+- lib/kstor/crypto/armored_value.rb
 - lib/kstor/crypto/ascii_armor.rb
 - lib/kstor/crypto/keys.rb
 - lib/kstor/error.rb
 - lib/kstor/log.rb
+- lib/kstor/log/simple_logger.rb
+- lib/kstor/log/systemd_logger.rb
 - lib/kstor/message.rb
+- lib/kstor/message/base.rb
+- lib/kstor/message/error.rb
+- lib/kstor/message/group_create.rb
+- lib/kstor/message/group_created.rb
+- lib/kstor/message/ping.rb
+- lib/kstor/message/pong.rb
+- lib/kstor/message/secret_create.rb
+- lib/kstor/message/secret_created.rb
+- lib/kstor/message/secret_delete.rb
+- lib/kstor/message/secret_deleted.rb
+- lib/kstor/message/secret_list.rb
+- lib/kstor/message/secret_search.rb
+- lib/kstor/message/secret_unlock.rb
+- lib/kstor/message/secret_update_meta.rb
+- lib/kstor/message/secret_update_value.rb
+- lib/kstor/message/secret_updated.rb
+- lib/kstor/message/secret_value.rb
 - lib/kstor/model.rb
 - lib/kstor/server.rb
 - lib/kstor/session.rb
@@ -117,11 +138,12 @@ files:
 - lib/kstor/store.rb
 - lib/kstor/systemd.rb
 - lib/kstor/version.rb
-homepage: https://github.com/jeremiepierson/kstor
+homepage: https://git.arlol.net/jpi/kstor
 licenses:
 - GPL-3.0-or-later
 metadata:
   rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org/
 post_install_message:
 rdoc_options: []
 require_paths: