open-loam 0.1.1 → 0.3.0

data/lib/generators/open_loam/install/templates/api_base_controller.rb

@@ -0,0 +1,127 @@
+module Api
+  # Base class for every JSON endpoint. Authentication is a bearer token:
+  #
+  #   curl -H "Authorization: Bearer <token>" http://localhost:3000/api/equipment
+  #
+  # A token identifies one user in one tenant, and `OpenLoam::ApiToken.authenticate`
+  # establishes both in OpenLoam::Current before any action runs. From that point
+  # on this is ordinary tenant-scoped OpenLoam code: every query is filtered, every
+  # write is audited, every policy applies — the API is not a side door.
+  #
+  # Finding a token is the one lookup that cannot start from a tenant (the
+  # token is what reveals the tenant), which is why it lives in the gem rather
+  # than here: host app code must never reach across tenants.
+  class BaseController < ActionController::API
+    before_action :authenticate_api_token!
+
+    # Same guard as the admin base controller: an endpoint that never authorized
+    # anything fails loudly rather than silently serving. Runs after the action,
+    # so it catches the omission in tests, not at runtime.
+    after_action :verify_authorized!
+
+    def self.skip_authorization!(reason, **options)
+      raise ArgumentError, "skip_authorization! needs a reason" if reason.to_s.strip.empty?
+
+      skip_after_action :verify_authorized!, **options
+    end
+
+    rescue_from OpenLoam::NotAuthorizedError do
+      render json: { error: "forbidden" }, status: :forbidden
+    end
+
+    rescue_from ActiveRecord::RecordNotFound do
+      render json: { error: "not_found" }, status: :not_found
+    end
+
+    rescue_from OpenLoam::UnknownCustomFieldError do |error|
+      render json: { error: error.message }, status: :unprocessable_entity
+    end
+
+    private
+
+    def authenticate_api_token!
+      @api_token = OpenLoam::ApiToken.authenticate(bearer_token)
+
+      render json: { error: "unauthorized" }, status: :unauthorized unless @api_token
+    end
+
+    def bearer_token
+      request.headers["Authorization"].to_s[/\ABearer (.+)\z/, 1]
+    end
+
+    def current_tenant = OpenLoam::Current.tenant
+    def current_actor = OpenLoam::Current.actor
+
+    def policy_for(record)
+      OpenLoam::Policy.for(record)
+    end
+
+    def authorize!(policy, action)
+      authorized!
+      raise OpenLoam::NotAuthorizedError unless policy.public_send(action)
+    end
+
+    # Marked whether the answer was yes or no — a refusal is still a check.
+    def authorized!
+      @open_loam_authorized = true
+    end
+
+    def verify_authorized!
+      return if @open_loam_authorized
+
+      raise OpenLoam::AuthorizationNotPerformedError,
+            "#{self.class.name}##{action_name} finished without authorizing. Call authorize!, or declare " \
+            "`skip_authorization! \"<why>\"` if it is authorized structurally."
+    end
+
+    # The JSON shape of an entity: the columns this actor's role may READ, plus
+    # the readable custom fields (which live in the `custom_fields` column that
+    # every generated entity carries).
+    #
+    # The read check is the same one the CSV export and the admin screens apply.
+    # Without it the API is a way around every `field readable:` rule in the app:
+    # the record is already loaded and `record.attributes` emits everything on it.
+    #
+    # Encrypted fields (OpenLoam::Encryptable) are returned DECRYPTED — the caller is
+    # authenticated, tenant-scoped and policy-gated, exactly like the admin show
+    # screen — and their blind-index `<field>_hash` column is dropped, so the
+    # equality-leaking hash never goes over the wire.
+    def entity_json(record, enrichments: nil)
+      policy = policy_for(record)
+      json = record.attributes.slice(*policy.readable_fields(record.attribute_names))
+
+      if record.class.respond_to?(:open_loam_encrypted_attributes)
+        record.class.open_loam_encrypted_attributes.each do |name|
+          json[name] = record.public_send(name) if json.key?(name)
+          json.delete("#{name}_hash")
+        end
+      end
+
+      # `custom_fields` is one JSON column, so it is all-or-nothing at the
+      # column level — filter its contents per definition instead.
+      if json.key?("custom_fields") && record.class.respond_to?(:custom_field_definitions)
+        readable = record.class.custom_field_definitions.map(&:name).select { |n| policy.custom_field_readable?(n) }
+        json["custom_fields"] = json["custom_fields"].to_h.slice(*readable)
+      end
+
+      # Computed cross-module blocks (OpenLoam::Enrichers), under a separate key so
+      # they're never confused with the record's own columns. An index passes the
+      # batched result (avoiding N+1); a single show computes it here.
+      enrichments = OpenLoam::Enrichers.enrich(record) if enrichments.nil?
+      json["enrichments"] = enrichments if enrichments.present?
+      json
+    end
+
+    # Same field-level enforcement as the admin screens: only a definition the
+    # actor's role may write is assigned. Custom fields ride at the top level
+    # of the request body, beside the entity key.
+    def assign_custom_fields!(record, params, policy)
+      submitted = params[:custom_fields]
+      return unless submitted
+
+      submitted.each do |name, value|
+        record.set_custom_field(name, value) if policy.custom_field_writable?(name)
+      end
+    end
+  end
+end

data/lib/generators/{loam → open_loam}/install/templates/guardrails_test.rb

@@ -1,21 +1,21 @@
 require "test_helper"
 
-# Structural guardrails. These are not feature tests — they enforce Loam's
+# Structural guardrails. These are not feature tests — they enforce OpenLoam's
 # invariants on the codebase itself. If one of these fails, an agent (or a
 # human) stepped outside the conventions.
-class LoamGuardrailsTest < ActiveSupport::TestCase
-  # Models that are legitimately not tenant-scoped. Loam::Config holds both
+class OpenLoamGuardrailsTest < ActiveSupport::TestCase
+  # Models that are legitimately not tenant-scoped. OpenLoam::Config holds both
   # global (tenant_id NULL) and per-tenant override rows, so tenancy is a
-  # nullable column and resolution lives in vetted gem code (Loam::Configs).
-  # Loam::MfaCredential belongs to the person, who spans tenants — MFA is
+  # nullable column and resolution lives in vetted gem code (OpenLoam::Configs).
+  # OpenLoam::MfaCredential belongs to the person, who spans tenants — MFA is
   # verified at login before any tenant is chosen.
-  TENANCY_ALLOWLIST = %w[ApplicationRecord User Loam::Tenant Loam::Config Loam::MfaCredential Loam::AuthAttempt].freeze
+  TENANCY_ALLOWLIST = %w[ApplicationRecord User OpenLoam::Tenant OpenLoam::Config OpenLoam::MfaCredential OpenLoam::AuthAttempt].freeze
 
   # Rails' own engine models (storage, rich text, jobs) are framework
   # plumbing, not business data — they are out of scope for tenant linting.
   FRAMEWORK_NAMESPACES = %w[ActiveStorage:: ActionText:: ActionMailbox:: SolidQueue:: SolidCache:: SolidCable::].freeze
 
-  test "every app model is tenant-scoped (inherits Loam::TenantRecord)" do
+  test "every app model is tenant-scoped (inherits OpenLoam::TenantRecord)" do
     Rails.application.eager_load!
 
     offenders = ActiveRecord::Base.descendants.reject do |model|
@@ -23,20 +23,20 @@ class LoamGuardrailsTest < ActiveSupport::TestCase
         model.name.nil? ||
         TENANCY_ALLOWLIST.include?(model.name) ||
         FRAMEWORK_NAMESPACES.any? { |ns| model.name.start_with?(ns) } ||
-        model <= Loam::TenantRecord
+        model <= OpenLoam::TenantRecord
     end
 
     assert_empty offenders,
       "These models are NOT tenant-scoped: #{offenders.map(&:name).join(', ')}. " \
-      "Business models must inherit Loam::TenantRecord (use `rails g loam:entity`). " \
+      "Business models must inherit OpenLoam::TenantRecord (use `rails g open_loam:entity`). " \
       "If a model is intentionally global, add it to TENANCY_ALLOWLIST here — in review, on purpose."
   end
 
   test "touching a tenant-scoped model with no tenant context raises" do
-    Loam::Current.reset
+    OpenLoam::Current.reset
 
-    assert_raises(Loam::MissingTenantError) { Loam::AuditRecord.count }
-    assert_raises(Loam::MissingTenantError) { Loam::Membership.first }
+    assert_raises(OpenLoam::MissingTenantError) { OpenLoam::AuditRecord.count }
+    assert_raises(OpenLoam::MissingTenantError) { OpenLoam::Membership.first }
   end
 
   test "nobody uses .unscoped outside vetted framework code" do
@@ -64,16 +64,16 @@ class LoamGuardrailsTest < ActiveSupport::TestCase
       "docs/ and link it, rather than raising the budget."
   end
 
-  test "every Loam::FieldDefinition entity_type resolves to a class that uses Loam::CustomFields" do
+  test "every OpenLoam::FieldDefinition entity_type resolves to a class that uses OpenLoam::CustomFields" do
     Rails.application.eager_load!
 
-    offenders = Loam::FieldDefinition.unscoped.distinct.pluck(:entity_type).reject do |entity_type|
+    offenders = OpenLoam::FieldDefinition.unscoped.distinct.pluck(:entity_type).reject do |entity_type|
       klass = entity_type.safe_constantize
-      klass && klass.include?(Loam::CustomFields)
+      klass && klass.include?(OpenLoam::CustomFields)
     end
 
     assert_empty offenders,
-      "These Loam::FieldDefinition entity_type values don't resolve to a class that " \
-      "`include Loam::CustomFields`: #{offenders.join(', ')}. Likely a typo when the field was created."
+      "These OpenLoam::FieldDefinition entity_type values don't resolve to a class that " \
+      "`include OpenLoam::CustomFields`: #{offenders.join(', ')}. Likely a typo when the field was created."
   end
 end

data/lib/generators/open_loam/install/templates/import_job.rb

@@ -0,0 +1,38 @@
+# Runs a CSV import in the background, advancing a OpenLoam::ProgressJob so the admin
+# watches it live (L-915). Carries tenant + actor explicitly, like every OpenLoam job.
+# The per-row summary (created/updated/failed + error rows) is stored on the
+# ProgressJob's `result` for the summary screen.
+#
+# The file arrives as a blob id, never as a job argument. ActiveJob arguments are
+# serialized into the queue backend and echoed in the job log, so passing the CSV
+# itself would persist every row — including columns bound for encrypted fields —
+# in the clear, outside the encryption the destination columns exist to provide.
+class ImportJob < ApplicationJob
+  queue_as :default
+
+  def perform(entity_type:, blob_id:, mapping:, match_key:, tenant_id:, actor_id:)
+    tenant = OpenLoam::Tenant.find(tenant_id)
+    actor = User.find_by(id: actor_id)
+    model = OpenLoam::Import.allowed_model(entity_type)
+    blob = ActiveStorage::Blob.find_by(id: blob_id)
+    return if blob.nil? # already purged: nothing to import, not an error
+
+    csv = blob.download.force_encoding("UTF-8")
+
+    OpenLoam.as_tenant(tenant, actor: actor) do
+      total = [ CSV.parse(csv).size - 1, 0 ].max
+      progress = OpenLoam::Progress.start(name: "Import #{entity_type}", total: total)
+      begin
+        result = OpenLoam::Import.run(csv, model: model, mapping: mapping, actor: actor, match_key: match_key, progress: progress)
+        progress.update_columns(result: result.to_h)
+        progress.complete!
+      rescue StandardError => error
+        progress.fail!(error.message)
+      end
+    end
+  ensure
+    # The upload has done its job; leaving it behind is a second copy of the
+    # same data with none of the destination's protections.
+    blob&.purge_later
+  end
+end

data/lib/generators/{loam → open_loam}/install/templates/inbound_webhooks_controller.rb

@@ -1,17 +1,17 @@
 # Public endpoint that receives webhooks FROM external systems at
 # /webhooks/:token. No session, no bearer token: the HMAC signature is the auth
 # (ActionController::API, so there is no CSRF to skip). All the verified,
-# replay-resistant work lives in Loam::InboundWebhooks.ingest; this controller
+# replay-resistant work lives in OpenLoam::InboundWebhooks.ingest; this controller
 # only maps its Result to an HTTP status and never leaks tenant context to the
 # next request on this thread.
 class InboundWebhooksController < ActionController::API
   def receive
-    result = Loam::InboundWebhooks.ingest(
+    result = OpenLoam::InboundWebhooks.ingest(
       token: params[:token], raw_body: request.raw_post, headers: request.headers
     )
-    Rails.logger.info("[loam inbound] #{result.status} #{result.reason}") if result.status >= 400
+    Rails.logger.info("[open_loam inbound] #{result.status} #{result.reason}") if result.status >= 400
     head result.status
   ensure
-    Loam::Current.reset
+    OpenLoam::Current.reset
   end
 end

data/lib/generators/{loam → open_loam}/install/templates/initializer.rb

@@ -1,214 +1,226 @@
-# Loam configuration, tenant lifecycle hooks, and domain event subscriptions.
+# OpenLoam configuration, tenant lifecycle hooks, and domain event subscriptions.
 
-# Master key for field encryption at rest (Loam::Encryptable). Per-tenant keys
+# Master key for field encryption at rest (OpenLoam::Encryptable). Per-tenant keys
 # are derived from it via HKDF, so it must be STABLE and SECRET — never commit it.
-# Set LOAM_MASTER_KEY in the environment (or wire Rails.application.credentials)
+# Set OPEN_LOAM_MASTER_KEY in the environment (or wire Rails.application.credentials)
 # to a high-entropy value, e.g. `SecureRandom.hex(32)`. Only apps that actually
 # `encrypts` a field need it; encryption raises a clear error if it is missing.
 #
-#   Loam::Encryption.master_key = ENV.fetch("LOAM_MASTER_KEY")
+#   OpenLoam::Encryption.master_key = ENV.fetch("OPEN_LOAM_MASTER_KEY")
 #
-# Rotating the key without re-encrypting orphans existing ciphertext — see
-# `bin/rails loam:encryption:rotate[Model,tenant_id]`.
+# To ROTATE: keep the outgoing key in OPEN_LOAM_PREVIOUS_MASTER_KEY while the new
+# one is in OPEN_LOAM_MASTER_KEY. Reads fall back to the old key, writes always use
+# the new one, so `bin/rails open_loam:encryption:rotate[Model,tenant_id]` can walk
+# each tenant's rows. Drop the previous key once every model has been rotated —
+# until then, both keys are live and the old one is still worth protecting.
 
 # Roles every tenant of this app is expected to have. A registry read by your
-# own seeding/admin code — Loam does not create memberships for you, because
+# own seeding/admin code — OpenLoam does not create memberships for you, because
 # who gets which role is business logic.
-Loam.default_roles = %w[manager employee]
+OpenLoam.default_roles = %w[manager employee]
 
-# Locales that CONTENT translations (Loam::Translatable) may be authored in — the
+# Locales that CONTENT translations (OpenLoam::Translatable) may be authored in — the
 # admin's language switcher and the per-record Translations screen offer these.
 # The first is the base/default; the rest overlay onto it. This is for user data
-# (a product name), NOT developer UI strings — those stay Rails i18n. Loam ships
-# a `loam.*` base locale (English) for its own chrome; the admin switcher sets
-# I18n.locale too, so add `config/locales/loam.pl.yml` (etc.) to translate the UI
+# (a product name), NOT developer UI strings — those stay Rails i18n. OpenLoam ships
+# a `open_loam.*` base locale (English) for its own chrome; the admin switcher sets
+# I18n.locale too, so add `config/locales/open_loam.pl.yml` (etc.) to translate the UI
 # for each locale you list here.
-Loam.locales = %w[en]
+OpenLoam.locales = %w[en]
 
-# Observability (Loam::Telemetry). By default Loam wraps its async hot paths
+# Observability (OpenLoam::Telemetry). By default OpenLoam wraps its async hot paths
 # (scheduler tick, durable event delivery, inbound webhook ingest) in spans that
-# emit ActiveSupport::Notifications events ("loam.span.*") — subscribe to those,
+# emit ActiveSupport::Notifications events ("open_loam.span.*") — subscribe to those,
 # or plug a real tracer in here:
 #
-#   Loam::Telemetry.backend = ->(name, attributes, work) do
-#     OpenTelemetry.tracer_provider.tracer("loam").in_span(name, attributes: attributes.transform_keys(&:to_s)) { work.call }
+#   OpenLoam::Telemetry.backend = ->(name, attributes, work) do
+#     OpenTelemetry.tracer_provider.tracer("open_loam").in_span(name, attributes: attributes.transform_keys(&:to_s)) { work.call }
 #   end
 
-# Feature-string permissions (Loam::Permissions) — a finer capability layer under
+# Feature-string permissions (OpenLoam::Permissions) — a finer capability layer under
 # the coarse role. Deny-by-default; `*` grants everything, a trailing `.*` is a
-# prefix ("equipment.*"). Check with `Loam.can?("equipment.edit")`,
+# prefix ("equipment.*"). Check with `OpenLoam.can?("equipment.edit")`,
 # `require_permission!("...")` in a controller, or the `can?` view helper.
-# Orthogonal to roles (Loam::Membership) and field-level policies (Loam::Policy).
+# Orthogonal to roles (OpenLoam::Membership) and field-level policies (OpenLoam::Policy).
 #
-#   Loam::Permissions.configure do
+#   OpenLoam::Permissions.configure do
 #     role :admin,   allow: "*"
 #     role :manager, allow: %w[equipment.* billing.read]
 #     role :clerk,   allow: %w[equipment.read]
 #   end
 
-# Customization WITHOUT forking (Loam::Overrides): disable or replace an entry in
-# one of Loam's keyed registries (:widgets, :broadcast_events). A stale override
+# Customization WITHOUT forking (OpenLoam::Overrides): disable or replace an entry in
+# one of OpenLoam's keyed registries (:widgets, :broadcast_events). A stale override
 # (a key that no longer exists) is warned about at boot by `check!`, so a
 # typo'd override is visible instead of silently doing nothing.
 #
-#   Loam::Overrides.disable(:widgets, "open_progress")   # drop a built-in widget
-#   Loam::Overrides.replace(:widgets, "audit_recent") { |actor| { kind: "count", value: 0 } }
-#   Loam::Overrides.disable(:broadcast_events, "loam.progress.")  # stop pushing it over SSE
+#   OpenLoam::Overrides.disable(:widgets, "open_progress")   # drop a built-in widget
+#   OpenLoam::Overrides.replace(:widgets, "audit_recent") { |actor| { kind: "count", value: 0 } }
+#   OpenLoam::Overrides.disable(:broadcast_events, "open_loam.progress.")  # stop pushing it over SSE
 #
-# BOUNDARY: this is only for Loam's in-gem registries. Override a VIEW, CONTROLLER,
+# BOUNDARY: this is only for OpenLoam's in-gem registries. Override a VIEW, CONTROLLER,
 # or ROUTE the standard Rails way (create a file at the same path to shadow the
 # engine's, or `prepend` a module) — not here.
 
-# Events pushed live to the browser over SSE (Loam::EventStream). Default off; the
+# Events pushed live to the browser over SSE (OpenLoam::EventStream). Default off; the
 # notification pattern is enabled here so the admin bell increments without a
 # reload. Add patterns (e.g. "billing.") to stream domain events to live widgets —
 # nothing reaches the browser unless it matches a pattern here (security posture).
-Loam.broadcast_events = [ "loam.notification.", "loam.progress." ]
+OpenLoam.broadcast_events = [ "open_loam.notification.", "open_loam.progress." ]
 
-# Response enrichers (Loam::Enrichers): attach a computed block onto ANOTHER
+# Events EXCLUDED from the event log (OpenLoam::EventLog), which otherwise
+# captures everything. Progress ticks are excluded because a bulk import fires
+# one per row — volume without history worth keeping.
+OpenLoam.uncaptured_events = [ "open_loam.progress." ]
+
+# How long captured events are kept before the daily per-tenant prune. nil keeps
+# everything, which means an unbounded table.
+OpenLoam.event_log_retention = 90.days
+
+# Response enrichers (OpenLoam::Enrichers): attach a computed block onto ANOTHER
 # module's entity in admin/API responses, with no foreign-key coupling — billing
 # can annotate an Equipment without Equipment knowing billing exists. Pass a
 # `batch:` resolver (array -> { id => value }) so an index stays one query, not N.
 #
-#   Loam::Enrichers.register("Equipment", key: "outstanding_balance", batch: ->(equipments) do
+#   OpenLoam::Enrichers.register("Equipment", key: "outstanding_balance", batch: ->(equipments) do
 #     totals = Invoice.where(equipment_id: equipments.map(&:id)).group(:equipment_id).sum(:balance)
 #     equipments.map(&:id).index_with { |id| totals.fetch(id, 0) }
 #   end)
 
-# Search backend (Loam::Search). The default is a substring LIKE — portable and
+# Search backend (OpenLoam::Search). The default is a substring LIKE — portable and
 # zero-setup. Opt into the word-level TokenDriver (also portable, no external
-# service: it keeps a normalized-token index in loam_search_tokens) for
+# service: it keeps a normalized-token index in open_loam_search_tokens) for
 # order-independent, whole-word matching. `searchable_by` and every
 # `Model.search(q)` call site are UNCHANGED — only this line differs; an external
 # engine (Meilisearch/Elasticsearch) is a third driver behind the same seam.
-# After switching, backfill existing rows once with `bin/rails loam:search:reindex`
+# After switching, backfill existing rows once with `bin/rails open_loam:search:reindex`
 # (new and updated records index themselves on save).
 #
-#   Loam::Search.driver = Loam::Search::TokenDriver
+#   OpenLoam::Search.driver = OpenLoam::Search::TokenDriver
 
-# Custom-field read-model index (Loam::CustomFieldIndex). Filtering/sorting on a
-# custom field is index-backed (a typed projection in loam_custom_field_values)
+# Custom-field read-model index (OpenLoam::CustomFieldIndex). Filtering/sorting on a
+# custom field is index-backed (a typed projection in open_loam_custom_field_values)
 # instead of a per-row JSON scan. Records project themselves on save; backfill
-# existing data once with `bin/rails loam:index:reindex` (or
-# `Loam::CustomFieldIndex.reindex(Model)`). Query with
-# `Loam::CustomFieldIndex.filter(Model, field_key, op, value)` — the generated
+# existing data once with `bin/rails open_loam:index:reindex` (or
+# `OpenLoam::CustomFieldIndex.reindex(Model)`). Query with
+# `OpenLoam::CustomFieldIndex.filter(Model, field_key, op, value)` — the generated
 # entity index routes a `cf_field`/`cf_op`/`cf_value` filter through it.
 
-# Single sign-on (Loam::Sso). OIDC is shipped end-to-end: configure a per-tenant
+# Single sign-on (OpenLoam::Sso). OIDC is shipped end-to-end: configure a per-tenant
 # provider under /admin/sso_providers (issuer, client_id, client_secret, email
 # domain, default JIT role). Home-realm discovery routes a user to their tenant's
 # IdP by email domain; a verified identity is JIT-provisioned or linked to an
-# existing User. The client_secret is encrypted at rest, so LOAM_MASTER_KEY must
-# be set (same key as the rest of Loam::Encryptable). SAML and SCIM are documented
+# existing User. The client_secret is encrypted at rest, so OPEN_LOAM_MASTER_KEY must
+# be set (same key as the rest of OpenLoam::Encryptable). SAML and SCIM are documented
 # seams (see docs/_foundation/overview.md). Nothing to register here for real OIDC.
 #
 # In tests, inject the offline fake so the flow never hits the network:
 #
-#   Loam::Sso.builder = ->(record, redirect_uri) { Loam::Sso::FakeProvider.new(record, redirect_uri: redirect_uri) }
+#   OpenLoam::Sso.builder = ->(record, redirect_uri) { OpenLoam::Sso::FakeProvider.new(record, redirect_uri: redirect_uri) }
 
-# Roles that MUST use two-factor auth (Loam::MfaCredential). At login, a user
+# Roles that MUST use two-factor auth (OpenLoam::MfaCredential). At login, a user
 # whose role in the chosen tenant is on this list and who has not enrolled is
-# sent to set MFA up before they can work. Resolved via Loam::Configs, so it can
+# sent to set MFA up before they can work. Resolved via OpenLoam::Configs, so it can
 # be a global default or a per-tenant override; empty means MFA is optional.
 #
-#   Loam::Configs.set("security.mfa_required_roles", ["manager"], scope: :global)
+#   OpenLoam::Configs.set("security.mfa_required_roles", ["manager"], scope: :global)
 #
-# Auth rate-limiting / lockout (Loam::AuthThrottle) guards failed password/TOTP/
+# Auth rate-limiting / lockout (OpenLoam::AuthThrottle) guards failed password/TOTP/
 # sudo attempts. Defaults: lock after 10 failures within a 15-minute window.
-# Tune via Loam::Configs (global or per-tenant):
+# Tune via OpenLoam::Configs (global or per-tenant):
 #
-#   Loam::Configs.set("security.max_auth_attempts",   5,  scope: :global)
-#   Loam::Configs.set("security.auth_window_minutes", 10, scope: :global)
+#   OpenLoam::Configs.set("security.max_auth_attempts",   5,  scope: :global)
+#   OpenLoam::Configs.set("security.auth_window_minutes", 10, scope: :global)
 #
 # Rack::Attack (with a cache store) is the production-scale path across multiple
 # processes; the built-in DB counter is the portable single-process default.
 
-# App-wide setting defaults (Loam::Configs). A key resolves override → global
+# App-wide setting defaults (OpenLoam::Configs). A key resolves override → global
 # row → this declared default, so declaring one here needs no migration and no
 # row — a tenant reads the default until someone overrides it in the admin
 # Settings screen (/admin/configs). Values keep their type (bool/number/string/
 # hash), and a per-tenant override never leaks to another tenant.
 #
-#   Loam.config_defaults = { "billing.currency" => "USD", "billing.net_terms" => 30 }
+#   OpenLoam.config_defaults = { "billing.currency" => "USD", "billing.net_terms" => 30 }
 #
 # To change the company-wide baseline at runtime (not per tenant), write a
-# global row: `Loam::Configs.set("billing.currency", "EUR", scope: :global)`.
+# global row: `OpenLoam::Configs.set("billing.currency", "EUR", scope: :global)`.
 
-# Feature flags (Loam::Features). Declare known capabilities and their default
+# Feature flags (OpenLoam::Features). Declare known capabilities and their default
 # state; a flag with no row resolves to its declared default, and managers flip
 # a tenant's override at /admin/features. A flag gates a CAPABILITY (is this on
 # for the tenant), orthogonal to roles/policies, which gate a PERSON.
 #
-#   Loam.feature_defaults = {
+#   OpenLoam.feature_defaults = {
 #     "beta_dashboard" => { default: false, description: "New dashboard, rolled out per tenant." }
 #   }
 #
 # In a controller: `require_feature!(:beta_dashboard)` (404s when off); in a
 # view: `<%% if feature_on?(:beta_dashboard) %>`. Flip app-wide with
-# `Loam::Features.enable(:beta_dashboard, scope: :global)`.
+# `OpenLoam::Features.enable(:beta_dashboard, scope: :global)`.
 
 # What a brand-new tenant gets for free. Registered at file scope on purpose:
 # inside `to_prepare` this would re-register on every code reload.
-Loam.on_tenant_created do |tenant|
+OpenLoam.on_tenant_created do |tenant|
   # Seed roles/defaults for a new tenant here. MUST be idempotent —
-  # `bin/rails loam:sync` re-runs these for every existing tenant, which is how
+  # `bin/rails open_loam:sync` re-runs these for every existing tenant, which is how
   # a default added in a later release reaches tenants that already exist.
   # Use find_or_create_by!, never create!. The block runs inside
-  # Loam.as_tenant(tenant), so tenant-scoped writes need no extra ceremony.
+  # OpenLoam.as_tenant(tenant), so tenant-scoped writes need no extra ceremony.
   #
-  # Baseline managed lookup lists (Loam::Dictionary) — a FieldDefinition of type
+  # Baseline managed lookup lists (OpenLoam::Dictionary) — a FieldDefinition of type
   # "dictionary" can then point a custom field at the key, rendering a select:
   #
-  #   severity = Loam::Dictionary.find_or_create_by!(key: "damage_severity") { |d| d.name = "Damage severity" }
+  #   severity = OpenLoam::Dictionary.find_or_create_by!(key: "damage_severity") { |d| d.name = "Damage severity" }
   #   [%w[minor Minor], %w[major Major], %w[critical Critical]].each_with_index do |(value, label), i|
   #     severity.entries.find_or_create_by!(value: value) { |e| e.label = label; e.position = i }
   #   end
 
-  # Materialize the registered tenant-scope schedules (see Loam::Scheduler.register
+  # Materialize the registered tenant-scope schedules (see OpenLoam::Scheduler.register
   # below) as rows for this tenant. A no-op until you register one.
-  Loam::Scheduler.sync_tenant(tenant)
+  OpenLoam::Scheduler.sync_tenant(tenant)
 end
 
-# Recurring jobs (Loam::Scheduler). Register default schedules here at file scope;
+# Recurring jobs (OpenLoam::Scheduler). Register default schedules here at file scope;
 # on_tenant_created materializes the tenant-scope ones per tenant. A "tenant" job
-# is enqueued with `tenant_id:` (establish it with Loam.as_tenant); a "system" job
+# is enqueued with `tenant_id:` (establish it with OpenLoam.as_tenant); a "system" job
 # runs once with no tenant. job_class MUST be a real ActiveJob (validated — never
 # arbitrary code). Wire the runner to system cron, every minute:
 #
-#   * * * * * cd /path/to/app && bin/rails loam:scheduler:tick
+#   * * * * * cd /path/to/app && bin/rails open_loam:scheduler:tick
 #
 # The claim is atomic, so running it from several hosts never double-fires a job.
 #
-#   Loam::Scheduler.register(key: "nightly_digest", name: "Nightly digest",
+#   OpenLoam::Scheduler.register(key: "nightly_digest", name: "Nightly digest",
 #                            job_class: "DigestJob", schedule: "0 7 * * *", scope: "tenant")
 #
 # Only ALLOWLISTED job classes are schedulable (a registered one, or one listed
 # here) — so a tenant admin can't schedule ActiveStorage::PurgeJob or a mailer:
 #
-#   Loam.schedulable_jobs = %w[DigestJob ReindexJob]
+#   OpenLoam.schedulable_jobs = %w[DigestJob ReindexJob]
 
 # Domain event subscriptions. Subscribe to a single event or a whole domain
 # (trailing dot = prefix). Register them here at file scope, not inside
 # `to_prepare`: subscriptions are global, so a reload would add a second copy
 # of each one and every event would be handled twice.
 #
-#   Loam::Events.subscribe("billing.subscription.renewed") do |name, payload|
+#   OpenLoam::Events.subscribe("billing.subscription.renewed") do |name, payload|
 #     BillingMailer.renewal_receipt(payload[:id]).deliver_later
 #   end
 #
-#   Loam::Events.subscribe("rental.") do |name, payload|
-#     Rails.logger.info("[loam event] #{name} #{payload.inspect}")
+#   OpenLoam::Events.subscribe("rental.") do |name, payload|
+#     Rails.logger.info("[open_loam event] #{name} #{payload.inspect}")
 #   end
 #
 # Event -> in-app notification is the intended pattern for telling someone
 # something. The subscriber runs in the publisher's tenant context, so the
 # notification lands in the right tenant with no extra ceremony:
 #
-#   Loam::Events.subscribe("rental.damage_report.approve") do |_name, payload|
-#     Loam::Notifications.notify_role(:manager, title: "Damage report approved")
+#   OpenLoam::Events.subscribe("rental.damage_report.approve") do |_name, payload|
+#     OpenLoam::Notifications.notify_role(:manager, title: "Damage report approved")
 #   end
 
-# Business rules (Loam::BusinessRule) are the admin-editable cousin of the
+# Business rules (OpenLoam::BusinessRule) are the admin-editable cousin of the
 # subscriptions above: a manager declares, per tenant, WHEN a condition holds on
 # a triggering record THEN run a fixed vocabulary of safe actions (notify,
 # emit_event, set_field, block_transition). The condition is DATA — a

data/lib/generators/open_loam/install/templates/migrations/create_open_loam_api_tokens.rb

@@ -0,0 +1,15 @@
+class CreateOpenLoamApiTokens < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :open_loam_api_tokens<%= open_loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :open_loam_tenants }<%= open_loam_type_option %>
+      t.references :user, null: false, foreign_key: true<%= open_loam_type_option %>
+      t.string :token_digest, null: false   # SHA-256; the plaintext is never stored
+      t.string :label
+      t.datetime :last_used_at
+      t.timestamps
+    end
+    # Tokens are looked up before a tenant is known, so the uniqueness that
+    # matters is global.
+    add_index :open_loam_api_tokens, :token_digest, unique: true
+  end
+end

data/lib/generators/open_loam/install/templates/migrations/create_open_loam_audit_records.rb

@@ -0,0 +1,14 @@
+class CreateOpenLoamAuditRecords < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+  def change
+    create_table :open_loam_audit_records<%= open_loam_id_option %> do |t|
+      t.references :tenant, null: false, foreign_key: { to_table: :open_loam_tenants }<%= open_loam_type_option %>
+      t.string :auditable_type, null: false
+      t.<%= open_loam_key_column_type %> :auditable_id<%= open_loam_key_limit_option %>, null: false
+      t.string :action, null: false
+      t.<%= open_loam_key_column_type %> :actor_id<%= open_loam_key_limit_option %>
+      t.text :changeset
+      t.timestamps
+    end
+    add_index :open_loam_audit_records, %i[tenant_id auditable_type auditable_id]
+  end
+end

data/lib/generators/{loam/install/templates/migrations/create_loam_auth_attempts.rb → open_loam/install/templates/migrations/create_open_loam_auth_attempts.rb}

@@ -1,11 +1,11 @@
-class CreateLoamAuthAttempts < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
+class CreateOpenLoamAuthAttempts < ActiveRecord::Migration[<%= ActiveRecord::VERSION::STRING.to_f %>]
   def change
-    create_table :loam_auth_attempts<%= loam_id_option %> do |t|
+    create_table :open_loam_auth_attempts<%= open_loam_id_option %> do |t|
       t.string :identifier, null: false   # the submitted login (normalized), NOT tenant-scoped
       t.string :kind, null: false         # password / totp / recovery / sudo
       t.string :ip                        # nullable; for an optional per-ip throttle
       t.timestamps
     end
-    add_index :loam_auth_attempts, %i[identifier created_at]
+    add_index :open_loam_auth_attempts, %i[identifier created_at]
   end
 end