open-loam 0.1.1 → 0.3.0

data/lib/{loam → open_loam}/event_stream.rb

@@ -1,14 +1,14 @@
-module Loam
-  # The real-time bridge: pushes selected Loam events to a browser over
+module OpenLoam
+  # The real-time bridge: pushes selected OpenLoam events to a browser over
   # Server-Sent Events, so the admin updates live instead of polling.
   #
   # SECURITY POSTURE — default OFF. An event reaches a browser only if ALL hold:
-  #   * its name matches a declared Loam.broadcast_events pattern (opt-in), AND
+  #   * its name matches a declared OpenLoam.broadcast_events pattern (opt-in), AND
   #   * its tenant matches the connected tenant (isolation), AND
   #   * its audience includes the connected actor (a payload `user_id`, if any,
   #     is the sole recipient; no `user_id` means tenant-wide).
   #
-  # FAN-OUT is behind a swappable broadcaster seam (Loam::EventStream.broadcaster).
+  # FAN-OUT is behind a swappable broadcaster seam (OpenLoam::EventStream.broadcaster).
   # The default in-process broadcaster only sees events published in THIS process
   # — fine for the single-process prototype; a multi-process deploy swaps in a
   # Redis/SolidCable-backed broadcaster with no controller change (see
@@ -24,10 +24,10 @@ module Loam
       # Is this event name allowed to reach browsers at all? Empty allow-list →
       # false, always (nothing leaks by default).
       def broadcastable?(event_name)
-        Loam.broadcast_events.any? do |pattern|
-          next false if Loam::Overrides.disabled?(:broadcast_events, pattern) # an app can turn a default pattern off
+        OpenLoam.broadcast_events.any? do |pattern|
+          next false if OpenLoam::Overrides.disabled?(:broadcast_events, pattern) # an app can turn a default pattern off
 
-          Loam::Events.pattern_matches?(pattern, event_name)
+          OpenLoam::Events.pattern_matches?(pattern, event_name)
         end
       end
 
@@ -42,9 +42,9 @@ module Loam
         recipient.nil? || recipient == actor&.id
       end
 
-      # One SSE message: an `event:` line (the Loam event name) and a `data:`
+      # One SSE message: an `event:` line (the OpenLoam event name) and a `data:`
       # line (JSON), ended by a blank line. Only small id-ish keys ride along —
-      # Loam events carry no attribute values, and this slices to a safe set as
+      # OpenLoam events carry no attribute values, and this slices to a safe set as
       # belt-and-suspenders (tenant_id is dropped; it is implied by the connection).
       def frame(event_name, payload)
         "event: #{event_name}\ndata: #{safe_payload(payload).to_json}\n\n"
@@ -54,21 +54,21 @@ module Loam
 
       def safe_payload(payload)
         # id-ish keys only — never attribute values. percent/status ride along for
-        # the progress bar (Loam::ProgressJob); both are non-sensitive.
+        # the progress bar (OpenLoam::ProgressJob); both are non-sensitive.
         payload.symbolize_keys.slice(:id, :type, :user_id, :from, :to, :percent, :status).compact
       end
     end
 
-    # The default fan-out: subscribe to Loam::Events in THIS process and forward
+    # The default fan-out: subscribe to OpenLoam::Events in THIS process and forward
     # the events deliverable to (tenant, actor) to a sink. A `sink` is anything
     # answering #call(sse_string) — the controller's is a Queue push.
     class InProcessBroadcaster
       # Returns an opaque handle to pass back to #unsubscribe.
       def subscribe(tenant:, actor:, &sink)
-        Loam::Events.subscribe_all do |event_name, payload|
-          next unless Loam::EventStream.deliverable?(event_name, payload, tenant: tenant, actor: actor)
+        OpenLoam::Events.subscribe_all do |event_name, payload|
+          next unless OpenLoam::EventStream.deliverable?(event_name, payload, tenant: tenant, actor: actor)
 
-          sink.call(Loam::EventStream.frame(event_name, payload))
+          sink.call(OpenLoam::EventStream.frame(event_name, payload))
         end
       end
 

data/lib/{loam → open_loam}/eventful.rb

@@ -1,18 +1,18 @@
-module Loam
+module OpenLoam
   # Lifecycle events by convention. Included in every generated entity:
   #
-  #   class Equipment < Loam::TenantRecord
-  #     include Loam::Eventful
+  #   class Equipment < OpenLoam::TenantRecord
+  #     include OpenLoam::Eventful
   #     event_domain :rental          # -> "rental.equipment.created" etc.
   #   end
   #
-  # Custom business events are published explicitly with Loam::Events.publish.
+  # Custom business events are published explicitly with OpenLoam::Events.publish.
   module Eventful
     extend ActiveSupport::Concern
 
     included do
-      class_attribute :loam_event_domain, default: "app"
-      class_attribute :loam_event_entity, default: nil
+      class_attribute :open_loam_event_domain, default: "app"
+      class_attribute :open_loam_event_entity, default: nil
 
       after_create_commit  { publish_lifecycle_event("created") }
       after_update_commit  { publish_lifecycle_event("updated") }
@@ -21,23 +21,23 @@ module Loam
 
     class_methods do
       def event_domain(domain)
-        self.loam_event_domain = domain.to_s
+        self.open_loam_event_domain = domain.to_s
       end
 
       # The middle segment of the event name. It defaults to the model's param
       # key, which is right for app models but awkward for namespaced ones —
-      # Loam::Comment would publish "loam.loam_comment.created" rather than
-      # "loam.comment.created".
+      # OpenLoam::Comment would publish "open_loam.open_loam_comment.created" rather than
+      # "open_loam.comment.created".
       def event_entity(name)
-        self.loam_event_entity = name.to_s
+        self.open_loam_event_entity = name.to_s
       end
     end
 
     private
 
     def publish_lifecycle_event(happened)
-      Loam::Events.publish(
-        "#{loam_event_domain}.#{loam_event_entity || model_name.param_key}.#{happened}",
+      OpenLoam::Events.publish(
+        "#{open_loam_event_domain}.#{open_loam_event_entity || model_name.param_key}.#{happened}",
         { id: id, type: self.class.name }
       )
     end

data/lib/{loam → open_loam}/events.rb

@@ -1,4 +1,4 @@
-module Loam
+module OpenLoam
   # A thin domain event bus over ActiveSupport::Notifications.
   #
   # Convention: event names are `domain.thing.happened`, e.g.
@@ -7,7 +7,7 @@ module Loam
   # subscribers are always tenant-aware.
   module Events
     NAME_FORMAT = /\A[a-z0-9_]+(\.[a-z0-9_]+){2,}\z/
-    PREFIX = "loam.event."
+    PREFIX = "open_loam.event."
 
     def self.publish(name, payload = {})
       name = name.to_s
@@ -17,12 +17,12 @@ module Loam
 
       ActiveSupport::Notifications.instrument(
         PREFIX + name,
-        payload.merge(tenant_id: Loam::Current.tenant&.id, actor_id: Loam::Current.actor&.id)
+        payload.merge(tenant_id: OpenLoam::Current.tenant&.id, actor_id: OpenLoam::Current.actor&.id)
       )
     end
 
     # The subscription rule, in one place: a trailing dot is a domain prefix,
-    # anything else is an exact event name. Loam::WebhookEndpoint matches
+    # anything else is an exact event name. OpenLoam::WebhookEndpoint matches
     # against this too, so a pattern means the same thing everywhere.
     def self.pattern_matches?(pattern, event_name)
       pattern = pattern.to_s
@@ -31,7 +31,7 @@ module Loam
       pattern.end_with?(".") ? event_name.start_with?(pattern) : event_name == pattern
     end
 
-    # Every Loam event, whatever its domain — the empty prefix matches them
+    # Every OpenLoam event, whatever its domain — the empty prefix matches them
     # all. Used by the webhook dispatcher, which decides per event which
     # endpoints care.
     def self.subscribe_all(&block)

data/lib/{loam → open_loam}/export.rb

@@ -1,16 +1,17 @@
 require "csv"
 
-module Loam
+module OpenLoam
   # CSV export of a tenant-scoped relation, POLICY- and ENCRYPTION-aware:
   #
-  #   Loam::Export.csv(Equipment.all, actor: current_actor)
+  #   OpenLoam::Export.csv(Equipment.all, actor: current_actor)
   #
-  # * only fields the actor's role may READ are columns (Loam::Policy#readable?);
+  # * only fields the actor's role may READ are columns (OpenLoam::Policy#readable?);
   # * an ENCRYPTED column is NEVER exported in the clear — its cell is
   #   "[encrypted]" (the same redaction as the audit trail), so a bulk export can
   #   never become a plaintext dump of PII a role shouldn't see;
-  # * declared custom fields are included (a dictionary field exports its stored
-  #   code, so the file round-trips back through Loam::Import);
+  # * declared custom fields go through the same read check
+  #   (OpenLoam::Policy#custom_field_readable?) — a dictionary field exports its
+  #   stored code, so the file round-trips back through OpenLoam::Import;
   # * tenant isolation is free — the relation is already scoped.
   #
   # Prototype scale: builds the CSV in memory with the stdlib CSV. A very large
@@ -37,10 +38,10 @@ module Loam
     # redacted), then declared custom fields.
     def exportable_columns(model, actor)
       policy = policy_for(model, actor)
-      encrypted = model.respond_to?(:loam_encrypted_attributes) ? model.loam_encrypted_attributes : []
+      encrypted = model.respond_to?(:open_loam_encrypted_attributes) ? model.open_loam_encrypted_attributes : []
       # The blind-index columns behind searchable encrypted fields (e.g.
       # email_hash) are internal HMACs — never export them either.
-      blind = model.respond_to?(:loam_searchable_encrypted_attributes) ? model.loam_searchable_encrypted_attributes.map { |a| "#{a}_hash" } : []
+      blind = model.respond_to?(:open_loam_searchable_encrypted_attributes) ? model.open_loam_searchable_encrypted_attributes.map { |a| "#{a}_hash" } : []
 
       columns = model.column_names.reject { |c| SKIP_COLUMNS.include?(c) || blind.include?(c) || c == "custom_fields" }
                      .select { |c| policy.readable?(c) }
@@ -48,6 +49,8 @@ module Loam
 
       if model.respond_to?(:custom_field_definitions)
         model.custom_field_definitions.order(:name).each do |definition|
+          next unless policy.custom_field_readable?(definition.name)
+
           columns << { header: definition.name, name: definition.name, kind: :custom }
         end
       end
@@ -61,14 +64,11 @@ module Loam
               when :custom    then (record.custom_field(column[:name]) rescue nil)
               else record.public_send(column[:name])
               end
-      Loam::Csv.safe(value) # neutralize CSV formula injection (=, +, -, @, tab/CR)
+      OpenLoam::Csv.safe(value) # neutralize CSV formula injection (=, +, -, @, tab/CR)
     end
 
     def policy_for(model, actor)
-      klass = "#{model.name}Policy".safe_constantize
-      # A blank instance as the record: readable? keys off the role, but the
-      # policy's custom-field checks read record.class.
-      (klass || Loam::Policy).new(actor, model.new)
+      OpenLoam::Policy.for_model(model, actor)
     end
   end
 end

data/lib/{loam → open_loam}/features.rb

@@ -1,18 +1,18 @@
-module Loam
+module OpenLoam
   # Runtime feature toggles: is a capability turned ON for this tenant right now.
   #
-  #   Loam::Features.on?(:beta_dashboard)          # for the current tenant
-  #   Loam::Features.enable(:beta_dashboard)       # this tenant only
-  #   Loam::Features.enable(:beta_dashboard, scope: :global)  # everyone
-  #   Loam::Features.disable(:beta_dashboard)
-  #   Loam::Features.reset(:beta_dashboard)        # drop the override → default
+  #   OpenLoam::Features.on?(:beta_dashboard)          # for the current tenant
+  #   OpenLoam::Features.enable(:beta_dashboard)       # this tenant only
+  #   OpenLoam::Features.enable(:beta_dashboard, scope: :global)  # everyone
+  #   OpenLoam::Features.disable(:beta_dashboard)
+  #   OpenLoam::Features.reset(:beta_dashboard)        # drop the override → default
   #
   # A flag gates a CAPABILITY (is this feature live for the tenant), which is
   # orthogonal to a policy — that gates a PERSON (may this user act). The two
   # coexist: a manager may be allowed to approve reports AND the approvals
   # feature may be switched off for their tenant during a rollout.
   #
-  # This is deliberately a thin wrapper over Loam::Configs: a flag is a boolean
+  # This is deliberately a thin wrapper over OpenLoam::Configs: a flag is a boolean
   # setting with the same override → global → declared-default resolution, so it
   # reuses that store (no new table) and its per-request cache. Flags live under
   # the reserved `features.` key prefix and get their own admin screen, because
@@ -22,7 +22,7 @@ module Loam
 
     class << self
       def on?(name)
-        !!Loam::Configs.get(key_for(name), default: default_for(name))
+        !!OpenLoam::Configs.get(key_for(name), default: default_for(name))
       end
 
       def off?(name)
@@ -32,37 +32,37 @@ module Loam
       # Flip a flag on. scope: :tenant (default) overrides for the current tenant
       # and requires a tenant in context; scope: :global sets the app-wide state.
       def enable(name, scope: :tenant)
-        Loam::Configs.set(key_for(name), true, scope: scope)
+        OpenLoam::Configs.set(key_for(name), true, scope: scope)
       end
 
       def disable(name, scope: :tenant)
-        Loam::Configs.set(key_for(name), false, scope: scope)
+        OpenLoam::Configs.set(key_for(name), false, scope: scope)
       end
 
       # Drop the current tenant's override so the flag falls back to the global
       # state / declared default.
       def reset(name)
-        Loam::Configs.reset(key_for(name))
+        OpenLoam::Configs.reset(key_for(name))
       end
 
       def overridden?(name)
-        Loam::Configs.overridden?(key_for(name))
+        OpenLoam::Configs.overridden?(key_for(name))
       end
 
       # Every declared flag, sorted — the admin lists these whether or not a row
       # exists yet, so a flag is visible the moment it is declared.
       def declared
-        Loam.feature_defaults.keys.sort
+        OpenLoam.feature_defaults.keys.sort
       end
 
       def description(name)
-        Loam.feature_defaults.dig(name.to_s, :description)
+        OpenLoam.feature_defaults.dig(name.to_s, :description)
       end
 
       # The declared-default state of a flag (false for an unknown one), used as
       # the last resort when there is no override and no global row.
       def default_for(name)
-        !!Loam.feature_defaults.dig(name.to_s, :default)
+        !!OpenLoam.feature_defaults.dig(name.to_s, :default)
       end
 
       private

data/lib/{loam → open_loam}/generated_key.rb

@@ -1,4 +1,4 @@
-module Loam
+module OpenLoam
   # Primary-key generation for tables whose key is not an integer.
   #
   # Rails leaves key generation to the database, which works for integer keys
@@ -7,22 +7,22 @@ module Loam
   # has neither: the INSERT sends NULL and the row is rejected or lands with an
   # empty key.
   #
-  # Loam's tables follow the host app's key type (see
-  # Loam::Generators::PrimaryKeyOptions), so on a string-keyed app every Loam
+  # OpenLoam's tables follow the host app's key type (see
+  # OpenLoam::Generators::PrimaryKeyOptions), so on a string-keyed app every OpenLoam
   # model needs its key generated in Ruby. Before this, hosts patched it in
   # themselves with a global before_create on ActiveRecord::Base — a lot to ask
   # of an app whose only deviation was not using bigints, and a hook broad
-  # enough to reach models that had nothing to do with Loam.
+  # enough to reach models that had nothing to do with OpenLoam.
   #
   # Integer keys take the early return, so nothing changes for the default app.
   module GeneratedKey
     def self.included(base)
-      base.before_create :assign_loam_generated_key
+      base.before_create :assign_open_loam_generated_key
     end
 
     private
 
-    def assign_loam_generated_key
+    def assign_open_loam_generated_key
       key = self.class.primary_key
       return if key.nil?             # a join table declared with id: false
       return if self[key].present?   # the caller chose the key

data/lib/{loam → open_loam}/import.rb

@@ -1,14 +1,14 @@
 require "csv"
 require "set"
 
-module Loam
+module OpenLoam
   # CSV import mapping engine — reusable, tenant-scoped, policy-safe.
   #
-  #   Loam::Import.preview(csv)                       # headers + first rows for the mapping UI
-  #   Loam::Import.run(csv, model:, mapping:, actor:, # map CSV header => field
+  #   OpenLoam::Import.preview(csv)                       # headers + first rows for the mapping UI
+  #   OpenLoam::Import.run(csv, model:, mapping:, actor:, # map CSV header => field
   #                    match_key: "name",             # update-or-create by a key (nil = create-only)
   #                    dry_run: true,                 # validate + report, commit nothing
-  #                    progress: progress_job)        # advance a Loam::ProgressJob per row
+  #                    progress: progress_job)        # advance a OpenLoam::ProgressJob per row
   #
   # Safety: the mapping may only target fields the actor's role can WRITE (real
   # columns + declared custom fields); tenant_id, plumbing, and non-permitted
@@ -27,14 +27,14 @@ module Loam
 
     module_function
 
-    # Resolve an entity_type string to a model — ONLY a Loam::TenantRecord
+    # Resolve an entity_type string to a model — ONLY a OpenLoam::TenantRecord
     # subclass (never an arbitrary constant), so an import target can't be
     # smuggled to a global model like User (same guard as the business-rules
     # engine).
     def allowed_model(entity_type)
       klass = entity_type.to_s.safe_constantize
-      unless klass.is_a?(Class) && klass < Loam::TenantRecord
-        raise Loam::Error, "import target #{entity_type.inspect} is not a Loam entity"
+      unless klass.is_a?(Class) && klass < OpenLoam::TenantRecord
+        raise OpenLoam::Error, "import target #{entity_type.inspect} is not a OpenLoam entity"
       end
 
       klass
@@ -79,7 +79,7 @@ module Loam
           is_new ? (result.created += 1) : (result.updated += 1)
         rescue StandardError => error
           # Store ONLY the row number + message — NEVER the raw cell values. The
-          # result is persisted (Loam::ProgressJob.result); a failed row into an
+          # result is persisted (OpenLoam::ProgressJob.result); a failed row into an
           # encrypted field would otherwise write PLAINTEXT PII at rest.
           result.failed += 1
           result.errors << { "row" => line, "message" => error.message }
@@ -103,7 +103,7 @@ module Loam
         out << (Array(headers) + [ "_error" ])
         result.errors.each do |error|
           original = data_rows[error["row"] - 2] || [] # row is 1-based incl. the header
-          out << original.map { |cell| Loam::Csv.safe(cell) } + [ error["message"] ]
+          out << original.map { |cell| OpenLoam::Csv.safe(cell) } + [ error["message"] ]
         end
       end
     end
@@ -115,7 +115,7 @@ module Loam
         next if target.to_s.blank?
         next if allowed.include?(target.to_s)
 
-        raise Loam::Error, "import mapping refuses #{target.inspect} — not a writable column or custom field"
+        raise OpenLoam::Error, "import mapping refuses #{target.inspect} — not a writable column or custom field"
       end
     end
 
@@ -155,14 +155,11 @@ module Loam
     def safe_parse(csv_string)
       CSV.parse(csv_string.to_s)
     rescue CSV::MalformedCSVError => error
-      raise Loam::Error, "could not parse CSV: #{error.message}"
+      raise OpenLoam::Error, "could not parse CSV: #{error.message}"
     end
 
     def policy_for(model, actor)
-      klass = "#{model.name}Policy".safe_constantize
-      # A blank instance as the record: readable?/writable? key off the role, but
-      # custom_field_writable? reads record.class.custom_field_definitions.
-      (klass || Loam::Policy).new(actor, model.new)
+      OpenLoam::Policy.for_model(model, actor)
     end
   end
 end

data/lib/{loam → open_loam}/inbound_webhooks.rb

@@ -1,9 +1,9 @@
 require "openssl"
 require "digest"
 
-module Loam
+module OpenLoam
   # Receiving webhooks FROM external systems (the inbound sibling of
-  # Loam::Webhooks). One entry point — `ingest` — does the whole verified,
+  # OpenLoam::Webhooks). One entry point — `ingest` — does the whole verified,
   # replay-resistant pipeline and returns a Result the controller turns into an
   # HTTP status. Kept here (not in a controller) so it is testable without HTTP
   # and shared by the generated app and the demo.
@@ -19,9 +19,12 @@ module Loam
   # Every AUTH failure returns 401 with no distinguishing body, so a sender can't
   # probe which check failed; the specific reason is logged server-side only.
   #
-  # REPLAY: the real defense is the (source_id, external_id) dedupe. The timestamp
-  # window is defense-in-depth: unless the sender signs the timestamp too, a
-  # replayer can refresh an unsigned timestamp header. Don't over-trust it.
+  # REPLAY: the real defense is the (source_id, external_id) dedupe, and
+  # external_id is derived from the SIGNED body — never from a header. Anything
+  # an attacker can vary without invalidating the signature is a way to mint a
+  # fresh dedupe key and replay the delivery. The timestamp window is
+  # defense-in-depth only, for the same reason: unless the sender signs the
+  # timestamp, a replayer just refreshes it.
   module InboundWebhooks
     MAX_BYTES = 1_000_000
 
@@ -30,13 +33,13 @@ module Loam
     module_function
 
     def ingest(token:, raw_body:, headers:)
-      Loam::Telemetry.span("inbound_webhook") { run_ingest(token, raw_body.to_s, headers) }
+      OpenLoam::Telemetry.span("inbound_webhook") { run_ingest(token, raw_body.to_s, headers) }
     end
 
     def run_ingest(token, raw_body, headers)
       return Result.new(status: 413, reason: "body too large") if raw_body.bytesize > MAX_BYTES
 
-      source = Loam::InboundWebhookSource.resolve(token)
+      source = OpenLoam::InboundWebhookSource.resolve(token)
       return Result.new(status: 404, reason: "unknown or inactive source") if source.nil?
 
       signature = header(headers, source.signature_header_key)
@@ -51,8 +54,8 @@ module Loam
 
       begin
         delivery = nil
-        Loam::InboundWebhookDelivery.transaction do
-          delivery = Loam::InboundWebhookDelivery.create!(
+        OpenLoam::InboundWebhookDelivery.transaction do
+          delivery = OpenLoam::InboundWebhookDelivery.create!(
             source: source, external_id: external_id, event_name: source.event_name,
             status: "received", received_at: Time.current, payload: parse(raw_body)
           )
@@ -60,7 +63,7 @@ module Loam
           # lives on the delivery row, subscribers read it from there. Publishing
           # inside the txn ties capture to the row — a publish failure rolls the
           # row back so the sender's retry isn't deduped away.
-          Loam::Events.publish(source.event_name, { source_id: source.id, delivery_id: delivery.id })
+          OpenLoam::Events.publish(source.event_name, { source_id: source.id, delivery_id: delivery.id })
         end
         Result.new(status: 202, reason: "accepted", delivery: delivery)
       rescue ActiveRecord::RecordNotUnique
@@ -92,14 +95,12 @@ module Loam
       (Time.current.to_i - seconds).abs <= tolerance.to_i
     end
 
-    def delivery_id(source, headers, body)
-      if source.delivery_id_header.present?
-        value = header(headers, source.delivery_id_header)
-        return value if value.present?
-      end
-      # No delivery-id header configured (or absent): fall back to a body hash.
-      # Consequence: identical bodies dedupe. A sender with a real delivery id
-      # should configure delivery_id_header so distinct-but-identical bodies pass.
+    # The dedupe key must come from SIGNED material, which means the body: the
+    # HMAC covers the body alone, so a captured (body, signature) replayed with a
+    # fresh delivery-id header used to mint a new external_id every time and
+    # re-publish the event. Cost: a sender emitting distinct deliveries with
+    # identical bodies sees the second deduped — its nonce belongs in the body.
+    def delivery_id(_source, _headers, body)
       Digest::SHA256.hexdigest(body)
     end