mixin_bot 2.6.0 → 3.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42fc9aa30981430bf8a4b32ac343994fedb94f3a318d4c519404f788f66d8c68
-  data.tar.gz: df1037544f1eb11ec4cf196aacbd076db8a3aa6c2dc11ed1d138751cdb37e073
+  metadata.gz: 520bf980215da4e70c9fa6ae1d9297874fc16fc8264a43bb019a126f0fb0d555
+  data.tar.gz: 1d5cf99a0e645d4ae110e73148b501bd5f942b3f2c0e9ac0a4338d2d38699a7a
 SHA512:
-  metadata.gz: a12c51222b50582cd31b4e80d17f3f95c73627845ec3500701a02de21d68de887e85ccf599e505be8ec81ce6c903485ec193ae6ee3e865dce9e2bd2b984ef023
-  data.tar.gz: 1dbb16ececb43acf6febcc42467ffb631b064fcb508f235c4a6e19148c15c328935a9ec1a297bffa45baebd70fc0b7458bf98d374fc2f5c0930734345bf67d29
+  metadata.gz: b73f1bd21043e018410555d93a537b2314f3398a174bf7ce443cce1652b578e425569faa9118d413789607f106863dbf08b1b79ef4da643f28c40fdbad065479
+  data.tar.gz: 49b66d6300397db22af3f28688eca9999a68ad47f07689a84f94a6c43831d96e0ad42c88d7b95cb3a12f531ab4bf4d5540f84cb0f070508687027f20337ff36a

data/AGENTS.md

@@ -1,6 +1,6 @@
 # AGENTS.md — MixinBot
 
-Ruby gem (v2.3.0): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
+Ruby gem (v3.0.2): Mixin Network REST SDK + `mixinbot` CLI. Parity targets: [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client), [bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client).
 
 ## Commands
 
@@ -34,13 +34,13 @@ docs/agent/             # LLM-oriented CLI and cookbook docs
 
 ## CI and release
 
-- **CI** (`.github/workflows/ci.yml`): `pull_request` and `push` to `main` — `rake test` on Ruby 3.2/3.3/4.0, `rake rubocop` (3.3), `rake mixin_bot:api_coverage`.
+- **CI** (`.github/workflows/ci.yml`): `pull_request` and `push` to `main` — `rake test` on Ruby 4.0, `rake rubocop` (4.0), `rake mixin_bot:api_coverage`.
 - **Release** (`.github/workflows/release.yml`): push tag `v*` (must match `MixinBot::VERSION`, e.g. tag `v2.1.0` for `VERSION = '2.1.0'`) → `rake build` → RubyGems via [trusted publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC; workflow `release.yml`, no repo secret) → GitHub Release (notes from `CHANGELOG.md`, `.gem` attached).
 - **Dependabot** (`.github/dependabot.yml`): weekly Bundler and GitHub Actions updates; Dependabot PRs use the same CI workflow.
 
 ## Conventions
 
-- **Ruby** >= 3.2 (CI: 3.2, 3.3, 4.0)
+- **Ruby** >= 4.0 (CI: 4.0)
 - **HTTP responses**: `MixinBot::Models::ApiEnvelope` — use `res['data']` or delegated keys
 - **Safe transfers**: require `spend_key`; prefer `create_safe_transfer` / `create_transfer` (Safe pipeline)
 - **Legacy APIs**: `create_legacy_transfer`, `POST /transfers` — deprecated, warns once

data/API_COVERAGE.md

@@ -81,6 +81,7 @@ Status values: `done` | `alias` | `n/a` (CLI-only / config / platform-specific)
 | **Snapshots** |
 | SafeSnapshots* | `API#safe_snapshots` | GET `/safe/snapshots` | done |
 | SafeSnapshotById | `API#safe_snapshot` | GET `/safe/snapshots/:id` | done |
+| SafeSnapshotByTrace | `API#safe_snapshot_by_trace` | GET `/safe/snapshots/trace/:trace_id` | done |
 | SafeNotifySnapshot | `API#create_safe_snapshot_notification` | POST notifications | done |
 | Snapshots / SnapshotById / SnapshotByTraceId | `API#snapshots`, `#snapshot`, `#snapshot_by_trace_id` | legacy | done |
 | NetworkSnapshot* | `API#network_snapshot(s)` | legacy | done |

data/CHANGELOG.md

@@ -5,7 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [3.0.2] - 2026-09-24
+
+### Added
+
+- **`MixinBot::API#update_app_security`** — `POST /apps/:id/security`, the endpoint that persists an app's `allowed_ips` and `resource_patterns`. The generic `update_app` endpoint silently ignores both fields, so code that tried to manage the resource-pattern whitelist through it was a no-op.
+
+## [3.0.1] - 2026-09-19
+
+### Fixed
+
+- **Blaze reconnect backoff no longer resets on short-lived connections.** `Reactor::STABLE_PERIOD` (the lifetime a connection needs for the backoff to reset) was exactly `MAX_BACKOFF` (30s), so any failure mode that closes sessions at a ~30s lifetime (e.g. a gateway throttling abusive reconnect patterns) read as "stable" on every cycle — the backoff pinned at the initial 1s and the reactor reconnected hot indefinitely, which is itself the abuse pattern that triggers such throttling. `STABLE_PERIOD` is now 120s (well above every single backoff step) and `MAX_BACKOFF` grows the ceiling to 300s so a sustained failure mode backs off hard while a single transient blip still reconnects in ~1s.
+
+## [3.0.0] - 2026-09-15
+
+### Added
+
+- **Puma plugin hosting the Blaze connection** (`plugin :mixin_blaze`) — Solid Queue-style in-process hosting, removing the standalone Blaze deployment artifact. Dual run modes via the `mixin_blaze_mode` Puma DSL option: `:fork` (default) forks a dedicated Blaze child on `on_booted` with a monitor thread that stops Puma if the child dies, terminated on `on_stopped`/`on_restart`; `:async` runs the reactor on a Puma background thread in-process. Handler resolution comes from `MixinBot` configuration (resolved lazily after app boot) with an explicit ack policy (on-receipt vs after-handler); Puma 6/7 lifecycle-event compatibility; cluster mode requires `preload_app!` and fails loudly without it. Puma remains a host-app concern — no new gem dependency.
+- **`MixinBot::Blaze::Reactor`** — reusable Blaze loop (connect, keepalive ping, read → handler → ack, reconnect with backoff) wrapping `API#blaze_async`; extracted from `examples/blaze_async.rb` so the plugin shell stays thin and the loop is unit-testable offline.
+
+### Changed
+
+- **Breaking**: Ruby >= 4.0 is now required — `required_ruby_version` bumped from `>= 3.2.0` to `>= 4.0.0`. The CI matrix, RuboCop target, and Release workflow all run Ruby 4.0; the dev-only `parallel` version pin (kept for the old Ruby 3.2 floor) was dropped.
 
 ## [2.6.0] - 2026-09-07
 

data/README.md

@@ -6,12 +6,12 @@ Ruby SDK and CLI for [Mixin Network](https://developers.mixin.one/docs): authent
 
 The gem aims for **parity with the official [bot-api-go-client](https://github.com/MixinNetwork/bot-api-go-client)** Go SDK and **[bot-api-nodejs-client](https://github.com/MixinNetwork/bot-api-nodejs-client)** Node SDK. See [API_COVERAGE.md](API_COVERAGE.md) for the full mapping; run `rake mixin_bot:api_coverage` to confirm no gaps are marked missing.
 
-Current gem version: **2.6.0** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
+Current gem version: **3.0.2** (see [CHANGELOG.md](CHANGELOG.md) for breaking changes and deprecations).
 
 ## Requirements
 
-- **Ruby** ≥ 3.2 (CI runs 3.2, 3.3, and 4.0).
-- **Bundler** 2.5+ recommended, especially on Ruby 4.
+- **Ruby** ≥ 4.0 (CI runs 4.0).
+- **Bundler** 2.6+ recommended.
 - Optional: the **`mixin`** CLI in `PATH` if you use `MixinBot::API#encode_raw_transaction_native` / `#decode_raw_transaction_native` or the experimental `MixinBot::NodeCLI` helpers.
 
 ## Installation
@@ -290,6 +290,117 @@ ensure
 end
 ```
 
+### Running Blaze inside Puma (`plugin :mixin_blaze`)
+
+For Rails/Puma apps, the gem ships a Puma plugin (Solid Queue-style) that hosts the Blaze connection inside the web process tree — no standalone Blaze process to deploy or supervise:
+
+```ruby
+# config/puma.rb
+plugin :mixin_blaze
+mixin_blaze_mode :fork # default; see table below
+```
+
+```ruby
+# config/initializers/mixin_bot.rb
+MixinBot.configure do
+  # ... credentials ...
+  self.blaze_handler = ->(envelope) { MyBot.process! envelope }
+  self.blaze_ack_policy = :on_receipt # default; or :after_handler
+end
+```
+
+The handler receives each decoded message envelope (a Hash with `action` and `data` keys) and runs serially on the hosting thread — safe for ActiveRecord. Handlers run one message at a time; the keepalive ping runs separately.
+
+| Mode | Where the connection lives | Notes |
+|---|---|---|
+| `:fork` (default) | Dedicated child process forked from the Puma launcher | Crash-isolated; if the child dies, Puma is stopped so the process manager restarts the unit |
+| `:async` | Background thread inside the Puma process itself | In cluster mode that process is the master; no child process |
+
+Ack policy: `:on_receipt` acknowledges each message immediately (at-most-once dispatch — a handler crash loses that message); `:after_handler` acknowledges only after the handler completes without raising (at-least-once — handlers must be idempotent, since unacknowledged messages are redelivered on reconnect).
+
+Receipt confirmations (`ACKNOWLEDGE_MESSAGE_RECEIPT` frames the server pushes for your own outgoing/acknowledged messages) are consumed internally: the handler never sees them and they are never re-acknowledged.
+
+Operational notes:
+
+- **Remove any standalone Blaze process when enabling the plugin** — two connections double your handler invocations (or split deliveries).
+- **Cluster mode requires `preload_app!`** — plugins run in the launcher process, which holds no application code without preloading; the plugin reports an error and stays off otherwise.
+- **Phased restarts keep the old handler code** in the hosting process until a full restart; the same applies to Solid Queue's plugin.
+- Workers that need to *send* messages should use the REST API (`create_message` / `create_messages`), not the socket.
+
+## Rails integration
+
+The gem ships Rails generators under the `mixin_bot:` namespace. The first one sets up **"Sign in with Mixin"** (OAuth login via [`omniauth-mixin`](https://github.com/an-lee/omniauth-mixin)), modeled on Rails' built-in `rails g authentication`:
+
+```bash
+rails generate mixin_bot:authentication
+```
+
+This creates an identity-only Mixin login: OmniAuth initializer, `User` / `Session` / `Current` models, `SessionsController` with the OAuth callback, an `Authentication` controller concern (injected into `ApplicationController`), a sign-in view, routes, and the `CreateUsers` / `CreateSessions` migrations. It also adds `omniauth-mixin` and `omniauth-rails_csrf_protection` to the Gemfile (uncommenting existing entries, otherwise `bundle add`) and runs migrations generation. Run `bin/rails db:migrate` afterwards.
+
+Then:
+
+- Set `MIXIN_CLIENT_ID` and `MIXIN_CLIENT_SECRET` from the [Mixin Developer Dashboard](https://developers.mixin.one/dashboard).
+- Register `https://<your-host>/auth/mixin/callback` as the OAuth redirect URL of your Mixin app.
+
+Notes:
+
+- **Identity only** — the OAuth exchange is used to establish identity (Mixin user id + name + avatar). Access/refresh tokens are not persisted; a future generator may add API-access wiring on top.
+- **Fail loud at sign-in, not at boot** — the app boots fine without credentials (deploys, CI, `assets:precompile`); attempting to sign in raises an error naming the missing `MIXIN_CLIENT_ID` / `MIXIN_CLIENT_SECRET`.
+- **CSRF-protected request phase** — the sign-in button POSTs to `/auth/mixin` (OmniAuth 2.x default request method, protected by `omniauth-rails_csrf_protection`); the provider redirects back to the `/auth/mixin/callback` GET route.
+- **Existing apps beware** — like `rails g authentication`, the generator templates over target files (e.g. an existing `User` model) and will prompt on conflicts; reconcile manually if you already have users.
+- Sessions are database-backed (`sessions` table with `ip_address` / `user_agent`) with a signed httponly cookie, exactly like Rails 8's `authentication` generator; `Current.user` is available after sign-in.
+
+The generated code depends only on Rails and the two OmniAuth gems — not on `mixin_bot` itself — so the login keeps working even if you later drop the gem from the app.
+
+### The full Rails integration layer (`require 'mixin_bot/rails'`)
+
+Beyond the generators, the gem ships an optional runtime integration layer. It is opt-in and Rails stays a soft dependency:
+
+```ruby
+# config/application.rb, after Bundler.require
+require 'mixin_bot/rails'
+```
+
+Or scaffold everything in one command and skip pieces as needed:
+
+```bash
+rails generate mixin_bot:install
+rails generate mixin_bot:install --skip-notifications --skip-transfers
+```
+
+What each piece gives you:
+
+- **Blaze message routing** — `MixinBot::Blaze::Router` is a callable that plugs into `config.blaze_handler`. Handlers live in `app/mixin/handlers`, receive a decoded `Message`, and reply over the HTTP message API (no WebSocket access needed):
+
+  ```ruby
+  # config/initializers/mixin_bot_blaze.rb (generated by `rails g mixin_bot:blaze`)
+  Rails.application.config.to_prepare do
+    MixinBot.configure do
+      self.blaze_handler = MixinBot::Blaze::Router.new do
+        on 'text', Mixin::Handlers::TextHandler       # 'text' => PLAIN_TEXT
+        on 'transfer', Mixin::Handlers::TransferHandler
+      end
+    end
+  end
+  ```
+
+  Pair with the Puma plugin (`plugin :mixin_blaze`) so messages are received inside the web process tree. Per-bot: `MixinBot::Blaze::Router.new(api: MixinBot.bot(:shop))`.
+
+- **Outputs polling** — `rails g mixin_bot:outputs` creates a receipt table (unique per `bot_app_id` + `output_id` — the dedup gate) and an example processor in `app/mixin/processors`. The poller's resume cursor is derived from the receipts themselves (newest recorded output `sequence` per bot — unique, monotonic, and the key the outputs API paginates on) — no separate cursor table. Run `rails mixin_bot:poller` (standalone process; pass `[bot_name]` for a registered bot). Every output — inbound *and* outbound — is delivered to matching processors through your job queue; memos bridge lazily via the snapshot notification API. Processors implement `self.matches?(envelope)` + `#process` and should be idempotent (dispatch is at-least-once).
+
+- **Outbound transfers** — `rails g mixin_bot:transfers` creates a `MixinTransfer` ledger with the state machine (`pending → broadcast → confirmed | failed | reconciling`). Creating a record enqueues the Safe pipeline with the record's `trace_id` as the request id — retries are network-deduplicated. A timeout after submission lands in `reconciling`; the recurring `MixinTransfers.ReconcileJob` confirms from the trace snapshot or re-sends safely.
+
+- **Mixin notifications** — `rails g mixin_bot:notifications` adds `noticed` and an example notification with `deliver_by :mixin`. The channel (`MixinBot::Notifications::MixinChannel`) sends text/post/app-card messages with the configured bot's credentials; it loads only when Noticed is present.
+
+Multiple bots in one process: register named bots, then reference them everywhere (`MixinBot.bot(:shop)`, `mixin_bot:poller[shop]`, `Router.new(api: ...)`, `deliver_by :mixin, bot: :shop`):
+
+```ruby
+MixinBot.register_bot :shop,
+                      app_id: '...', session_id: '...',
+                      session_private_key: '...', server_public_key: '...',
+                      spend_key: '...'
+```
+
 ## Deep links and bot auth
 
 ```ruby
@@ -396,8 +507,8 @@ Examples under `examples/` expect `examples/config.yml` (copy from `examples/con
 
 GitHub Actions runs on every pull request and on pushes to `main`:
 
-- **Test** — Ruby 3.2, 3.3, and 4.0: `bundle exec rake test`
-- **RuboCop** — Ruby 3.3: `bundle exec rake rubocop`
+- **Test** — Ruby 4.0: `bundle exec rake test`
+- **RuboCop** — Ruby 4.0: `bundle exec rake rubocop`
 - **API coverage** — `bundle exec rake mixin_bot:api_coverage`
 
 ### Release

data/docs/agent/cookbook.md

@@ -130,6 +130,55 @@ end
 
 See [examples/blaze.rb](../../examples/blaze.rb).
 
+## Blaze inside Puma (`plugin :mixin_blaze`)
+
+For Rails/Puma apps the gem ships a Puma plugin (Solid Queue-style) that hosts the Blaze connection inside the web process tree — no standalone Blaze process. Requires a configured `blaze_handler`; without one the plugin logs an error and stays off.
+
+```ruby
+# config/puma.rb
+plugin :mixin_blaze
+mixin_blaze_mode :fork # default (:fork = supervised child process); :async = in-process thread
+
+# config/initializers/mixin_bot.rb
+MixinBot.configure do
+  # ... credentials ...
+  self.blaze_handler = ->(envelope) { MyBot.process! envelope } # required
+  self.blaze_ack_policy = :on_receipt # default; :after_handler = ack after handler success
+end
+```
+
+Behavior: reconnect with bounded backoff, keepalive pings, serial handler dispatch (ActiveRecord-safe), handler exceptions logged without ending delivery, graceful shutdown with Puma (child killed on stop; in `:fork` mode a dead child stops Puma so the unit restarts). `ACKNOWLEDGE_MESSAGE_RECEIPT` confirmations are consumed internally — the handler never sees them and they are never re-acknowledged.
+
+Operational notes:
+
+- **Remove any standalone Blaze process when enabling the plugin** — duplicate connections duplicate handler invocations.
+- **Puma cluster mode requires `preload_app!`** — plugins run in the launcher process; without preloading there is no app code to resolve the handler and the plugin reports an error.
+- **Phased restarts keep old handler code** in the hosting process until a full restart.
+- Workers that need to *send* messages use the REST API (`create_message`), not the socket.
+
+## Mixin login for a Rails app (`rails g mixin_bot:authentication`)
+
+Task: add "Sign in with Mixin" (OAuth identity login) to an existing Rails app.
+
+```bash
+bundle add mixin_bot            # if not already present
+rails generate mixin_bot:authentication
+bin/rails db:migrate
+```
+
+Generated: `config/initializers/omniauth.rb` (OmniAuth `:mixin` provider), `app/models/{user,session,current}.rb`, `app/controllers/sessions_controller.rb` + `app/controllers/concerns/authentication.rb` (injected into `ApplicationController`), `app/views/sessions/new.html.erb`, `resource :session` + `/auth/mixin/callback` routes, and `CreateUsers` (`mixin_user_id` unique, `name`, `avatar_url`) / `CreateSessions` migrations. The Gemfile gains `omniauth-mixin` and `omniauth-rails_csrf_protection`.
+
+Required environment: `MIXIN_CLIENT_ID`, `MIXIN_CLIENT_SECRET` (from the Mixin Developer Dashboard); register `https://<host>/auth/mixin/callback` as the OAuth redirect URL.
+
+Behavior notes for agents:
+
+- **Identity only** — sign-in stores the Mixin user id + name + avatar (`User.find_or_create_by_mixin_auth!`, matched by uid). OAuth access/refresh tokens are never persisted; do not add token columns to the generated models.
+- **Boot is safe without credentials** (CI / `assets:precompile`); a sign-in attempt without them raises `ArgumentError` naming the missing env vars (OmniAuth setup phase).
+- **Request phase is POST + CSRF** (`button_to` → `/auth/mixin`, `omniauth-rails_csrf_protection`); callback is the GET route → `sessions#create`. A GET to `/auth/mixin` is rejected (OmniAuth 2.x).
+- **Sessions** are DB-backed (`sessions` rows, `ip_address`/`user_agent`) remembered in a signed httponly cookie; `Current.user` after sign-in; unauthenticated requests redirect to the sign-in page and return after login; `terminate_session` on sign-out.
+- **Self-contained** — generated code references no `mixin_bot` APIs; the login survives removing the gem. Re-running the generator does not duplicate routes or Gemfile entries; template conflicts prompt like any Rails generator (an existing `User` model is overwritten only if you choose so).
+- To call Mixin APIs on behalf of a signed-in user afterwards, use the gem's OAuth machinery (`MixinBot::API` with delegated authorization) separately from the generated authentication code.
+
 ## Discover API methods
 
 ```bash

data/examples/blaze_async.rb

@@ -40,10 +40,12 @@ def send_frame(connection, bytes)
 end
 
 Async do |task|
-  # endpoint_options: is forwarded to Async::HTTP::Endpoint.parse (a connect
-  # timeout here). handler: stays default; pass an Async::WebSocket::Connection
-  # subclass to hook the raw frame events (e.g. PONG correlation).
-  connection = API.blaze_async(endpoint_options: { timeout: 10 })
+  # endpoint_options: is forwarded to Async::HTTP::Endpoint.parse. No
+  # timeout: here — it would become the socket's per-read timeout and kill
+  # quiet-but-healthy connections; liveness is the keepalive ping below.
+  # handler: stays default; pass an Async::WebSocket::Connection subclass to
+  # hook the raw frame events (e.g. PONG correlation).
+  connection = API.blaze_async
   p [Time.now.to_s, :connected]
 
   # liveness is the caller's policy: nothing on the wire goes stale quietly

data/lib/generators/mixin_bot/authentication/USAGE

@@ -0,0 +1,29 @@
+Description:
+    Adds "Sign in with Mixin" to this Rails application using OmniAuth
+    (omniauth-mixin): User/Session/Current models, a sessions controller with
+    the OAuth callback, an authentication concern, routes, migrations, and
+    the OmniAuth initializer.
+
+    The generated login is identity-only: the OAuth access token is used to
+    establish identity and is not persisted.
+
+    After generating, set MIXIN_CLIENT_ID and MIXIN_CLIENT_SECRET, and register
+    https://<your-host>/auth/mixin/callback as the OAuth redirect URL in the
+    Mixin developer dashboard.
+
+Example:
+    rails generate mixin_bot:authentication
+
+    This will create:
+        config/initializers/omniauth.rb
+        app/models/user.rb
+        app/models/session.rb
+        app/models/current.rb
+        app/controllers/sessions_controller.rb
+        app/controllers/concerns/authentication.rb
+        app/views/sessions/new.html.erb
+        db/migrate/xxx_create_users.rb
+        db/migrate/xxx_create_sessions.rb
+
+    It will also add `omniauth-mixin` and `omniauth-rails_csrf_protection` to
+    the Gemfile and inject `include Authentication` into ApplicationController.

data/lib/generators/mixin_bot/authentication/authentication_generator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:authentication` — sets up "Sign in with Mixin"
+    # via OmniAuth, modeled on Rails' built-in `authentication` generator.
+    # Identity only: the OAuth tokens are used to establish identity and are
+    # not persisted.
+    class AuthenticationGenerator < Rails::Generators::Base
+      # Rails 8.1 moved bundle_command out of Actions into BundleHelper.
+      unless method_defined?(:bundle_command) || private_method_defined?(:bundle_command)
+        begin
+          require 'rails/generators/bundle_helper'
+          include Rails::Generators::BundleHelper
+        rescue LoadError
+          # Older Rails ships bundle_command in Rails::Generators::Actions.
+        end
+      end
+
+      source_root File.expand_path('templates', __dir__)
+
+      SESSION_ROUTE = 'resource :session, only: [:new, :destroy]'
+      CALLBACK_ROUTE = "get '/auth/mixin/callback', to: 'sessions#create'"
+      OMNIAUTH_GEMS = %w[omniauth-mixin omniauth-rails_csrf_protection].freeze
+
+      def create_authentication_files
+        template 'config/initializers/omniauth.rb'
+        template 'app/models/user.rb'
+        template 'app/models/session.rb'
+        template 'app/models/current.rb'
+        template 'app/controllers/sessions_controller.rb'
+        template 'app/controllers/concerns/authentication.rb'
+        template 'app/views/sessions/new.html.erb'
+      end
+
+      def configure_application_controller
+        inject_into_class 'app/controllers/application_controller.rb', 'ApplicationController', "  include Authentication\n"
+      end
+
+      def configure_authentication_routes
+        route SESSION_ROUTE
+        route CALLBACK_ROUTE
+      end
+
+      def add_migrations
+        generate 'migration', 'CreateUsers', 'mixin_user_id:string!:uniq name:string avatar_url:string', '--force'
+        generate 'migration', 'CreateSessions', 'user:references ip_address:string user_agent:string', '--force'
+      end
+
+      def add_omniauth_gems
+        gemfile = File.read(gemfile_path)
+        uncommented = []
+
+        OMNIAUTH_GEMS.each do |name|
+          pattern = /gem\s+["']#{Regexp.escape(name)}["']/
+          next if gemfile.match?(/^\s*#{pattern}/) # already present
+
+          if gemfile.match?(/^\s*#\s*#{pattern}/)
+            uncomment_lines 'Gemfile', pattern
+            uncommented << name
+          else
+            # Single positional call: bundle_command signatures differ across
+            # railties versions (8.1 BundleHelper is (command, env, params);
+            # older Actions is (command, options)) — only this shape is valid
+            # on all of them, and bundler handles --quiet itself.
+            bundle_command("add #{name} --quiet")
+          end
+        end
+
+        bundle_command('install --quiet') unless uncommented.empty?
+      end
+
+      private
+
+      def gemfile_path
+        File.expand_path('Gemfile', destination_root)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/authentication/templates/app/controllers/concerns/authentication.rb.tt

@@ -0,0 +1,52 @@
+module Authentication
+  extend ActiveSupport::Concern
+
+  included do
+    before_action :require_authentication
+    helper_method :authenticated?
+  end
+
+  class_methods do
+    def allow_unauthenticated_access(**options)
+      skip_before_action :require_authentication, **options
+    end
+  end
+
+  private
+    def authenticated?
+      resume_session
+    end
+
+    def require_authentication
+      resume_session || request_authentication
+    end
+
+    def resume_session
+      Current.session ||= find_session_by_cookie
+    end
+
+    def find_session_by_cookie
+      Session.find_by(id: cookies.signed[:session_id]) if cookies.signed[:session_id]
+    end
+
+    def request_authentication
+      session[:return_to_after_authenticating] = request.url
+      redirect_to new_session_path
+    end
+
+    def after_authentication_url
+      session.delete(:return_to_after_authenticating) || root_url
+    end
+
+    def start_new_session_for(user)
+      user.sessions.create!(user_agent: request.user_agent, ip_address: request.remote_ip).tap do |session|
+        Current.session = session
+        cookies.signed.permanent[:session_id] = { value: session.id, httponly: true, same_site: :lax }
+      end
+    end
+
+    def terminate_session
+      Current.session&.destroy
+      cookies.delete(:session_id)
+    end
+end

data/lib/generators/mixin_bot/authentication/templates/app/controllers/sessions_controller.rb.tt

@@ -0,0 +1,24 @@
+class SessionsController < ApplicationController
+  allow_unauthenticated_access only: %i[new create]
+
+  def new
+  end
+
+  def create
+    auth = request.env["omniauth.auth"]
+
+    unless auth
+      redirect_to new_session_path, alert: "Sign in with Mixin failed. Please try again."
+      return
+    end
+
+    user = User.find_or_create_by_mixin_auth!(auth)
+    start_new_session_for user
+    redirect_to after_authentication_url
+  end
+
+  def destroy
+    terminate_session
+    redirect_to new_session_path, status: :see_other
+  end
+end

data/lib/generators/mixin_bot/authentication/templates/app/models/current.rb.tt

@@ -0,0 +1,4 @@
+class Current < ActiveSupport::CurrentAttributes
+  attribute :session
+  delegate :user, to: :session, allow_nil: true
+end

data/lib/generators/mixin_bot/authentication/templates/app/models/session.rb.tt

@@ -0,0 +1,3 @@
+class Session < ApplicationRecord
+  belongs_to :user
+end

data/lib/generators/mixin_bot/authentication/templates/app/models/user.rb.tt

@@ -0,0 +1,12 @@
+class User < ApplicationRecord
+  has_many :sessions, dependent: :destroy
+
+  # Finds or creates the user for an OmniAuth auth hash and refreshes the
+  # stored Mixin profile (name, avatar). The OAuth exchange is used only to
+  # establish identity; credentials are not stored.
+  def self.find_or_create_by_mixin_auth!(auth)
+    user = find_or_create_by!(mixin_user_id: auth.uid)
+    user.update!(name: auth.info.name, avatar_url: auth.info.image)
+    user
+  end
+end

data/lib/generators/mixin_bot/authentication/templates/app/views/sessions/new.html.erb.tt

@@ -0,0 +1,3 @@
+<p style="color: red"><%%= alert %></p>
+
+<%%= button_to "Sign in with Mixin", "/auth/mixin", data: { turbo: false } %>

data/lib/generators/mixin_bot/authentication/templates/config/initializers/omniauth.rb.tt

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "omniauth"
+require "omniauth/strategies/mixin"
+
+Rails.application.config.middleware.use OmniAuth::Builder do
+  provider :mixin,
+           ENV.fetch("MIXIN_CLIENT_ID", nil),
+           ENV.fetch("MIXIN_CLIENT_SECRET", nil),
+           setup: lambda { |env|
+             client_id = ENV["MIXIN_CLIENT_ID"]
+             client_secret = ENV["MIXIN_CLIENT_SECRET"]
+
+             if client_id.blank? || client_secret.blank?
+               raise ArgumentError, "Missing Mixin OAuth credentials: set MIXIN_CLIENT_ID and MIXIN_CLIENT_SECRET"
+             end
+
+             env["omniauth.strategy"].options[:client_id] = client_id
+             env["omniauth.strategy"].options[:client_secret] = client_secret
+           }
+end

data/lib/generators/mixin_bot/blaze/USAGE

@@ -0,0 +1,19 @@
+Description:
+    Adds Mixin Blaze message routing to this Rails application: a routes
+    initializer wired to MixinBot's `blaze_handler`, an example text handler
+    under app/mixin/handlers, and the `mixin_blaze` Puma plugin line in
+    config/puma.rb so messages are received inside the web process tree.
+
+    Requires MixinBot bot credentials (app_id, session_id,
+    session_private_key, server_public_key) to be configured, e.g. from
+    environment variables.
+
+Example:
+    rails generate mixin_bot:blaze
+
+    This will create:
+        config/initializers/mixin_bot_blaze.rb
+        app/mixin/handlers/text_handler.rb
+
+    It will also add `plugin :mixin_blaze` to config/puma.rb (creating it
+    when missing) without duplicating an existing line.

data/lib/generators/mixin_bot/blaze/blaze_generator.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+
+module MixinBot
+  module Generators
+    # `rails generate mixin_bot:blaze` — scaffolds Mixin Blaze message
+    # routing: a routes initializer wired to `config.blaze_handler`, an
+    # example text handler under `app/mixin/handlers`, and the `mixin_blaze`
+    # Puma plugin line in `config/puma.rb` so the app receives messages in
+    # its own process tree.
+    class BlazeGenerator < Rails::Generators::Base
+      source_root File.expand_path('templates', __dir__)
+
+      PUMA_PLUGIN_LINE = 'plugin :mixin_blaze'
+      PUMA_COMMENT = '# Receive Mixin Blaze messages in the web process tree (MixinBot).'
+
+      def create_routes_initializer
+        template 'config/initializers/mixin_bot_blaze.rb'
+      end
+
+      def create_example_handler
+        template 'app/mixin/handlers/text_handler.rb'
+      end
+
+      def configure_puma_plugin
+        if File.exist?(puma_path)
+          return if File.read(puma_path).match?(/^\s*plugin\s+:mixin_blaze\b/)
+
+          append_to_file 'config/puma.rb', "\n#{PUMA_COMMENT}\n#{PUMA_PLUGIN_LINE}\n"
+        else
+          create_file 'config/puma.rb', "#{PUMA_COMMENT}\n#{PUMA_PLUGIN_LINE}\n"
+        end
+      end
+
+      private
+
+      def puma_path
+        File.expand_path('config/puma.rb', destination_root)
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/blaze/templates/app/mixin/handlers/text_handler.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Mixin
+  module Handlers
+    # Example Blaze handler: echoes text messages back to the sender.
+    # Handlers are instantiated per message; `message` exposes decoded data,
+    # conversation/sender ids, and the `reply` helper (HTTP message API).
+    class TextHandler < MixinBot::Blaze::Router::Base
+      def handle
+        reply("You said: #{message.data}")
+      end
+    end
+  end
+end

data/lib/generators/mixin_bot/blaze/templates/config/initializers/mixin_bot_blaze.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# Mixin Blaze message routing.
+#
+# Requires bot credentials in MixinBot.configure (app_id, session_id,
+# session_private_key, server_public_key, spend_key) — typically from
+# environment variables — and the `mixin_blaze` Puma plugin in
+# config/puma.rb to actually receive messages.
+#
+# Routes dispatch decoded envelopes in registration order (first match
+# wins); handlers live under app/mixin/handlers and are re-resolved on
+# every code reload in development.
+
+Rails.application.config.to_prepare do
+  MixinBot.configure do
+    self.blaze_handler = MixinBot::Blaze::Router.new do
+      on 'text', Mixin::Handlers::TextHandler
+      # on 'transfer', Mixin::Handlers::TransferHandler
+      # on category: 'APP_CARD', handler: Mixin::Handlers::AppCardHandler
+      # on action: 'CREATE_MESSAGE', handler: ->(message) { ... }
+    end
+  end
+end