masks-server 0.7.0

data/db/migrate/20261010140000_create_groups.rb

@@ -0,0 +1,38 @@
+class CreateGroups < ActiveRecord::Migration[8.1]
+  include Masks::Server::TenantIsolation
+
+  def up
+    create_table :groups do |t|
+      t.references :tenant, null: false, foreign_key: true, index: false
+      t.string :key, null: false
+      t.string :name, null: false
+
+      t.timestamps
+
+      t.index %i[tenant_id key], unique: true
+    end
+
+    create_table :group_members do |t|
+      t.references :tenant, null: false, foreign_key: true, index: false
+      t.references :group, null: false, foreign_key: { on_delete: :cascade }, index: false
+      t.references :actor, null: false, foreign_key: { on_delete: :cascade }
+
+      t.timestamps
+
+      t.index %i[group_id actor_id], unique: true
+    end
+
+    add_column :clients, :allowed_groups, :string, array: true, null: false, default: []
+
+    enable_row_level_security(:groups)
+    enable_row_level_security(:group_members)
+  end
+
+  def down
+    remove_column :clients, :allowed_groups
+    disable_row_level_security(:group_members)
+    disable_row_level_security(:groups)
+    drop_table :group_members
+    drop_table :groups
+  end
+end

data/db/migrate/20261010150000_add_token_lifetimes_to_clients.rb

@@ -0,0 +1,6 @@
+class AddTokenLifetimesToClients < ActiveRecord::Migration[8.1]
+  def change
+    add_column :clients, :access_token_lifetime, :integer
+    add_column :clients, :refresh_token_lifetime, :integer
+  end
+end

data/db/migrate/20261010160000_create_tenant_logos.rb

@@ -0,0 +1,27 @@
+class CreateTenantLogos < ActiveRecord::Migration[8.1]
+  include Masks::Server::TenantIsolation
+
+  def up
+    create_table :tenant_logos do |t|
+      t.references :tenant, null: false, foreign_key: true, index: { unique: true }
+      t.string :content_type, null: false
+      t.string :digest, null: false
+      t.integer :byte_size, null: false
+      t.binary :data, null: false
+
+      t.timestamps
+    end
+
+    enable_row_level_security(:tenant_logos)
+
+    add_column :tenants, :logo_digest, :string
+    add_column :tenants, :accent_color, :string
+  end
+
+  def down
+    remove_column :tenants, :accent_color
+    remove_column :tenants, :logo_digest
+    disable_row_level_security(:tenant_logos)
+    drop_table :tenant_logos
+  end
+end

data/db/migrate/20261011120000_index_pending_approvals.rb

@@ -0,0 +1,5 @@
+class IndexPendingApprovals < ActiveRecord::Migration[8.1]
+  def change
+    add_index :actors, %i[tenant_id pending_approval_at], where: "pending_approval_at IS NOT NULL"
+  end
+end

data/db/migrate/20261011130000_add_key_rotation_days_to_tenants.rb

@@ -0,0 +1,5 @@
+class AddKeyRotationDaysToTenants < ActiveRecord::Migration[8.1]
+  def change
+    add_column :tenants, :key_rotation_days, :integer
+  end
+end

data/db/migrate/20261011140000_add_keys_derived_at_to_tenants.rb

@@ -0,0 +1,5 @@
+class AddKeysDerivedAtToTenants < ActiveRecord::Migration[8.1]
+  def change
+    add_column :tenants, :keys_derived_at, :datetime
+  end
+end

data/db/migrate/20261011150000_add_proof_of_work_to_sign_in_policies.rb

@@ -0,0 +1,5 @@
+class AddProofOfWorkToSignInPolicies < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sign_in_policies, :proof_of_work, :integer, null: false, default: 17
+  end
+end

data/db/migrate/20261011160000_add_password_required_to_sign_in_policies.rb

@@ -0,0 +1,5 @@
+class AddPasswordRequiredToSignInPolicies < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sign_in_policies, :password_required, :boolean, null: false, default: false
+  end
+end

data/db/migrate/20261011170000_create_saml_participations.rb

@@ -0,0 +1,30 @@
+class CreateSamlParticipations < ActiveRecord::Migration[8.1]
+  include Masks::Server::TenantIsolation
+
+  def up
+    create_table :saml_participations do |t|
+      t.references :tenant, null: false, foreign_key: true
+      t.references :session, null: false, foreign_key: { on_delete: :cascade }, index: false
+      t.references :client, null: false, foreign_key: { on_delete: :cascade }, index: false
+      t.string :name_id, null: false
+      t.string :name_id_format, null: false
+      t.string :session_index, null: false
+      t.datetime :notified_at
+
+      t.timestamps
+    end
+
+    add_index :saml_participations, %i[session_id client_id], unique: true
+    add_index :saml_participations, %i[client_id name_id]
+
+    enable_row_level_security(:saml_participations)
+
+    add_column :clients, :saml_slo_url, :string
+  end
+
+  def down
+    remove_column :clients, :saml_slo_url
+    disable_row_level_security(:saml_participations)
+    drop_table :saml_participations
+  end
+end

data/db/migrate/20261011180000_rename_adapters_to_senders.rb

@@ -0,0 +1,45 @@
+class RenameAdaptersToSenders < ActiveRecord::Migration[8.1]
+  include Masks::Server::TenantIsolation
+
+  def up
+    rename_table :adapters, :senders
+    rename_index :senders, "index_adapters_one_primary_per_kind", "index_senders_one_primary_per_kind"
+    rename_actions "adapter.", "sender."
+  end
+
+  def down
+    rename_actions "sender.", "adapter."
+    rename_index :senders, "index_senders_one_primary_per_kind", "index_adapters_one_primary_per_kind"
+    rename_table :senders, :adapters
+  end
+
+  private
+
+    def rename_actions(from, to)
+      across_tenants(:events) do
+        execute <<~SQL
+          UPDATE events
+             SET action = #{quote(to)} || substr(action, #{from.length + 1})
+           WHERE action LIKE #{quote("#{from}%")}
+        SQL
+      end
+
+      across_tenants(:event_streams) do
+        execute <<~SQL
+          UPDATE event_streams
+             SET actions = (
+               SELECT jsonb_agg(
+                        CASE WHEN value LIKE #{quote("#{from}%")}
+                             THEN #{quote(to)} || substr(value, #{from.length + 1})
+                             ELSE value END
+                        ORDER BY ordinality)
+                 FROM jsonb_array_elements_text(actions) WITH ORDINALITY
+             )
+           WHERE EXISTS (
+             SELECT 1 FROM jsonb_array_elements_text(actions) AS held(value)
+              WHERE held.value LIKE #{quote("#{from}%")}
+           )
+        SQL
+      end
+    end
+end

data/lib/generators/masks/server/install/install_generator.rb

@@ -0,0 +1,116 @@
+require "rails/generators/base"
+
+module Masks
+  module Server
+    module Generators
+      class InstallGenerator < ::Rails::Generators::Base
+        source_root File.expand_path("templates", __dir__)
+
+        desc "Mount the masks provider in this app, write its initializer, and say what the database needs."
+
+        class_option :mode, type: :string, default: "engine", enum: %w[engine server],
+                     desc: "engine mounts masks inside this app; server makes this app masks and nothing else"
+        class_option :at, type: :string, default: "/auth",
+                     desc: "The path to mount masks at, in engine mode"
+        class_option :host, type: :string, default: nil,
+                     desc: "A subdomain to serve masks on instead of a path, in engine mode"
+        class_option :database, type: :string, default: "masks",
+                     desc: "The database.yml entry masks keeps its tables in, in engine mode"
+        class_option :tenant, type: :string, default: "app",
+                     desc: "The tenant this app's accounts belong to, in engine mode"
+
+        def create_initializer
+          template "masks_server.rb.tt", "config/initializers/masks_server.rb"
+        end
+
+        def mount_engine
+          route mount_line
+        end
+
+        def serve_ldap
+          return unless File.exist?(File.join(destination_root, "config/puma.rb"))
+
+          append_to_file "config/puma.rb", "\nplugin :masks_ldap\n"
+        end
+
+        def say_what_is_left
+          say ""
+          say "masks is mounted #{where}.", :green
+          say ""
+
+          engine? ? say_engine_database : say_server_database
+
+          say "In production, set MASKS_PUBLIC_ORIGIN_TEMPLATE to #{origin_example}, so the issuer and every"
+          say "emailed link are built from it and never from a request's Host header."
+          say ""
+          say "Then run bin/rails db:prepare and bin/rails masks:tenants, and open #{login_path} to set up"
+          say "the first account with the setup token masks prints."
+          say ""
+        end
+
+        private
+
+          def engine?
+            options[:mode] == "engine"
+          end
+
+          def subdomain?
+            engine? && options[:host].present?
+          end
+
+          def mount_path
+            engine? && !subdomain? ? options[:at] : "/"
+          end
+
+          def mount_line
+            mount = %(mount Masks::Server::Engine, at: "#{mount_path}")
+
+            subdomain? ? %(constraints(host: "#{options[:host]}") { #{mount} }) : mount
+          end
+
+          def where
+            return "at the root of #{options[:host]}" if subdomain?
+
+            "at #{mount_path}"
+          end
+
+          def login_path
+            mount_path == "/" ? "/login" : "#{mount_path}/login"
+          end
+
+          def origin_example
+            return "https://#{options[:host]}" if subdomain?
+            return "https://auth.example.com" unless engine?
+
+            "https://app.example.com#{options[:at]}"
+          end
+
+          def say_engine_database
+            say "Add a database of its own for masks to config/database.yml, in each environment:"
+            say ""
+            say "  #{options[:database]}:"
+            say "    <<: *default"
+            say "    database: #{File.basename(destination_root)}_#{options[:database]}_<%= Rails.env %>"
+            say "    username: masks"
+            say "    migrations_paths: <%= Masks::Server::Engine.root.join(\"db/migrate\") %>"
+            say "    schema_dump: false"
+            say ""
+            say "Its role must hold neither SUPERUSER nor BYPASSRLS, or masks refuses to start: row-level"
+            say "security is what keeps one tenant's accounts and keys away from another's."
+            say ""
+            say "Controllers that need the signed-in account include Masks::Server::Host, which gives them"
+            say "masks_actor and require_masks_actor!." unless subdomain?
+            say "On a subdomain, sign this app in with the masks gem's Masks::Rails, as any other client." if subdomain?
+            say ""
+          end
+
+          def say_server_database
+            say "masks keeps its tables in the primary database. Connect as a role holding neither"
+            say "SUPERUSER nor BYPASSRLS, and set config.active_record.schema_format = :sql, since"
+            say "row-level security does not survive a schema.rb."
+            say ""
+          end
+      end
+    end
+  end
+end

data/lib/generators/masks/server/install/templates/masks_server.rb.tt

@@ -0,0 +1,7 @@
+Rails.application.configure do
+  config.masks.mode = :<%= options[:mode] %>
+<% if engine? -%>
+  config.masks.database = :<%= options[:database] %>
+  config.masks.tenant = "<%= options[:tenant] %>"
+<% end -%>
+end

data/lib/masks/server/configuration.rb

@@ -0,0 +1,134 @@
+require "ipaddr"
+
+module Masks
+  module Server
+    module Configuration
+      MODES = %i[server engine].freeze
+
+      module_function
+
+      def defaults
+        config = ActiveSupport::OrderedOptions.new
+        config.mode = ENV.fetch("MASKS_MODE", "server").to_sym
+        config.database = nil
+        config.secret = nil
+        config.attempt_limit = ENV.fetch("MASKS_ATTEMPT_LIMIT", 10).to_i
+        config.account_attempt_limit = ENV.fetch("MASKS_ACCOUNT_ATTEMPT_LIMIT", 5).to_i
+        config.registration_limit = ENV.fetch("MASKS_REGISTRATION_LIMIT", 10).to_i
+        config.recovery_limit = ENV.fetch("MASKS_RECOVERY_LIMIT", 5).to_i
+        config.device_code_limit = ENV.fetch("MASKS_DEVICE_CODE_LIMIT", 30).to_i
+        config.claim_limit = ENV.fetch("MASKS_CLAIM_LIMIT", 3).to_i
+        config.claim_ceiling = ENV.fetch("MASKS_CLAIM_CEILING", 30).to_i
+        config.setup_token = ENV["MASKS_SETUP_TOKEN"].presence
+        config.recover = ENV["MASKS_RECOVER"].presence
+        config.config_path = ENV["MASKS_CONFIG"].presence
+        config.themes_path = ENV["MASKS_THEMES_PATH"].presence
+        config.docs_url = ENV.fetch("MASKS_DOCS_URL", "https://masks.pages.dev")
+        config.public_origin_template = ENV["MASKS_PUBLIC_ORIGIN_TEMPLATE"].presence
+        config.tenant = ENV["MASKS_TENANT"].presence
+        config.tenants = ENV["MASKS_TENANTS"].to_s.split(/[\s,]+/).reject(&:empty?)
+        config.dynamic_client_scopes = ENV["MASKS_DYNAMIC_CLIENT_SCOPES"].presence
+        config.named_by = ENV["MASKS_NAMED_BY"].presence
+        config.dynamic_registration = ENV["MASKS_DYNAMIC_REGISTRATION"].presence
+        config.browsers_only = ENV["MASKS_BROWSERS_ONLY"].presence
+        config.blocked_agents = ENV["MASKS_BLOCKED_AGENTS"].presence
+        config.mail_from = ENV["MASKS_MAIL_FROM"].presence
+        config.smtp_address = ENV["MASKS_SMTP_ADDRESS"].presence
+        config.smtp_settings = smtp_settings(config.smtp_address)
+        config.invitation_lifetime = ENV.fetch("MASKS_INVITATION_LIFETIME", 7 * 24 * 60 * 60).to_i.seconds
+        config.organization_invitation_lifetime =
+          ENV.fetch("MASKS_ORGANIZATION_INVITATION_LIFETIME", 14 * 24 * 60 * 60).to_i.seconds
+        config.password_reset_lifetime = ENV.fetch("MASKS_PASSWORD_RESET_LIFETIME", 30 * 60).to_i.seconds
+        config.email_verification_lifetime = ENV.fetch("MASKS_EMAIL_VERIFICATION_LIFETIME", 2 * 24 * 60 * 60).to_i.seconds
+        config.outbound_allowed = outbound_allowed(ENV["MASKS_OUTBOUND_ALLOWED"])
+        config.ldap_port = ENV.fetch("MASKS_LDAP_PORT", 3389).to_i
+        config.ldap_cert = ENV["MASKS_LDAP_CERT"].presence
+        config.ldap_key = ENV["MASKS_LDAP_KEY"].presence
+        config
+      end
+
+      def outbound_allowed(value)
+        ranges(value, "MASKS_OUTBOUND_ALLOWED", "List the private ranges masks may call, separated by commas.")
+      end
+
+      def trusted_proxies(value)
+        ActionDispatch::RemoteIp::TRUSTED_PROXIES +
+          ranges(value, "MASKS_TRUSTED_PROXIES", "List the proxies in front of masks, separated by commas.")
+      end
+
+      def ranges(value, variable, advice)
+        value.to_s.split(/[\s,]+/).reject(&:empty?).map do |range|
+          IPAddr.new(range)
+        rescue IPAddr::InvalidAddressError
+          raise "#{variable} holds #{range.inspect}, which is not an address or a range such as 10.20.0.0/16. #{advice}"
+        end
+      end
+
+      def smtp_settings(address)
+        return nil if address.nil?
+
+        port = ENV.fetch("MASKS_SMTP_PORT", 587).to_i
+        implicit_tls = ENV.fetch("MASKS_SMTP_TLS", port == 465 ? "true" : "false") == "true"
+
+        {
+          address: address,
+          port: port,
+          user_name: ENV["MASKS_SMTP_USERNAME"].presence,
+          password: ENV["MASKS_SMTP_PASSWORD"].presence,
+          authentication: ENV.fetch("MASKS_SMTP_AUTHENTICATION", "plain").to_sym,
+          domain: ENV["MASKS_SMTP_DOMAIN"].presence,
+          tls: implicit_tls,
+          enable_starttls: !implicit_tls,
+          openssl_verify_mode: OpenSSL::SSL::VERIFY_PEER,
+          open_timeout: 10,
+          read_timeout: 10
+        }.compact
+      end
+
+      def validate!(config, local:, building:)
+        unless MODES.include?(config.mode)
+          raise "masks runs in server or engine mode, and config.masks.mode is #{config.mode.inspect}."
+        end
+
+        if config.named_by && !%w[nickname email either].include?(config.named_by)
+          raise "MASKS_NAMED_BY is #{config.named_by.inspect}, and the only things an " \
+                "account can be named by are a nickname, an email address, or either one. " \
+                "Set it to nickname, email or either, or leave it unset and let the first-run " \
+                "screen decide."
+        end
+
+        if config.dynamic_registration && !%w[off anything bounded].include?(config.dynamic_registration)
+          raise "MASKS_DYNAMIC_REGISTRATION is #{config.dynamic_registration.inspect}. " \
+                "Dynamic registration is off, on for anything a manager does not have to grant, " \
+                "or on and bounded by MASKS_DYNAMIC_CLIENT_SCOPES. Set it to off, anything or " \
+                "bounded, or leave it unset and let the first-run screen decide."
+        end
+
+        return if local || building
+
+        if config.mail_from && config.smtp_address.nil?
+          raise "MASKS_MAIL_FROM is set but MASKS_SMTP_ADDRESS is not. Mail would be handed to a " \
+                "local sendmail that is not there, and every invitation and password reset would " \
+                "be dropped without an error anyone sees."
+        end
+
+        if config.public_origin_template.nil?
+          raise "MASKS_PUBLIC_ORIGIN_TEMPLATE is required outside development. Without it the " \
+                "issuer, the registration endpoint and every emailed link follow the Host header, " \
+                "so anyone who can reach this server can have a password reset delivered to theirs."
+        end
+
+        if config.setup_token && config.setup_token.length < 24
+          raise "MASKS_SETUP_TOKEN is #{config.setup_token.length} characters, and at least 24 are " \
+                "required outside development. Whoever holds it creates the first account of every " \
+                "tenant that has none, and that account manages the tenant."
+        end
+
+        if config.mode == :engine && config.database.nil?
+          raise "masks in engine mode needs a database of its own. Set config.masks.database to " \
+                "the name of a database.yml entry whose role cannot bypass row-level security."
+        end
+      end
+    end
+  end
+end

data/lib/masks/server/engine.rb

@@ -0,0 +1,60 @@
+module Masks
+  module Server
+    class Engine < ::Rails::Engine
+      isolate_namespace Masks::Server
+
+      config.before_configuration do |app|
+        app.config.masks = Configuration.defaults
+      end
+
+      middleware.use Tenancy::Middleware
+
+      initializer "masks_server.forwarded_app" do |app|
+        app.middleware.insert 0, ForwardedApp
+      end
+
+      config.after_initialize do |app|
+        app.config.masks.themes_path ||= app.root.join("themes").to_s
+
+        Configuration.validate!(
+          app.config.masks,
+          local: ::Rails.env.local?,
+          building: ENV["SECRET_KEY_BASE_DUMMY"].present?
+        )
+
+        middleware.insert_before Tenancy::Middleware, Isolation if app.config.masks.mode == :engine
+      end
+
+      initializer "masks_server.journeys" do
+        ActiveSupport.on_load(:active_job) do
+          require_relative "journey_serializer"
+
+          ActiveJob::Serializers.add_serializers(JourneySerializer)
+        end
+      end
+
+      initializer "masks_server.tenant_setting" do
+        ActiveSupport.on_load(:active_record_postgresqladapter) do
+          set_callback :checkout, :after, -> { TenantIsolation.adopt(self) }
+        end
+      end
+
+      initializer "masks_server.static" do |app|
+        app.middleware.use Rack::Static,
+                           urls: %w[/masks-public /masks-assets],
+                           root: root.join("public").to_s,
+                           header_rules: [
+                             [ :all, { "cache-control" => "public, max-age=3600" } ],
+                             [ "/masks-assets", { "cache-control" => "public, max-age=31536000, immutable" } ]
+                           ]
+      end
+
+      initializer "masks_server.migrations", after: :load_config_initializers do |app|
+        next if app.config.masks.mode == :engine
+        next if app.root.to_s == root.to_s
+
+        config.paths["db/migrate"].expanded.each { |path| app.config.paths["db/migrate"] << path }
+      end
+    end
+  end
+end

data/lib/masks/server/forwarded_app.rb

@@ -0,0 +1,19 @@
+module Masks
+  module Server
+    class ForwardedApp
+      PATH = %r{/forward-auth(?:/callback)?\z}
+      MOVED = %w[HTTP_X_FORWARDED_HOST HTTP_X_FORWARDED_URI HTTP_X_ORIGINAL_URL].freeze
+      KEY = "masks.forwarded_app".freeze
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        env[KEY] = MOVED.to_h { |header| [ header, env.delete(header) ] }.compact if env["PATH_INFO"].to_s.match?(PATH)
+
+        @app.call(env)
+      end
+    end
+  end
+end

data/lib/masks/server/forwarding.rb

@@ -0,0 +1,29 @@
+module Masks
+  module Server
+    class Forwarding
+      HEADERS = %w[HTTP_X_FORWARDED_FOR HTTP_X_FORWARDED_HOST HTTP_CLIENT_IP HTTP_FORWARDED].freeze
+
+      def initialize(app, proxies)
+        @app = app
+        @proxies = proxies
+      end
+
+      def call(env)
+        HEADERS.each { |header| env.delete(header) } unless trusted?(env["REMOTE_ADDR"])
+
+        @app.call(env)
+      end
+
+      private
+
+        def trusted?(address)
+          peer = IPAddr.new(address.to_s.split("%").first)
+          peer = peer.native if peer.ipv4_mapped?
+
+          @proxies.any? { |proxy| proxy.include?(peer) }
+        rescue IPAddr::InvalidAddressError, IPAddr::AddressFamilyError
+          false
+        end
+    end
+  end
+end

data/lib/masks/server/host.rb

@@ -0,0 +1,21 @@
+module Masks
+  module Server
+    module Host
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :masks_actor if respond_to?(:helper_method)
+      end
+
+      def masks_actor
+        return @masks_actor if defined?(@masks_actor)
+
+        @masks_actor = Server.actor_for(request)
+      end
+
+      def require_masks_actor!
+        redirect_to masks_server.login_path(return_to: request.fullpath) unless masks_actor
+      end
+    end
+  end
+end

data/lib/masks/server/isolation.rb

@@ -0,0 +1,34 @@
+module Masks
+  module Server
+    class Isolation
+      HELD = %w[
+        rack.session rack.session.options action_dispatch.cookies
+        action_dispatch.key_generator action_dispatch.secret_key_base
+        action_dispatch.cookies_rotations
+      ].freeze
+
+      SESSION_KEY = "_masks_session".freeze
+
+      def initialize(app)
+        store = ActionDispatch::Session::CookieStore.new(
+          app, key: SESSION_KEY, httponly: true, same_site: :lax, secure: !::Rails.env.local?
+        )
+        @app = ActionDispatch::Cookies.new(store)
+      end
+
+      def call(env)
+        held = HELD.to_h { |key| [ key, env[key] ] }
+        HELD.each { |key| env.delete(key) }
+
+        env["action_dispatch.key_generator"] = Server.key_generator
+        env["action_dispatch.secret_key_base"] = Server.secret_key_base
+        env["action_dispatch.cookies_rotations"] = ActiveSupport::Messages::RotationConfiguration.new
+
+        @app.call(env)
+      ensure
+        HELD.each { |key| env.delete(key) }
+        held.each { |key, value| env[key] = value unless value.nil? }
+      end
+    end
+  end
+end

data/lib/masks/server/journey_serializer.rb

@@ -0,0 +1,17 @@
+module Masks
+  module Server
+    class JourneySerializer < ActiveJob::Serializers::ObjectSerializer
+      def serialize(journey)
+        super(journey.dump)
+      end
+
+      def deserialize(held)
+        Journey.load(held)
+      end
+
+      def klass
+        Journey
+      end
+    end
+  end
+end