open-loam 0.1.0

data/lib/generators/loam/install/templates/migrations/create_loam_search_tokens.rb

@@ -0,0 +1,18 @@
+class CreateLoamSearchTokens < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_search_tokens<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :searchable_type, null: false  # the entity class name (e.g. "Gadget")
+      t.<%= loam_key_column_type %> :searchable_id<%= loam_key_limit_option %>, null: false     # the record it indexes
+      t.string :token, null: false             # one normalized word
+    end
+    # The match subquery filters by (tenant, type, token); index maintenance
+    # deletes by (tenant, type, record). One index each — no timestamps: these
+    # are plumbing rows written with insert_all/delete_all.
+    #
+    # Shipped even though the default LikeDriver never uses it, so switching to
+    # Loam::Search::TokenDriver is a one-line initializer change, not a migration.
+    add_index :loam_search_tokens, %i[tenant_id searchable_type token]
+    add_index :loam_search_tokens, %i[tenant_id searchable_type searchable_id]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_sso_providers.rb

@@ -0,0 +1,34 @@
+class CreateLoamSsoProviders < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_sso_providers<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :name, null: false
+      t.string :protocol, null: false, default: "oidc"  # "oidc" shipped; "saml" is a seam
+      t.string :issuer                                    # OIDC discovery base (.well-known)
+      t.string :client_id
+      t.text :client_secret                               # ENCRYPTED at rest (tenant-scoped key)
+      t.string :domain, null: false                       # email domain for home-realm discovery
+      t.string :jit_role, null: false, default: "employee"  # role for JIT-provisioned users
+      t.json :group_role_map, null: false, default: {}    # IdP group -> Loam role (first match wins)
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    # HRD resolves a provider by email domain, cross-tenant, before login — so the
+    # domain is globally unique (one owning IdP per domain).
+    add_index :loam_sso_providers, :domain, unique: true
+    add_index :loam_sso_providers, %i[tenant_id active]
+
+    # The durable link between an external identity (provider + subject) and a
+    # local User — the primary lookup on callback (email can change at the IdP,
+    # `sub` does not).
+    create_table :loam_sso_identities<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.references :sso_provider, null: false, foreign_key: { to_table: :loam_sso_providers }<%= loam_type_option %>
+      t.<%= loam_key_column_type %> :user_id<%= loam_key_limit_option %>, null: false  # the local User this identity belongs to
+      t.string :sub, null: false      # the IdP's stable subject identifier
+      t.timestamps
+    end
+    add_index :loam_sso_identities, %i[sso_provider_id sub], unique: true
+    add_index :loam_sso_identities, :user_id
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_tenants.rb

@@ -0,0 +1,9 @@
+class CreateLoamTenants < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_tenants<%= loam_id_option %> do |t|
+      t.string :name, null: false
+      t.string :slug, null: false, index: { unique: true }
+      t.timestamps
+    end
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_translations.rb

@@ -0,0 +1,15 @@
+class CreateLoamTranslations < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_translations<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :translatable_type, null: false
+      t.<%= loam_key_column_type %> :translatable_id<%= loam_key_limit_option %>, null: false
+      t.string :locale, null: false            # "en", "de", "pl"
+      t.string :field, null: false             # the translated attribute
+      t.text :value                            # the per-locale content
+      t.timestamps
+    end
+    add_index :loam_translations, %i[translatable_type translatable_id locale field],
+              unique: true, name: "index_loam_translations_unique"
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_loam_webhook_endpoints.rb

@@ -0,0 +1,13 @@
+class CreateLoamWebhookEndpoints < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :loam_webhook_endpoints<%= loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :loam_tenants }<%= loam_type_option %>
+      t.string :url, null: false
+      t.string :event_pattern, null: false
+      t.string :secret, null: false
+      t.boolean :active, null: false, default: true
+      t.timestamps
+    end
+    add_index :loam_webhook_endpoints, %i[tenant_id active]
+  end
+end

data/lib/generators/loam/install/templates/migrations/create_users.rb

@@ -0,0 +1,13 @@
+class CreateUsers < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :users<%= loam_id_option %> do |t|
+      t.string :name, null: false
+      t.string :email, null: false
+      t.string :password_digest, null: false
+      t.timestamps
+    end
+    # Email is the login, so uniqueness is enforced by the database, not only
+    # by the model.
+    add_index :users, :email, unique: true
+  end
+end

data/lib/generators/loam/install/templates/user.rb

@@ -0,0 +1,21 @@
+# Minimal actor model. Deliberately NOT tenant-scoped: a user can belong to
+# many tenants via Loam::Membership (role is per tenant). Swap in your real
+# auth (Devise, OmniAuth, SSO) later — Loam only needs an `id` and, for the
+# bundled admin login, something that answers `authenticate_by`.
+class User < ApplicationRecord
+  # Loam's foreign keys point at this table, so its key has to be generated
+  # the same way theirs are when the app does not use integer keys.
+  include Loam::GeneratedKey
+
+  has_secure_password
+
+  has_many :loam_memberships, class_name: "Loam::Membership"
+
+  validates :name, presence: true
+  validates :email, presence: true, uniqueness: true
+
+  # Email is the login, so it must mean the same thing however it was typed.
+  # `normalizes` applies on write AND to finders, so User.authenticate_by and
+  # find_by match a mixed-case address without callers downcasing anything.
+  normalizes :email, with: ->(email) { email.to_s.strip.downcase }
+end

data/lib/generators/loam/primary_key_options.rb

@@ -0,0 +1,101 @@
+module Loam
+  module Generators
+    # Shared primary-key shaping for `loam:install` and `loam:entity`.
+    #
+    # Loam's migrations used to spell every key `bigint` — implicitly in
+    # `create_table`, and explicitly in `t.references` and the polymorphic
+    # `*_id` columns. In an app whose own tables use string or uuid keys the
+    # foreign keys then do not line up with the tables they point at, and every
+    # generated migration has to be hand-edited after the generator runs.
+    #
+    # The key type is taken from, in order: an explicit --primary-key-type, the
+    # host app's own `config.generators` setting (so an app that already told
+    # Rails what its keys look like does not have to tell Loam separately), and
+    # bigint as the Rails default.
+    #
+    # The templates ask for the *rendered fragment* rather than the type, so
+    # bigint keeps emitting exactly the migrations it emitted before — no `id:`
+    # and no `type:` — and only a non-default key type adds anything.
+    module PrimaryKeyOptions
+      SUPPORTED = %w[bigint uuid string].freeze
+
+      # varchar(36) is the usual shape for a UUID stored as a string, and it is
+      # the case in the report that prompted this. An app that stores them some
+      # other width passes --key-limit.
+      DEFAULT_STRING_LIMIT = 36
+
+      def self.included(base)
+        base.class_option :primary_key_type, type: :string, default: nil,
+                                             desc: "Key type for the generated tables: #{SUPPORTED.join(', ')}. " \
+                                                   "Defaults to the app's config.generators primary_key_type, then bigint."
+        base.class_option :key_limit, type: :numeric, default: nil,
+                                      desc: "Column limit for a string key (default #{DEFAULT_STRING_LIMIT}). Ignored for bigint and uuid."
+      end
+
+      private
+
+      def loam_key_type
+        @loam_key_type ||= begin
+          requested = (options[:primary_key_type] || host_app_primary_key_type).to_s
+          requested = "bigint" if requested.empty?
+
+          unless SUPPORTED.include?(requested)
+            raise Thor::Error,
+                  "Unsupported --primary-key-type #{requested.inspect}. Loam generates #{SUPPORTED.join(', ')}. " \
+                  "A key type Loam does not know how to size would produce migrations that look right and " \
+                  "do not line up with your tables."
+          end
+
+          requested.to_sym
+        end
+      end
+
+      # What the host app already told Rails its keys look like. Absent outside
+      # a booted application (the generator specs), which is the bigint case.
+      def host_app_primary_key_type
+        return nil unless defined?(Rails) && Rails.application
+
+        Rails.application.config.generators.options.dig(:active_record, :primary_key_type)
+      rescue StandardError
+        nil
+      end
+
+      def loam_key_limit
+        return options[:key_limit].to_i if options[:key_limit]
+
+        loam_key_type == :string ? DEFAULT_STRING_LIMIT : nil
+      end
+
+      # Appended to `create_table :x` — "" for bigint, so the default path is
+      # byte-for-byte what it was.
+      def loam_id_option
+        return "" if loam_key_type == :bigint
+
+        "#{loam_key_fragment.sub('type:', 'id:')}"
+      end
+
+      # Appended inside `t.references :x, ...`.
+      def loam_type_option
+        return "" if loam_key_type == :bigint
+
+        loam_key_fragment
+      end
+
+      # The bare column type for a polymorphic or un-constrained `*_id`, which
+      # cannot use t.references.
+      def loam_key_column_type
+        loam_key_type
+      end
+
+      def loam_key_limit_option
+        loam_key_limit ? ", limit: #{loam_key_limit}" : ""
+      end
+
+      def loam_key_fragment
+        fragment = ", type: :#{loam_key_type}"
+        fragment += ", limit: #{loam_key_limit}" if loam_key_limit
+        fragment
+      end
+    end
+  end
+end

data/lib/loam/attachable.rb

@@ -0,0 +1,27 @@
+module Loam
+  # Files on a record, via ActiveStorage:
+  #
+  #   equipment.files.attach(io: File.open(path), filename: "manual.pdf")
+  #   equipment.files.each { |file| url_for(file) }
+  #
+  # KNOWN BOUNDARY: ActiveStorage blobs live in global tables that Loam does
+  # NOT tenant-scope. The association is scoped (a record only ever lists its
+  # own files, and the record is tenant-scoped), but a signed blob URL is a
+  # bearer capability: whoever holds the link can fetch the file, with no
+  # tenant check. Gate access at the record — through its policy — and treat
+  # attachment URLs as secrets rather than as addresses.
+  module Attachable
+    extend ActiveSupport::Concern
+
+    included do
+      unless respond_to?(:has_many_attached)
+        raise Loam::Error,
+              "#{name} includes Loam::Attachable but ActiveStorage is not available. " \
+              "Run `bin/rails active_storage:install && bin/rails db:migrate`, or remove the include " \
+              "(this app was probably generated with --skip-active-storage)."
+      end
+
+      has_many_attached :files
+    end
+  end
+end

data/lib/loam/auditable.rb

@@ -0,0 +1,67 @@
+module Loam
+  # Audit-by-default. Included in every generated entity: create/update/destroy
+  # writes a Loam::AuditRecord tagged with tenant + actor + changeset. "Who
+  # changed the excavator's price, and when" is answered structurally, not by
+  # remembering to log.
+  module Auditable
+    extend ActiveSupport::Concern
+
+    IGNORED_ATTRIBUTES = %w[updated_at created_at].freeze
+
+    included do
+      after_create  { loam_audit("create") }
+      after_update  { loam_audit(loam_audit_action) if loam_audit_changes.any? }
+      after_destroy { loam_audit("destroy") }
+    end
+
+    private
+
+    # Relabel the audit that the save inside the block writes. Loam::SoftDeletable
+    # uses this to record a soft-delete (an UPDATE) as "soft_delete"/"restore"
+    # rather than the "update" it would otherwise be — one audit path, reused,
+    # not a second one to keep in sync.
+    def loam_audit_as(action)
+      previous = @loam_audit_action
+      @loam_audit_action = action
+      yield
+    ensure
+      @loam_audit_action = previous
+    end
+
+    def loam_audit_action
+      @loam_audit_action || "update"
+    end
+
+    def loam_audit(action)
+      Loam::AuditRecord.create!(
+        auditable_type: self.class.name,
+        auditable_id: id,
+        action: action,
+        actor_id: Loam::Current.actor&.id,
+        changeset: action == "destroy" ? {} : loam_audit_changes
+      )
+    end
+
+    def loam_audit_changes
+      changes = saved_changes.except(*IGNORED_ATTRIBUTES)
+      loam_redact_encrypted(changes)
+    end
+
+    # The audit trail must record the FACT that an encrypted field changed, never
+    # its value — neither the plaintext nor the ciphertext (a ciphertext still
+    # leaks length and, over time, correlations). So an encrypted column's change
+    # becomes "[encrypted]", and its blind-index sibling is dropped entirely.
+    # A no-op for models without Loam::Encryptable.
+    def loam_redact_encrypted(changes)
+      return changes unless self.class.respond_to?(:loam_encrypted_attributes)
+
+      encrypted = self.class.loam_encrypted_attributes.map(&:to_s)
+      hash_columns = self.class.loam_searchable_encrypted_attributes.map { |name| "#{name}_hash" }
+
+      changes.each_with_object({}) do |(column, values), redacted|
+        next if hash_columns.include?(column)
+        redacted[column] = encrypted.include?(column) ? "[encrypted]" : values
+      end
+    end
+  end
+end

data/lib/loam/auth_throttle.rb

@@ -0,0 +1,83 @@
+module Loam
+  # Rate-limiting + lockout for authentication, to blunt online brute-force of
+  # passwords and (especially) 6-digit TOTP codes. A DB-backed counter keyed by
+  # the submitted identifier: after N failures within a window, the identifier is
+  # locked; a success clears the counter.
+  #
+  #   Loam::AuthThrottle.locked?(email)                      # refuse if true
+  #   Loam::AuthThrottle.record_failure(email, kind: "password", ip: request.ip)
+  #   Loam::AuthThrottle.clear(email)                        # on success
+  #
+  # PER-IDENTIFIER is the primary defense (an attacker targets one account /
+  # code). A per-ip throttle to blunt spraying across accounts is a clean
+  # addition behind the same store (record_failure takes an ip) but not wired by
+  # default — noted as a roadmap knob. Rack::Attack is the PRODUCTION tool
+  # (needs a cache store + a gem); this DB counter is the portable,
+  # single-process-correct prototype.
+  #
+  # Thresholds come from Loam::Configs (per-tenant-overridable, but read globally
+  # here at the auth layer with sane defaults):
+  #   security.max_auth_attempts   (default 10)
+  #   security.auth_window_minutes (default 15) — failures counted in this window
+  #   security.auth_lockout_minutes(default 15) — how long "try again in N" reports
+  module AuthThrottle
+    module_function
+
+    def max_attempts
+      Loam::Configs.get("security.max_auth_attempts", default: 10).to_i
+    end
+
+    def window
+      Loam::Configs.get("security.auth_window_minutes", default: 15).to_i.minutes
+    end
+
+    def lockout
+      Loam::Configs.get("security.auth_lockout_minutes", default: 15).to_i.minutes
+    end
+
+    # Log a failed attempt. Recorded for ANY submitted identifier — existing or
+    # not — so a lockout can never become an account-existence oracle.
+    def record_failure(identifier, kind:, ip: nil)
+      identifier = normalize(identifier)
+      return if identifier.blank?
+
+      Loam::AuthAttempt.create!(identifier: identifier, kind: kind.to_s, ip: ip)
+    end
+
+    # Locked if there are >= max failures within the window. Old attempts age out
+    # of the window automatically (the window query IS the expiry — no reaper).
+    def locked?(identifier, kind: nil)
+      recent_failures(identifier, kind: kind) >= max_attempts
+    end
+
+    def recent_failures(identifier, kind: nil)
+      scope = attempts(identifier).where("created_at > ?", window.ago)
+      scope = scope.where(kind: kind.to_s) if kind
+      scope.count
+    end
+
+    # Reset the counter — call on a SUCCESSFUL auth so a legitimate user who
+    # eventually gets in isn't left throttled.
+    def clear(identifier)
+      attempts(identifier).delete_all
+    end
+
+    # Seconds until the identifier unlocks (for the "try again in N" message),
+    # or 0 when not locked.
+    def remaining_lockout(identifier)
+      last = attempts(identifier).maximum(:created_at)
+      return 0 unless last
+
+      seconds = (last + [ window, lockout ].max - Time.current).to_i
+      seconds.positive? ? seconds : 0
+    end
+
+    def attempts(identifier)
+      Loam::AuthAttempt.where(identifier: normalize(identifier))
+    end
+
+    def normalize(identifier)
+      identifier.to_s.strip.downcase
+    end
+  end
+end

data/lib/loam/base32.rb

@@ -0,0 +1,23 @@
+module Loam
+  # RFC 4648 Base32 — the encoding authenticator apps expect for a TOTP secret.
+  # Ruby ships Base64 but not Base32, and this is ~15 lines, so no dependency.
+  # No padding on encode (authenticators don't want it); decode ignores case,
+  # spaces and `=` padding so a secret pasted from anywhere still works.
+  module Base32
+    ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567".freeze
+
+    def self.encode(bytes)
+      bits = bytes.bytes.map { |byte| byte.to_s(2).rjust(8, "0") }.join
+      # Pad the bit string up to a multiple of 5, then map each 5 bits to a char.
+      bits += "0" * ((5 - bits.length % 5) % 5)
+      bits.scan(/.{5}/).map { |chunk| ALPHABET[chunk.to_i(2)] }.join
+    end
+
+    def self.decode(string)
+      clean = string.to_s.upcase.gsub(/[^A-Z2-7]/, "")
+      bits = clean.each_char.map { |char| ALPHABET.index(char).to_s(2).rjust(5, "0") }.join
+      # Only whole bytes are data; the trailing <8 bits are encoding padding.
+      bits.scan(/.{8}/).map { |byte| byte.to_i(2).chr }.join.b
+    end
+  end
+end

data/lib/loam/bulk.rb

@@ -0,0 +1,59 @@
+module Loam
+  # Datatable bulk actions over selected records — policy-checked PER record and
+  # tenant-scoped. The ids are resolved THROUGH the tenant scope
+  # (`model.where(id: ids)`), so a forged cross-tenant id is simply not found —
+  # a bulk op can never reach another tenant's rows.
+  #
+  #   Loam::Bulk.soft_delete(Equipment, params[:ids])
+  #   Loam::Bulk.set_field(Equipment, params[:ids], field: "status", value: "retired")
+  #
+  # Returns the number of records actually affected (a record the actor may not
+  # touch, or an id from another tenant, is silently skipped).
+  module Bulk
+    module_function
+
+    def soft_delete(model, ids)
+      each_permitted(model, ids) do |record, policy|
+        next unless policy.destroy?
+
+        record.soft_delete!
+        true
+      end
+    end
+
+    def set_field(model, ids, field:, value:)
+      field = field.to_s
+      each_permitted(model, ids) do |record, policy|
+        next unless policy.update? && policy.writable?(field) && writable_column?(model, field)
+
+        record.update!(field => value)
+        true
+      end
+    end
+
+    # A relation for "export selected" — tenant-scoped, so it composes with
+    # Loam::Export.csv and can't leak another tenant's rows.
+    def selected(model, ids)
+      model.where(id: Array(ids))
+    end
+
+    def each_permitted(model, ids)
+      count = 0
+      selected(model, ids).find_each do |record|
+        count += 1 if yield(record, Loam::Policy.for(record))
+      end
+      count
+    end
+
+    def writable_column?(model, field)
+      model.column_names.include?(field) && Loam::Import::PLUMBING.exclude?(field) && !workflow_column?(model, field)
+    end
+
+    # A workflow status column may ONLY change through a transition (role-gated).
+    # Skip it here so a bulk set-field can't self-"approve" (the model guard is
+    # the backstop; this keeps the bulk op a clean no-op rather than an error).
+    def workflow_column?(model, field)
+      model.respond_to?(:loam_workflow) && model.loam_workflow&.column == field
+    end
+  end
+end

data/lib/loam/business_rules/actions.rb

@@ -0,0 +1,92 @@
+module Loam
+  module BusinessRules
+    # The typed action vocabulary — a FIXED, safe set the engine dispatches. No
+    # arbitrary code: an action is a json descriptor with a `type` and known
+    # keys. `call_webhook` is deferred (emit_event → a webhook endpoint already
+    # covers it).
+    module Actions
+      PLUMBING = %w[id tenant_id lock_version deleted_at created_at updated_at].freeze
+
+      # Run one action against the record that triggered the rule. Returns a
+      # short label of what it did (for the execution log). `:veto` is the
+      # block_transition signal (see Loam::BusinessRules.veto?).
+      def self.run(action, record)
+        case action["type"].to_s
+        when "notify"           then run_notify(action, record)
+        when "emit_event"       then run_emit_event(action)
+        when "set_field"        then run_set_field(action, record)
+        when "block_transition" then :veto
+        else raise ArgumentError, "unknown action type #{action["type"].inspect}"
+        end
+      end
+
+      def self.run_notify(action, _record)
+        title = action["title"].to_s
+        body = action["body"]
+        if action["role"].present?
+          Loam::Notifications.notify_role(action["role"], title: title, body: body)
+        elsif action["user_id"].present?
+          user = User.find_by(id: action["user_id"])
+          Loam::Notifications.notify(user, title: title, body: body) if user
+        end
+        "notify"
+      end
+
+      # Publish validates the name format (raising InvalidEventNameError), so a
+      # malformed event name is caught by the engine's per-rule isolation.
+      def self.run_emit_event(action)
+        Loam::Events.publish(action["name"], (action["payload"] || {}).symbolize_keys)
+        "emit_event(#{action["name"]})"
+      end
+
+      # Assign a whitelisted attribute or custom field on the TRIGGERING record.
+      # Refused: the workflow status column (would bypass the transition gate —
+      # use a transition), and plumbing columns. The change is saved as the
+      # event's actor, and the rule is identifiable via the execution log.
+      def self.run_set_field(action, record)
+        field = action["field"].to_s
+        refuse_workflow_column!(record, field)
+        refuse_credential_column!(field)
+        refuse_cross_tenant!(record)
+
+        if writable_column?(record.class, field)
+          record.update!(field => action["value"])
+        elsif Condition.custom_field?(record, field)
+          record.set_custom_field(field, action["value"])
+          record.save!
+        else
+          raise ArgumentError, "set_field: #{field.inspect} is not a writable column or custom field"
+        end
+        "set_field(#{field})"
+      end
+
+      def self.writable_column?(klass, field)
+        klass.column_names.include?(field) && PLUMBING.exclude?(field)
+      end
+
+      def self.refuse_workflow_column!(record, field)
+        return unless record.class.respond_to?(:loam_workflow) && record.class.loam_workflow&.column == field
+
+        raise ArgumentError, "set_field must not write the workflow column #{field.inspect} — use a transition"
+      end
+
+      # A business rule has no business setting credentials, even on a
+      # tenant-scoped record: never a password column, a *_digest, or email.
+      def self.refuse_credential_column!(field)
+        normalized = field.downcase
+        return unless normalized.include?("password") || normalized.end_with?("_digest") || normalized == "email"
+
+        raise ArgumentError, "set_field must not write the credential column #{field.inspect}"
+      end
+
+      # Belt-and-suspenders: subject_for only ever loads a current-tenant record,
+      # but never write one whose tenant is not the tenant in context.
+      def self.refuse_cross_tenant!(record)
+        return unless record.respond_to?(:tenant_id)
+        return if record.tenant_id == Loam.tenant!.id
+
+        raise ArgumentError, "set_field refuses a record outside the current tenant"
+      end
+    end
+  end
+end