zero-rails-adapter 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87460dcc3c79305e4ca81c9bd30800866a2a9c97709298955cdf16334723d442
-  data.tar.gz: 9c76ea660812fb14a1fa52fc148e00e973da5b670635dcd85242d781b93f0958
+  metadata.gz: ab52c7684cc6471e482808ce5bcdb64b7aa63ccbf8c9ae736feb535683198204
+  data.tar.gz: f69fa8c3101e9f8fff279af69103f5980a323dc856a70dd6b436f8bb92a9b37c
 SHA512:
-  metadata.gz: 13941576c897585d1253128412c7a3b062c273e407b1430e51cbae1f0dd9fc4a89d24b5fba7b8f5398ff610d72b64a38b286293af8146f6270bc5db27394a12c
-  data.tar.gz: e4785424bc04062e227084591faf341260d67177bf73c588494778b4037e25b9642fc6e444718554c90bdf371928ab71f7c01952c1dc4d3627d73c14f5b83ad5
+  metadata.gz: a8a68b2c6bc50703669edd95cf46e9b74c0a01c6b4414723a78b07c4158d8b37ef884ae4972e0c0bf5ae684f897c2416f4d2e1b1b8beb1a2d1fd967faa8a36f0
+  data.tar.gz: 8690225768276ff9ca61478486674f90b91f3b873ed190d95dc0bb7da5aea2f3a96d32f3c74ef24cc2d21fe54e731f03b136549638d3491dff3a354d1b7fc1d6

data/CHANGELOG.md

@@ -0,0 +1,150 @@
+# Changelog
+
+All notable changes to `zero-rails-adapter` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Because the project is still below 1.0, minor releases may contain breaking
+changes; those changes are called out explicitly below.
+
+## [Unreleased]
+
+## [0.3.1] - 2026-07-29
+
+### Security
+
+- Changed request verification, authentication, and global mutation
+  authorization defaults to fail closed. Applications must now configure every
+  gate explicitly.
+- Custom mutators without an `authorize_with` callback are rejected instead of
+  executing implicitly. The mutator generator scaffolds an explicit
+  deny-by-default callback.
+- Generated initializers now require `ZERO_MUTATE_API_KEY` with `ENV.fetch`
+  instead of silently disabling request verification when the variable is
+  absent.
+- Internal and database `PushFailed` responses no longer expose raw exception
+  messages. Full errors remain available to the configured server logger.
+
+### Fixed
+
+- Persist only explicit application and validation failures before advancing
+  LMID. Database failures and unexpected Ruby exceptions now roll back the
+  mutation completely and return a retry-safe `PushFailed`, allowing the same
+  mutation ID to succeed after the underlying problem is fixed.
+
+### Changed
+
+- Expanded the Zero 1.8 integration contract to use PostgreSQL UUID primary
+  keys and foreign keys and to cover request verification, authentication,
+  global and mutator authorization, sanitized internal failures, unchanged
+  LMID state, and successful same-ID replay.
+- Updated the contract's direct `ws` dependency from 8.18.3 to 8.21.1.
+
+### Upgrade notes
+
+Configure `request_verifier`, `authenticator`, and `authorizer` explicitly
+before accepting mutation traffic. Add `authorize_with` to every custom
+mutator, including mutators that intentionally rely only on the global
+authorizer. Regenerate the initializer if the application still conditionally
+configures `ZERO_MUTATE_API_KEY`.
+
+## [0.3.0] - 2026-07-29
+
+### Breaking changes
+
+- Changed model and column exposure from permissive to fail-closed. The adapter
+  no longer discovers and publishes every Active Record model by default.
+  Applications must define `published_schema` with both the models and columns
+  that Zero may replicate.
+- Split the former `model_provider` responsibility into `published_schema` for
+  replicated data and `crud_model_provider` for generic writes.
+- Made generic CRUD fully opt-in. `crud_model_provider` now defaults to an empty
+  list and `crud_authorizer` denies every operation by default. Publishing a
+  model does not make it writable.
+- Changed integer-backed Active Record enum generation from a string
+  enumeration to `number()`. String-backed Active Record enums generate
+  `string()`, while only PostgreSQL native enums generate Zero enumerations.
+
+### Upgrade notes
+
+Before upgrading an application from 0.2.0:
+
+1. Replace `model_provider` with an explicit `published_schema` table-and-column
+   allowlist.
+2. If generic CRUD is required, configure both `crud_model_provider` and
+   `crud_authorizer`. Keep them closed and use custom mutators for domain
+   operations that enforce application invariants.
+3. Regenerate `schema.ts` and `mutators.ts`.
+4. Generate and review the column-limited PostgreSQL publication SQL, apply it
+   through the application's normal database process, and point zero-cache at
+   that publication.
+5. Confirm that timestamp consumers treat Zero values as Unix epoch
+   milliseconds and update any code that assumed string-valued Rails enums.
+
+See the [README](README.md#explicit-publication-schema) for configuration
+examples.
+
+### Added
+
+- Added a table-and-column publication schema with validation for primary keys,
+  sensitive credentials, framework-internal tables, unknown columns, and
+  unsupported PostgreSQL types.
+- Added a generator for reviewable, column-limited PostgreSQL publication SQL.
+- Added `zero_key` for stable synchronization identifiers that differ from the
+  Active Record primary key, including composite keys. Separate keys must be
+  published and backed by exact unique, non-null database indexes.
+- Added explicit one-hop and two-hop relationship definitions for delegated,
+  polymorphic, through, custom-key, and other associations Rails cannot safely
+  infer.
+- Added an exact Zero 1.8 integration contract using PostgreSQL logical
+  replication, zero-cache, a Rails custom-mutator endpoint, and a real Zero
+  client.
+- Added coverage for replication queries, LMID advancement, duplicate
+  mutations, failed-mutation skipping, and `_zero_cleanupResults`.
+
+### Changed
+
+- Generic update and destroy now locate records through the configured Zero
+  key. Generic updates cannot change either the Zero key or the Active Record
+  primary key.
+- TypeScript generation now uses `published_schema` for tables and columns and
+  generates CRUD mutators only for models returned by `crud_model_provider`.
+- Timestamps are explicitly documented and generated as Unix epoch
+  milliseconds on the Zero side.
+- Manual relationships override inferred relationships with the same source
+  and name.
+
+### Security
+
+- Added default rejection for known credential columns such as password hashes
+  and token digests, authentication tables, Active Storage internals, and
+  Action Mailbox internals.
+- Publication validation rejects unsupported PostgreSQL types, including
+  `citext`; applications must exclude those columns or publish a supported safe
+  mirror column.
+- Prevented schema generation and PostgreSQL publication generation from
+  silently exposing newly discovered Active Record models or columns.
+
+## [0.2.0] - 2026-07-28
+
+### Added
+
+- Initial public release.
+- Added a mountable Rails Engine with Zero mutation endpoints.
+- Added generic Active Record create, update, and destroy operations using
+  validations, callbacks, associations, database constraints, and Rails
+  transactions.
+- Added explicit custom mutators through a Ruby DSL, base class, registry, and
+  Rails generator.
+- Added configurable request verification, authentication, authorization,
+  model resolution, writable-attribute policies, and transaction storage.
+- Added atomic Zero LMID tracking, mutation ordering, duplicate detection,
+  structured application errors, failed-mutation skipping, and cleanup-result
+  handling.
+- Added TypeScript schema and mutator generation from Active Record models.
+- Added Active Support mutation notifications and Rails/PostgreSQL test
+  coverage.
+
+[Unreleased]: https://github.com/mechiland/zero_rails_adapter/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/mechiland/zero_rails_adapter/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/mechiland/zero_rails_adapter/releases/tag/v0.3.0
+[0.2.0]: https://rubygems.org/gems/zero-rails-adapter/versions/0.2.0

data/README.md

@@ -3,6 +3,8 @@
 `zero-rails-adapter` is a mountable Rails Engine that maps Rocicorp Zero custom
 mutations directly to existing Active Record models.
 
+See the [changelog](CHANGELOG.md) for release notes and upgrade instructions.
+
 The default CRUD path does not require a Ruby Mutator class for every model:
 
 | Zero mutation | Rails call |
@@ -48,6 +50,10 @@ bundle install
 bin/rails generate zero_rails_adapter:install
 ```
 
+The generated initializer reads `ZERO_MUTATE_API_KEY` with `ENV.fetch`, so a
+missing key fails during application boot instead of disabling request
+verification.
+
 Mount the Engine:
 
 ```ruby
@@ -283,6 +289,17 @@ and writable-attribute interfaces below.
 The generated initializer supports `ZERO_MUTATE_API_KEY` and verifies
 zero-cache's `X-Api-Key` header using a constant-time comparison.
 
+All mutation security gates fail closed by default:
+
+- `request_verifier` returns `false`.
+- `authenticator` raises `UnauthorizedError`.
+- The global `authorizer` returns `false`.
+- The generic CRUD `crud_authorizer` returns `false`.
+
+Applications must configure each gate they use explicitly. An application that
+intentionally permits anonymous identities must still install an authenticator
+that returns `ZeroRailsAdapter::Identity.new`.
+
 The authentication interface receives the Rails request. It can integrate with
 Devise/Warden, any JWT library, a session, or an application-specific
 authentication system:
@@ -307,6 +324,10 @@ authorizer then receives the model class as `target` for create, or the loaded
 record for update and destroy:
 
 ```ruby
+config.authorizer = lambda do |context, mutation|
+  MutationPolicy.allowed?(context.current_user, mutation.name)
+end
+
 config.crud_authorizer = lambda do |context, action, target, attributes|
   MutationPolicy.new(
     context.current_user,
@@ -370,6 +391,10 @@ available:
 ZeroRailsAdapter.define_mutator "projects.archive" do
   attribute :id, :string
 
+  authorize_with do |context|
+    context.current_user.present?
+  end
+
   perform do
     Project.find(id).archive!(actor: context.current_user)
   end
@@ -377,7 +402,9 @@ end
 ```
 
 Mutators use Active Model attributes and validations and share a transaction
-with application writes and LMID tracking.
+with application writes and LMID tracking. A custom mutator without an
+`authorize_with` callback is rejected. To rely intentionally on the global
+authorizer alone, the mutator must still declare `authorize_with { true }`.
 
 ## Mutation Ordering and Transaction Semantics
 
@@ -389,11 +416,19 @@ For each `(schema, clientGroupID, clientID)`, the adapter:
 4. Executes the authorized Active Record operation inside a transaction.
 5. Updates the LMID atomically.
 
-When a business validation or callback fails, the first transaction rolls
-back. A second transaction advances the LMID and stores a structured `app`
-result so that a bad mutation is not retried forever and later mutations can
-continue. If the second transaction also fails, the adapter returns a
-retry-safe `PushFailed` response.
+When an explicit `ApplicationError`, argument validation error, or supported
+Active Model/Active Record validation or lifecycle error occurs, the first
+transaction rolls back. A second transaction advances the LMID and stores a
+structured `app` result so that a bad mutation is not retried forever and later
+mutations can continue.
+
+Database failures and unexpected Ruby exceptions do not advance LMID or store
+a mutation result. They return a retry-safe `PushFailed`, so the same mutation
+ID can be retried after the underlying problem is fixed. Public database and
+internal failure messages are fixed and sanitized; the configured server
+logger receives the original exception and backtrace. If persisting an
+application failure also fails, the adapter likewise returns `PushFailed`
+without advancing LMID.
 
 Each mutation owns an independent transaction. A later failure in the same
 HTTP batch does not roll back earlier committed mutations.
@@ -446,9 +481,11 @@ bundle exec rake contract
 
 That task compiles the generated TypeScript, starts PostgreSQL with logical
 replication, starts the real zero-cache and Rails mutation endpoint, then uses
-a Zero client to mutate and query replicated rows. The generated fixture
-includes a separate Zero key and a two-hop relationship. The task also verifies
-LMID advancement, duplicate-mutation handling, failure skipping, and
+a Zero client to mutate and query replicated rows. The generated fixture uses
+UUID primary and foreign keys and includes a separate Zero key and a two-hop
+relationship. The task also verifies request verification, authentication,
+global and mutator authorization, sanitized retry-safe failures, same-ID
+replay, LMID advancement, duplicate-mutation handling, failure skipping, and
 `_zero_cleanupResults`. The contract runs as its own CI job.
 
 See [`examples/nextjs`](examples/nextjs) for a Next.js integration fixture.

data/app/controllers/zero_rails_adapter/mutations_controller.rb

@@ -27,7 +27,11 @@ module ZeroRailsAdapter
       ZeroRailsAdapter.configuration.logger&.error(
         "ZeroRailsAdapter request failed: #{error.class}: #{error.message}"
       )
-      render json: push_failed("internal", error.message, []), status: :internal_server_error
+      render json: push_failed(
+        "internal",
+        Processor::INTERNAL_ERROR_MESSAGE,
+        []
+      ), status: :internal_server_error
     end
 
     private

data/lib/generators/zero_rails_adapter/install/templates/initializer.rb

@@ -6,11 +6,9 @@ ZeroRailsAdapter.configure do |config|
 
   # Verify that calls came from your zero-cache instance.
   # Configure zero-cache with ZERO_MUTATE_API_KEY using the same value.
-  if ENV["ZERO_MUTATE_API_KEY"].present?
-    config.request_verifier = ZeroRailsAdapter::RequestVerifiers::ApiKey.new(
-      key: ENV.fetch("ZERO_MUTATE_API_KEY")
-    )
-  end
+  config.request_verifier = ZeroRailsAdapter::RequestVerifiers::ApiKey.new(
+    key: ENV.fetch("ZERO_MUTATE_API_KEY")
+  )
 
   # Return an Identity from any authentication system (Devise, JWT, cookies, etc.).
   # config.authenticator = lambda do |request|

data/lib/generators/zero_rails_adapter/mutator/templates/mutator.rb

@@ -7,8 +7,11 @@ class <%= class_name %> < ZeroRailsAdapter::Mutator
   # attribute :title, :string
   # validates :title, presence: true
 
+  authorize_with do |_context|
+    false
+  end
+
   def perform
-    # Use context.current_user, context.user_id, and context.claims for authorization.
     raise NotImplementedError
   end
 end

data/lib/zero_rails_adapter/configuration.rb

@@ -9,9 +9,11 @@ module ZeroRailsAdapter
       :relationship_provider
 
     def initialize
-      @authenticator = ->(_request) { Identity.new }
-      @request_verifier = ->(_request) { true }
-      @authorizer = ->(_context, _mutation) { true }
+      @authenticator = lambda do |_request|
+        raise UnauthorizedError, "Authentication is not configured"
+      end
+      @request_verifier = ->(_request) { false }
+      @authorizer = ->(_context, _mutation) { false }
       @crud_authorizer = ->(_context, _action, _target, _attributes) { false }
       @logger = defined?(Rails) ? Rails.logger : nil
       @transaction_class = ActiveRecord::Base

data/lib/zero_rails_adapter/mutator.rb

@@ -61,7 +61,9 @@ module ZeroRailsAdapter
 
     def authorize!
       callback = self.class.authorization_callback
-      return true unless callback
+      unless callback
+        raise ForbiddenError, "Mutator authorization is not configured"
+      end
       return true if instance_exec(context, &callback)
 
       raise ForbiddenError, "Mutation is not authorized"

data/lib/zero_rails_adapter/processor.rb

@@ -3,6 +3,16 @@
 module ZeroRailsAdapter
   class Processor
     CLEANUP_MUTATION_NAME = "_zero_cleanupResults"
+    DATABASE_ERROR_MESSAGE = "Database error"
+    INTERNAL_ERROR_MESSAGE = "Internal server error"
+    PERSISTABLE_MUTATION_ERRORS = [
+      ActiveModel::UnknownAttributeError,
+      ActiveModel::ValidationError,
+      ActiveRecord::RecordInvalid,
+      ActiveRecord::RecordNotDestroyed,
+      ActiveRecord::RecordNotFound,
+      ActiveRecord::RecordNotSaved
+    ].freeze
 
     attr_reader :request, :context, :storage
 
@@ -47,16 +57,20 @@ module ZeroRailsAdapter
         mutation_ids: request.mutation_ids.drop(processed_count)
       )
     rescue ActiveRecord::ActiveRecordError => error
+      mutation_ids = request.mutation_ids.drop(processed_count)
+      log_push_failure(error, reason: "database", mutation_ids:)
       push_failed(
         reason: "database",
-        message: error.message,
-        mutation_ids: request.mutation_ids.drop(processed_count)
+        message: DATABASE_ERROR_MESSAGE,
+        mutation_ids:
       )
     rescue StandardError => error
+      mutation_ids = request.mutation_ids.drop(processed_count)
+      log_push_failure(error, reason: "internal", mutation_ids:)
       push_failed(
         reason: "internal",
-        message: error.message,
-        mutation_ids: request.mutation_ids.drop(processed_count)
+        message: INTERNAL_ERROR_MESSAGE,
+        mutation_ids:
       )
     end
 
@@ -84,7 +98,7 @@ module ZeroRailsAdapter
       already_processed_response(mutation, error)
     rescue OutOfOrderMutationError
       raise
-    rescue StandardError => error
+    rescue ApplicationError, *PERSISTABLE_MUTATION_ERRORS => error
       application_error = normalize_application_error(error)
       begin
         persist_failure(mutation, application_error)
@@ -138,8 +152,10 @@ module ZeroRailsAdapter
     def normalize_application_error(error)
       return error if error.is_a?(ApplicationError)
 
-      if error.respond_to?(:record) && error.record.respond_to?(:errors)
-        return ApplicationError.new(error.message, details: error.record.errors.to_hash)
+      model = error.record if error.respond_to?(:record)
+      model ||= error.model if error.respond_to?(:model)
+      if model.respond_to?(:errors)
+        return ApplicationError.new(error.message, details: model.errors.to_hash)
       end
 
       ApplicationError.new(error.message)
@@ -174,5 +190,17 @@ module ZeroRailsAdapter
         "mutationIDs" => mutation_ids
       }
     end
+
+    def log_push_failure(error, reason:, mutation_ids:)
+      ZeroRailsAdapter.configuration.logger&.error(
+        "ZeroRailsAdapter push failed: " \
+        "reason=#{reason} request_id=#{request.request_id.inspect} " \
+        "mutation_ids=#{mutation_ids.inspect} " \
+        "#{error.class}: #{error.message}\n" \
+        "#{Array(error.backtrace).join("\n")}"
+      )
+    rescue StandardError
+      nil
+    end
   end
 end

data/lib/zero_rails_adapter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZeroRailsAdapter
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zero-rails-adapter
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Zero Rails Adapter contributors
@@ -35,6 +35,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
 - app/controllers/zero_rails_adapter/mutations_controller.rb
@@ -87,7 +88,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.16
 specification_version: 4
 summary: A Rails 8 Active Record adapter for Rocicorp Zero
 test_files: []