clickwrap 0.0.0 → 0.1.1

data/lib/clickwrap/engine.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+
+module Clickwrap
+  # The mountable engine: wires autoloading, migrations, locales, the
+  # ActiveRecord macro, the form-builder extension, the controller helpers, and
+  # boot-time policy loading into the host app.
+  class Engine < ::Rails::Engine
+    isolate_namespace Clickwrap
+
+    # -------------------------------------------------------------------------
+    # Zeitwerk: the gem keeps its ActiveRecord models under lib/clickwrap/models
+    # (same layout as the moderate and chats gems) so the whole domain ships in
+    # lib/ and the engine's app/ tree only holds the web layer. For that to
+    # autoload correctly we manage the loader by hand:
+    #
+    #   - `push_dir(lib/clickwrap, namespace: Clickwrap)` makes
+    #     lib/clickwrap/models/... autoloadable *under the Clickwrap namespace*.
+    #   - `collapse(models)` + `collapse(models/concerns)` mean the files in
+    #     those folders define Clickwrap::Event / Clickwrap::HasClickwraps —
+    #     not Clickwrap::Models::Event.
+    #   - The SPINE files are required explicitly by lib/clickwrap.rb at boot,
+    #     so they must be *ignored* by the loader or Zeitwerk would complain
+    #     about double definitions.
+    # -------------------------------------------------------------------------
+    LIB_ROOT = File.expand_path("..", __dir__)
+    CLICKWRAP_LIB = File.expand_path("clickwrap", LIB_ROOT)
+
+    ZEITWERK_IGNORED = %w[
+      version.rb
+      errors.rb
+      vocabulary.rb
+      canonical_json.rb
+      digest.rb
+      identifier.rb
+      ip_geolocation.rb
+      ip_geolocation/location.rb
+      ip_geolocation/resolver.rb
+      ip_geolocation/null_resolver.rb
+      ip_geolocation/static_resolver.rb
+      ip_geolocation/trackdown_resolver.rb
+      configuration.rb
+      engine.rb
+      macros.rb
+      authority.rb
+      registry.rb
+      localized_text.rb
+      document_definition.rb
+      statement.rb
+      request_evidence_policy.rb
+      policy.rb
+      retention_class.rb
+      dsl/policy_builder.rb
+      dsl/retention_builder.rb
+      document_renderers/markdown.rb
+      form_builder_extensions.rb
+      view_helpers.rb
+      controller_helpers.rb
+      registration.rb
+    ].freeze
+
+    initializer "clickwrap.autoload", before: :set_autoload_paths do
+      loader = Rails.autoloaders.main
+
+      ZEITWERK_IGNORED.each do |file|
+        path = File.join(CLICKWRAP_LIB, file)
+        loader.ignore(path) if File.exist?(path)
+      end
+
+      %w[models models/concerns].each do |dir|
+        path = File.join(CLICKWRAP_LIB, dir)
+        loader.collapse(path) if File.directory?(path)
+      end
+
+      loader.push_dir(CLICKWRAP_LIB, namespace: Clickwrap)
+    end
+
+    config.eager_load_paths << CLICKWRAP_LIB
+
+    # Make the gem's migrations runnable from the host without copying
+    # (`rails db:migrate` picks them up). The install generator still copies a
+    # host-owned migration, which is the recommended path: a released migration
+    # is never edited underneath an installed application, so the host owns the
+    # file that describes its own schema.
+    initializer "clickwrap.migrations" do |app|
+      unless app.root.to_s == root.to_s
+        config.paths["db/migrate"].expanded.each do |path|
+          app.config.paths["db/migrate"] << path
+        end
+      end
+    end
+
+    # Expose `has_clickwraps` on every AR model.
+    initializer "clickwrap.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        extend Clickwrap::Macros
+      end
+    end
+
+    # Expose `form.clickwrap` and `form.clickwrap_fields` on the standard form
+    # builder, so the one-line happy path works in an ordinary `form_with`.
+    initializer "clickwrap.form_builder" do
+      ActiveSupport.on_load(:action_view) do
+        ActionView::Helpers::FormBuilder.prepend(Clickwrap::FormBuilderExtensions) unless
+          ActionView::Helpers::FormBuilder < Clickwrap::FormBuilderExtensions
+        # The custom-surface helpers (token field, statement controls, the
+        # manifest-worded submit) — available in every view, like the form
+        # builder methods above.
+        include Clickwrap::ViewHelpers
+      end
+    end
+
+    # Give host controllers `clickwrap_submission`, `capture_clickwrap_and!`,
+    # and the `requires_clickwrap` gate.
+    initializer "clickwrap.action_controller" do
+      ActiveSupport.on_load(:action_controller) do
+        include Clickwrap::ControllerHelpers
+
+        # `clickwraps_registration_with :signup` for Devise controllers. The
+        # macro is available everywhere; nothing happens unless a controller
+        # actually calls it, and Devise is never required.
+        include Clickwrap::Registration
+      end
+    end
+
+    # The gem's locale files ship through Rails::Engine's own :add_locales
+    # (every engine's `config/locales` is picked up automatically) — and NOT
+    # through a manual `app.config.i18n.load_path +=` on top of it. The manual
+    # append is not merely redundant: railties paths are UNSHIFTED before
+    # everything in `load_path`, so an appended copy of these files lands
+    # AFTER the host's own locales and quietly overrides them. Load order is
+    # the whole contract here — gem first, host last — because a host rewords
+    # a statement by shipping the same key in its own locale file, and the
+    # host's counsel must always get the last word.
+
+    initializer "clickwrap.assets" do |app|
+      app.config.assets.paths << root.join("app/assets/stylesheets") if app.config.respond_to?(:assets)
+    end
+
+    # Load the host's document, policy, and retention declarations. They live in
+    # ordinary Ruby files so they are reviewable in a diff and deployable like
+    # code; `to_prepare` re-reads them on every boot and every development
+    # reload, and compilation raises on a mistake rather than deferring it to
+    # the first person who tries to sign up.
+    # Every `requires_clickwrap` gate, checked once the host's routes exist.
+    #
+    # `after_routes_loaded` rather than `after_initialize`, and the difference
+    # matters: `after_initialize` runs while the application is still
+    # initializing, which is precisely when the routes reloader declines to
+    # load. Checking there would report "the engine is not mounted" to
+    # applications that mount it perfectly well, which is worse than not
+    # checking at all. This hook fires at the one moment the answer is knowable.
+    #
+    # A dead-end gate is still better found at boot than by the first person it
+    # stops, so the request path keeps its own backstop for controllers that are
+    # autoloaded later in development.
+    if config.respond_to?(:after_routes_loaded)
+      config.after_routes_loaded do
+        Clickwrap::ControllerHelpers.verify_registered_gates!
+        Clickwrap::Services::ValidatePolicyReferences.validate_remediation_paths!
+      end
+    end
+
+    config.to_prepare do
+      Clickwrap::Services::LoadPolicies.new.call
+
+      # Whether the raw request-evidence values are encrypted is a host decision
+      # read from the initializer, so it can only be applied once that has been
+      # read — and it has to be re-applied on every development reload, because
+      # the model class is a fresh object each time.
+      Clickwrap::RequestEvidence.apply_configured_encryption!
+
+      # `clickwrap:install` emits only the tables a default installation can
+      # actually put a row in; the rest come with their own flag. The one
+      # failure mode that creates is turning a capability on and forgetting its
+      # migration, and that must not be discovered by a capture failing in
+      # production. It is discovered here, with the exact command that fixes
+      # it. Answering needs a database, and "there is no database yet"
+      # (db:create, an asset build) is not a misconfiguration — the check
+      # simply does not fire.
+      Clickwrap::SchemaRequirements.reset!
+      missing = Clickwrap::SchemaRequirements.missing_for_configuration
+      raise Clickwrap::ConfigurationError, missing.map(&:explanation).join("\n\n") if missing.any?
+    end
+  end
+end

data/lib/clickwrap/errors.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Clickwrap
+  # Base class for every error Clickwrap raises. Hosts can rescue this one
+  # class and still distinguish causes through the subclasses below.
+  class Error < StandardError; end
+
+  # --- Configuration and boot -------------------------------------------------
+
+  # Raised when the initializer contains a value Clickwrap cannot safely use.
+  class ConfigurationError < Error; end
+
+  # Raised while compiling a policy, document, or retention class definition.
+  class DefinitionError < Error; end
+
+  # Raised when a policy, document, statement, or retention class is referenced
+  # but was never defined.
+  class NotDefinedError < Error; end
+
+  class UnknownPolicyError < NotDefinedError; end
+  class UnknownStatementError < NotDefinedError; end
+  class UnknownRetentionClassError < NotDefinedError; end
+
+  # --- Documents --------------------------------------------------------------
+
+  # Raised when a document version is required but has not been published, or
+  # when stored bytes no longer match their recorded digest.
+  class DocumentNotPublishedError < Error; end
+  class DocumentDigestMismatchError < Error; end
+
+  # Raised when a version label is reused for different bytes.
+  class DocumentVersionConflictError < Error; end
+
+  # --- Presentation and submission -------------------------------------------
+
+  # The family of refusals a PERSON can cause from a form: a stale or missing
+  # presentation, a submission that doesn't parse, a required box left empty.
+  # These are not application errors — they deserve a re-rendered form with a
+  # localized sentence, never a 500. One rescue covers the whole family:
+  #
+  #   rescue Clickwrap::CaptureRefused => refusal
+  #     redirect_to somewhere_path, alert: refusal.user_facing_message
+  #
+  # Everything OUTSIDE this family (an evidence write failure above all) stays
+  # loud on purpose: infrastructure problems are yours to see, not the
+  # person's to absorb.
+  class CaptureRefused < Error
+    # The localized sentence the gem's own screens show for this refusal —
+    # safe to put in front of a person, never a developer-facing message.
+    def user_facing_message
+      I18n.t("clickwrap.errors.presentation_no_longer_valid")
+    end
+  end
+
+  # Raised when the submitted presentation token is missing, malformed, signed
+  # with a different key, expired, or bound to a different actor, tenant,
+  # subject, policy, or revision than the one being captured.
+  class PresentationInvalid < CaptureRefused
+    attr_reader :result
+
+    def initialize(message = nil, result: nil)
+      @result = result
+      super(message || result&.message || "The presentation could not be verified")
+    end
+  end
+
+  class PresentationExpired < PresentationInvalid; end
+
+  # Raised when a submission cannot be parsed or contains keys the manifest
+  # never declared.
+  class SubmissionInvalid < CaptureRefused; end
+
+  # --- Capture ----------------------------------------------------------------
+
+  # Raised when a required answer is missing or an answer is not one of the
+  # choices the server offered.
+  class AnswerInvalid < CaptureRefused
+    attr_reader :statement_key, :reason
+
+    def initialize(message = nil, statement_key: nil, reason: nil)
+      @statement_key = statement_key
+      @reason = reason
+      super(message || "The submitted answer for #{statement_key.inspect} was not accepted")
+    end
+
+    def user_facing_message
+      I18n.t("clickwrap.errors.required_statement")
+    end
+  end
+
+  # Raised when the evidence event itself could not be written. The protected
+  # database action in the same transaction rolls back with it.
+  class EventWriteFailed < Error; end
+
+  # Raised when an identical idempotency key arrives with a different payload.
+  class ReplayRejected < Error; end
+
+  # Raised when a registration block returns without persisting the exact
+  # prospective actor the presentation was issued for.
+  class RegistrationFailed < Error; end
+
+  # Raised when a represented-party creation block does not return a persisted
+  # record of the type whose browser flow was bound at presentation.
+  class RepresentedPartyCreationFailed < Error; end
+
+  # Raised when delegated action was not explicitly permitted by the policy and
+  # positively verified by the host's authority callback.
+  class AuthorityNotVerified < Error; end
+
+  # Raised when a signed in-place remediation context is missing, expired,
+  # belongs to a different actor/tenant/policy, or names a resource that can no
+  # longer be resolved and authorized.
+  class RemediationInvalid < Error; end
+  class RemediationNotAuthorized < RemediationInvalid; end
+
+  # Raised when a deadlock or serialization failure occurred and Clickwrap
+  # cannot prove the caller's block is safe to retry. The host decides.
+  class RetryableTransactionError < Error; end
+
+  # --- Verification and gating ------------------------------------------------
+
+  # Raised by the bang verification methods. Always carries the same structured
+  # result the non-bang `Clickwrap.verify` would have returned, so applications
+  # never parse an English message to make an authorization decision.
+  class VerificationFailed < Error
+    attr_reader :result
+
+    def initialize(result)
+      @result = result
+      super(result.message)
+    end
+
+    def error = result.error
+  end
+
+  # --- Lifecycle --------------------------------------------------------------
+
+  class LifecycleError < Error; end
+  class AlreadyWithdrawnError < LifecycleError; end
+  class AlreadyConsumedError < LifecycleError; end
+  class OneTimeAuthorizationConflict < LifecycleError; end
+  class NotWithdrawableError < LifecycleError; end
+
+  # --- Request evidence, retention, and disposition ---------------------------
+
+  # Raised when a policy requires IP address, browser user-agent, or IP
+  # geolocation evidence and it could not be resolved.
+  class RequestEvidenceUnavailable < Error; end
+
+  # Raised when disposition is attempted on evidence under a legal hold.
+  class LegalHoldInEffect < Error; end
+
+  # Raised when ordinary Active Record mutation is attempted against evidence
+  # whose only permitted changes are named, audited lifecycle transitions.
+  class ImmutableEvidenceError < Error; end
+
+  # Raised when a disposition plan is stale, already applied, expired, or no
+  # longer matches what the operator reviewed.
+  class DispositionPlanInvalid < Error; end
+
+  # Raised when unredacted request evidence is requested without host
+  # authorization or without a human-readable reason.
+  class AccessNotAuthorized < Error; end
+
+  # --- Integrity and receipts -------------------------------------------------
+
+  # Raised when a receipt cannot be parsed, its schema version is unknown, or
+  # its canonical bytes do not match the digest it carries.
+  class ReceiptInvalid < Error; end
+  class UnknownReceiptSchema < ReceiptInvalid; end
+  class IntegrityCheckFailed < Error; end
+
+  # Raised when a pending receipt is used after its transaction rolled back, or
+  # when export/verification is called before commit.
+  class ReceiptNotCommitted < Error; end
+
+  # --- External actions -------------------------------------------------------
+
+  class ExternalActionError < Error; end
+  class ExternalActionAlreadyResolved < ExternalActionError; end
+end