placet-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: db4bfcb4a459bf5fa9fa800a098e9ac53b7270e18c4d6e169188b6aec61f5858
+  data.tar.gz: 5bd4e349f816f0dab05a594330e13b367b0573ba0767f51c085064fdfa6f1cd7
+SHA512:
+  metadata.gz: d1bef0f2695c4ff710efc1769b95e1376f82cb46addb4821181caf2a7aef4bf12f939ecc2ebb87bdf2eb3252de9622b915e74eda9ed5a1b15f49328d39fa913a
+  data.tar.gz: 1e1fd5cabd3b03328dc796df594e2a8ca1fdd68f8c76b64b3137dd56012335f988ea154d9e0b8a236f3a7d635b92eb4b85727039b2fc4309398005d5075c0761

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yugo TERADA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# placet-rails
+
+> placet の Rails アダプタ — 宣言的な per-action 認可と ActiveRecord への scope 合成
+
+[placet](../../README.md) を Rails に統合するアダプタ gem。設計の全体像は [docs/rails-usage.md](../../docs/rails-usage.md) を参照。
+
+## インストール
+
+```ruby
+# Gemfile
+gem "placet-rails"   # placet 本体も依存として入る
+```
+
+## 提供するもの
+
+- **コントローラ統合（PEP ヘルパー）** — `placet_permit`（check / scope の 2 モード、複数 action は AND）、`placet_resource`（RESTful 規約の展開）、`placet_public`（明示オプトアウト）、`placet_verify!`（enforcement 漏れの検知）、`placet_scope` / `placet_permit?` ヘルパー
+- **ActiveRecord への scope 写像** — コアの ScopePlan（empty / all / union ± exclude）を主キーのサブクエリとして `ActiveRecord::Relation` に合成する。返るのは素の Relation なので、ページネーション・ORDER・`count` がそのまま動く
+- **Railtie** — `config/placet/**/*.rb` の定義を起動時にロード（不備は起動エラー）。`rails placet:export` / `rails placet:endpoints` タスク
+
+## 使い方の骨子
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Placet::Rails::Controller
+  placet_verify!
+
+  rescue_from Placet::Denied do |error|
+    Rails.logger.info(error.decision.to_h)  # 根拠は監査ログへ
+    head :forbidden                          # ユーザーには理由を出さない
+  end
+end
+
+class PostsController < ApplicationController
+  before_action :set_post, only: %i[update destroy]
+  placet_resource Post
+  placet_permit "post:publish", only: :publish, resource: -> { @post }
+
+  def index = render(json: placet_scope.order(created_at: :desc).page(params[:page]))
+  def show  = render(json: placet_scope.find(params[:id]))   # 見えなければ 404
+end
+```
+
+## テストの実行
+
+```sh
+cd packages/rails
+bundle install
+for f in test/*_test.rb; do bundle exec ruby -Ilib -Itest "$f"; done
+```

data/lib/placet/rails/active_record_scope.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Placet
+  module Rails
+    # ScopePlan → ActiveRecord::Relation の写像（concept.md 8.4 の集合演算を SQL に落とす）。
+    # relation の scope 同士の構造差（joins の有無など）に依存しないよう、
+    # 和集合・差集合は主キーのサブクエリとして合成する
+    module ActiveRecordScope
+      module_function
+
+      def compose(plan, relations, user, model)
+        return model.none if plan.kind == "empty"
+
+        pk = model.primary_key
+        base =
+          if plan.kind == "all"
+            model.all
+          else
+            Placet.relation_scopes(relations, plan.include_relations, user)
+                  .map { |scope| model.where(pk => scope.select(pk)) }
+                  .reduce { |a, b| a.or(b) }
+          end
+        Placet.relation_scopes(relations, plan.exclude_relations, user)
+              .reduce(base) { |rel, scope| rel.where.not(pk => scope.select(pk)) }
+      end
+    end
+  end
+end
+
+# ActiveRecord モデルに対する ScopePlan の実体化として登録する
+Placet.register_scope_materializer(
+  ->(model) { defined?(ActiveRecord::Base) && model.is_a?(Class) && model <= ActiveRecord::Base },
+  Placet::Rails::ActiveRecordScope.method(:compose)
+)

data/lib/placet/rails/controller.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module Placet
+  module Rails
+    # placet_verify! が enforcement 漏れを検出したときに送出される
+    class VerificationError < Placet::Error; end
+
+    # コントローラ統合（PEP ヘルパー。docs/rails-usage.md Section 4）
+    #
+    #   class ApplicationController < ActionController::Base
+    #     include Placet::Rails::Controller
+    #     placet_verify!
+    #   end
+    #
+    #   class PostsController < ApplicationController
+    #     before_action :set_post, only: %i[update destroy]
+    #     placet_resource Post
+    #     placet_permit "post:publish", only: :publish, resource: -> { @post }
+    #   end
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :placet_declarations, default: {}, instance_writer: false
+        class_attribute :placet_public_actions, default: [], instance_writer: false
+        class_attribute :placet_verify_enabled, default: false, instance_writer: false
+        class_attribute :placet_enforcer_installed, default: false, instance_writer: false
+        helper_method :placet_permit?, :placet_user if respond_to?(:helper_method)
+      end
+
+      class_methods do
+        # action ごとの権限宣言。
+        # via: :check  — before_action として authorize! を実行（403）
+        # via: :scope  — placet_scope で合成済みコレクションを取得（絞り込み / 404）
+        # 複数 action は AND。via: :scope は単一 action のみ（docs/rails-usage.md 4.2）
+        def placet_permit(actions, only:, via: :check, resource: nil, model: nil)
+          actions = Array(actions).map(&:to_s)
+          if via == :scope && actions.size > 1
+            raise Placet::DefinitionError, "via: :scope の宣言は単一 action のみ: #{actions.inspect}"
+          end
+
+          # typo は「静かな全拒否 / 空 scope」になるため宣言時に検査する（検証規則はコアに一元化）
+          actions.each { |action| Placet.validate_action!(action, error_class: Placet::DefinitionError) }
+
+          declaration = { actions: actions, via: via, resource: resource, model: model }
+          if via == :scope && model.nil?
+            # 規約推論（resource セグメント → モデル名）は宣言時に解決しておく。
+            # リロードと相性を保つため、クラス参照ではなく名前文字列を保持する
+            declaration[:model_name] = actions.first.split(":", 2).first.camelize
+          end
+
+          merged = Array(only).map(&:to_s).to_h { |name| [name, (placet_declarations[name] || []) + [declaration]] }
+          self.placet_declarations = placet_declarations.merge(merged)
+
+          install_placet_enforcer if via == :check
+        end
+
+        # RESTful CRUD の規約展開（docs/rails-usage.md 4.1）。
+        # index/show → <resource>:view (scope)、create/update/destroy → check。
+        # リソースのロードは肩代わりしない: update/destroy は @<resource> を参照する
+        def placet_resource(model)
+          name = model.name.underscore
+          ref = -> { instance_variable_get(:"@#{name}") }
+          placet_permit "#{name}:view",   only: %i[index show], via: :scope, model: model
+          placet_permit "#{name}:create", only: :create
+          placet_permit "#{name}:update", only: :update,  resource: ref
+          placet_permit "#{name}:delete", only: :destroy, resource: ref
+        end
+
+        # 認可不要のエンドポイントを明示的にオプトアウトする（verify の対象から外す唯一の方法）
+        def placet_public(only:)
+          self.placet_public_actions = placet_public_actions + Array(only).map(&:to_s)
+        end
+
+        # enforcement（authorize! / scoped）が一度も行われずにアクションが終わったら raise。
+        # development / test で必ず有効化することを推奨（docs/rails-usage.md 4.4）
+        def placet_verify!
+          return if placet_verify_enabled
+
+          self.placet_verify_enabled = true
+          prepend_before_action { @_placet_enforcements_before = Placet.enforcements }
+          after_action :placet_verify_enforcement!
+        end
+
+        private
+
+        # check モードの enforcement は、宣言ハッシュを唯一の真実として 1 本の
+        # before_action で行う（endpoints タスク・verify と同じデータを見る）。
+        # 最初の check 宣言の位置で登録されるため、リソースをロードする
+        # before_action はそれより前に宣言しておくこと
+        def install_placet_enforcer
+          return if placet_enforcer_installed
+
+          self.placet_enforcer_installed = true
+          before_action :placet_enforce!
+        end
+      end
+
+      # アプリ側で上書き可能。既定は current_user
+      def placet_user = current_user
+
+      # via: :scope の宣言から合成済みコレクション（AR なら Relation）を返す
+      def placet_scope(model = nil)
+        declaration = placet_scope_declaration!
+        target = model || declaration[:model] || declaration[:model_name].constantize
+        Placet.scoped(placet_user, declaration[:actions].first, model: target)
+      end
+
+      # 表示制御用。enforcement にはカウントされない
+      def placet_permit?(actions, resource = nil) = Placet.permit?(placet_user, actions, resource)
+
+      # 二段構えの再チェック（docs/rails-usage.md Section 6）。scope で絞った結果
+      # （通常は 1 ページ分）へ個体判定を再適用し、check / scope の乖離があっても
+      # 見えてはいけないレコードを返さない。action 省略時は scope 宣言から引き継ぐ
+      def placet_recheck(records, action: nil)
+        action ||= placet_scope_declaration![:actions].first
+        Placet.recheck(placet_user, action, records)
+      end
+
+      private
+
+      def placet_scope_declaration!
+        (placet_declarations[action_name] || []).find { |d| d[:via] == :scope } ||
+          raise(Placet::Error, "#{self.class.name}##{action_name} に via: :scope の宣言がない")
+      end
+
+      def placet_enforce!
+        (placet_declarations[action_name] || []).each do |declaration|
+          next unless declaration[:via] == :check
+
+          target = declaration[:resource] && instance_exec(&declaration[:resource])
+          Placet.authorize!(placet_user, declaration[:actions], target)
+        end
+      end
+
+      def placet_verify_enforcement!
+        return if placet_public_actions.include?(action_name)
+        return if Placet.enforcements > (@_placet_enforcements_before || 0)
+
+        raise VerificationError,
+              "#{self.class.name}##{action_name} で認可が行われていない。" \
+              "placet_permit / placet_resource で宣言するか、placet_scope / Placet.authorize! を呼ぶか、" \
+              "認可不要なら placet_public で明示すること"
+      end
+    end
+  end
+end

data/lib/placet/rails/railtie.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Placet
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.placet = ActiveSupport::OrderedOptions.new
+
+      # config/placet/**/*.rb（1 ファイル 1 ポリシー + actions.rb 等）を起動時にロードする。
+      # 定義の不備は DefinitionError となり、起動が失敗する（fail fast）
+      initializer "placet.load_definitions", after: :load_config_initializers do |app|
+        paths = app.config.placet.definition_paths ||
+                [app.root.join("config", "placet", "**", "*.rb").to_s]
+        paths.flat_map { |pattern| Dir[pattern.to_s].sort }.each { |file| load file }
+      end
+
+      # 再チェック（Placet.recheck / placet_recheck）で乖離を検出したときの既定通知
+      initializer "placet.recheck_divergence_logging" do
+        Placet.on_recheck_divergence ||= lambda do |_user, action, record|
+          ::Rails.logger.warn(
+            "placet: scope と check の乖離を検出 action=#{action} " \
+            "record=#{record.class}##{record.respond_to?(:id) ? record.id : record.inspect}"
+          )
+        end
+      end
+
+      rake_tasks do
+        load File.expand_path("../../tasks/placet.rake", __dir__)
+      end
+    end
+  end
+end

data/lib/placet/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Placet
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/placet/rails.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require "placet"
+require_relative "rails/version"
+require_relative "rails/controller"
+require_relative "rails/active_record_scope"
+require_relative "rails/railtie" if defined?(::Rails::Railtie)

data/lib/placet-rails.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "placet/rails"

data/lib/tasks/placet.rake

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+namespace :placet do
+  desc "コンパイル済みの正規形（canonical form）を JSON で出力する"
+  task export: :environment do
+    require "json"
+    puts JSON.pretty_generate(Placet.export)
+  end
+
+  desc "principal の実効権限、または principal 集合 × action の決定根拠を表示する"
+  task :explain, %i[subject action] => :environment do |_t, args|
+    subject = args[:subject].to_s.strip
+    action = args[:action].to_s.strip
+    if subject.empty?
+      abort 'usage: rails "placet:explain[tenant:acme]" / ' \
+            'rails "placet:explain[role:editor flag:suspended, post:update]"'
+    end
+
+    principals = subject.split(/\s+/)
+    if action.empty?
+      abort "principal の説明は 1 つずつ指定してください" if principals.size > 1
+      puts Placet::Explain.principal_report(principals.first)
+    else
+      puts Placet::Explain.decision_report(principals, action)
+    end
+  end
+
+  desc "コントローラの宣言から エンドポイント → 必要権限 の一覧を出力する"
+  task endpoints: :environment do
+    Rails.application.eager_load!
+    controllers = ActionController::Base.descendants
+                                        .select { |c| c.respond_to?(:placet_declarations) }
+                                        .sort_by(&:name)
+    controllers.each do |controller|
+      controller.placet_declarations.sort.each do |action_name, declarations|
+        declarations.each do |decl|
+          mode = decl[:via] == :scope ? "(scoped)" : "(403)"
+          puts format("%-40s %-30s %s", "#{controller.name}##{action_name}", decl[:actions].join(" AND "), mode)
+        end
+      end
+      controller.placet_public_actions.each do |action_name|
+        puts format("%-40s %-30s %s", "#{controller.name}##{action_name}", "-", "(public)")
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: placet-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yugo TERADA
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: placet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: 'placet-rails integrates the placet authorization library with Rails:
+  per-action permission declarations (placet_permit / placet_resource), an enforcement
+  verification hook, and mapping of placet scope plans onto ActiveRecord relations
+  for list filtering.'
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/placet-rails.rb
+- lib/placet/rails.rb
+- lib/placet/rails/active_record_scope.rb
+- lib/placet/rails/controller.rb
+- lib/placet/rails/railtie.rb
+- lib/placet/rails/version.rb
+- lib/tasks/placet.rake
+homepage: https://github.com/aspick/placet
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/aspick/placet
+  source_code_uri: https://github.com/aspick/placet
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.18
+signing_key:
+specification_version: 4
+summary: Rails adapter for placet — declarative per-action authorization and ActiveRecord
+  scope composition
+test_files: []