acting_for 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 416659519f04a4cf5f2639684e6078fe51766cf1eb727ac7b9cde851207d4f9e
+  data.tar.gz: b976be543b26602045c4f0db0152bbf5e051c028c54f18f70e2aae335f702a9e
+SHA512:
+  metadata.gz: 5173d14fb39328a07f28957a365a4dbafe845f8dfbc4b2a73045f57f2c69a40ba6f96de9306b21a77d7b16d9cd10b6f136e93567f771bb5c0df0df082f4f11b3
+  data.tar.gz: 31cb9911b3a8efa9d4a6e54a5c30fb4eff45f15e0f54a1007391727959d37b10503e8da45ff994cd26389d345d51e26651fa3fdc0f46c490f9ae503c91fb2bab

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChangQuan Cui
+
+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,475 @@
+# ActingFor
+
+**Add delegated authorization behind MCP tools and other agent-driven Rails actions.**
+
+*Rails-native delegated authorization for AI agents.*
+
+MCP can give AI clients a standard way to discover and call tools exposed by your Rails application.
+
+ActingFor answers the next question:
+
+> **Should this Agent be allowed to perform this Action on behalf of this Principal?**
+
+AI AgentがPrincipalの代理として何をしてよいかを、委任された権限に基づいて制御するRails向け認可Gemです。
+
+## Status
+
+> **Implemented and CI verified; Not released.** The Public API, migrations, models, constraints, automatic Audit persistence, and formal test suite are implemented. CI covers Ruby 3.4 / 4.0, Rails 8.0 / 8.1, and PostgreSQL 16. The runnable setup was verified in a new Rails application in [D230](docs/DECISIONS.md#d230-runnable-quick-start-implementation). ActingFor has not been published to RubyGems.
+
+## Why ActingFor?
+
+Traditional Rails authorization usually answers:
+
+> **May this user perform this action?**
+
+Once an AI Agent can act through MCP, an API, or another integration, the application also needs to answer:
+
+> **May this Agent perform this action on behalf of this user?**
+
+For example, an MCP server might expose tools such as:
+
+```text
+search_products
+purchase_product
+cancel_order
+```
+
+Making those tools callable is only part of the problem. Before Rails executes `purchase_product`, it may still need to know:
+
+```text
+Which Agent is acting?
+For which Principal?
+Was :purchase delegated?
+Is ¥8,900 within the delegated limit?
+Has the Delegation expired or been revoked?
+Is human approval required?
+```
+
+That is the layer ActingFor provides.
+
+## MCP + ActingFor in one picture
+
+```text
+ChatGPT / Claude / AI Agent
+            │
+            │ MCP, API, or another integration
+            ▼
+      Rails Host Application
+            │
+            │ "purchase_product"
+            ▼
+         ActingFor
+            │
+            ├─ Which Agent?
+            ├─ Acting for whom?
+            ├─ Was :purchase delegated?
+            ├─ Do constraints pass?
+            ├─ Is the Delegation active?
+            └─ Is approval required?
+            │
+            ▼
+   allow / require_approval / deny
+            │
+            ▼
+     Rails Business Logic
+```
+
+**MCP gives Agents a way to interact with your Rails application. ActingFor adds delegated authorization behind that interaction.**
+
+ActingFor does not require MCP, and it does not replace MCP. The same authorization layer can sit behind REST APIs, background jobs, internal Agent workflows, or other interfaces.
+
+## What does ActingFor do?
+
+ActingFor answers a focused question: may this authenticated Agent perform this Action on behalf of this Principal, for this Resource and trusted Context?
+
+- **Principal**: the party on whose behalf an Agent acts.
+- **Agent**: the separate actor requesting an Action.
+- **Delegation**: authority and constraints granted by the Principal.
+- **Decision**: `allow`, `deny`, or `require_approval`.
+
+The Principal and Agent are always separate actors. ActingFor evaluates their Delegation; it does not authenticate the Agent or execute the business operation.
+
+## MCP vs ActingFor
+
+| | MCP | ActingFor |
+| --- | --- | --- |
+| Main role | Connect AI clients to application capabilities | Decide what an Agent may do for a Principal |
+| Example | Call `purchase_product` | Decide whether that Agent may purchase |
+| Agent authentication | May participate through the surrounding auth flow | Not provided by ActingFor |
+| Delegation | Not ActingFor-style delegated authority | Core responsibility |
+| Constraints / expiry / revocation | Not ActingFor's role | Core responsibility |
+| Authorization audit | Not ActingFor's role | Automatic AuditEvent persistence |
+
+MCP tool names and ActingFor Actions are different concepts. An adapter or host layer may translate an MCP tool call into `agent`, `principal`, `action`, `resource`, and trusted `context`.
+
+See the [formal responsibility boundary](docs/PROJECT.md#21-actingforとmcpの正式な責務境界).
+
+## Delegated purchase example
+
+A Principal can give an Agent only part of their authority:
+
+```text
+User A
+ │
+ │ delegates
+ ▼
+Shopping Agent
+ │
+ ├─ search_products       allowed by the host as appropriate
+ ├─ purchase <= ¥10,000   delegated
+ ├─ purchase > ¥10,000    not covered by this Delegation
+ └─ delete_account        not delegated
+```
+
+At runtime:
+
+```text
+Principal (User)
+ │ delegates a constrained :purchase
+ ▼
+Shopping Agent
+ │ requests a purchase
+ ▼
+Rails Host Application
+ │ authenticates the Agent, resolves the Principal,
+ │ loads the Product, and establishes trusted Context
+ ▼
+ActingFor.authorize(...)
+ │ evaluates Delegation, constraints, expiry, and revocation
+ │ saves an AuditEvent automatically
+ ▼
+allow / require_approval / deny
+ │
+ ▼
+Rails Host Application enforces the Decision
+```
+
+## 30-second example
+
+The host has already authenticated an external caller, resolved it to the local `shopping_agent`, resolved `user`, and loaded `product`:
+
+```ruby
+ActingFor.delegate(
+  agent: shopping_agent,
+  principal: user,
+  action: :purchase,
+  resource: Product,
+  constraints: [
+    { field: "amount", operator: "lte", value: 10_000 }
+  ],
+  effect: :allow
+)
+
+decision = ActingFor.authorize(
+  agent: shopping_agent,
+  principal: user,
+  action: :purchase,
+  resource: product,
+  context: { amount: product.price }
+)
+
+decision.allowed? # => true when product.price is 8_900
+```
+
+Both calls use the implemented [v0.1 Public API](docs/public_api_v0_1.md). Context values that affect authorization must be established by the host, not trusted directly from an Agent request.
+
+## Quick Start
+
+ActingFor is not yet published to RubyGems. This pre-release setup installs the public GitHub `main` branch.
+
+1. Add the Gem and install dependencies:
+
+   ```ruby
+   gem "acting_for", github: "cuichangquan/acting_for", branch: "main"
+   # Rails 8.0 uses JSON options removed in JSON 3.
+   gem "json", "< 3"
+   ```
+
+   ```sh
+   bundle install
+   ```
+
+2. Install migrations:
+
+   ```sh
+   bin/rails acting_for:install:migrations
+   bin/rails db:migrate
+   ```
+
+3. In `bin/rails console`, create the local Agent:
+
+   ```ruby
+   shopping_agent = ActingFor::Agent.create!(
+     identifier: "shopping-agent",
+     name: "Shopping Agent"
+   )
+   ```
+
+4. Create a Delegation:
+
+   ```ruby
+   ActingFor.delegate(
+     agent: shopping_agent,
+     principal: user,
+     action: :purchase,
+     resource: Product,
+     constraints: [
+       { field: "amount", operator: "lte", value: 10_000 }
+     ],
+     effect: :allow
+   )
+   ```
+
+5. Authorize with host-verified Context:
+
+   ```ruby
+   product = Product.find_by!(price: 8_900)
+   decision = ActingFor.authorize(
+     agent: shopping_agent,
+     principal: user,
+     action: :purchase,
+     resource: product,
+     context: { amount: product.price }
+   )
+   ```
+
+6. Check the Decision before the host performs any operation:
+
+   ```ruby
+   [decision.status, decision.allowed?, decision.denied?, decision.approval_required?]
+   # => [:allow, true, false, false]
+   ```
+
+For the complete runnable setup—including a new Rails application, public GitHub pre-release installation, host models, all three `¥8,900 / ¥20,000 / ¥50,000` outcomes, Audit behavior, and production security guidance—see [Getting Started](docs/getting_started.md).
+
+## How does an external AI Agent reach ActingFor?
+
+ActingFor starts **after** the Rails Host Application knows which Agent is making the request.
+
+An external caller such as ChatGPT, Claude, an MCP client, or a custom Agent must first be authenticated or otherwise reliably identified by the host application. The host then resolves that external identity to a local `ActingFor::Agent`.
+
+```text
+External AI Agent
+(ChatGPT / Claude / MCP Client / custom Agent)
+        │
+        │ OAuth token / JWT / API credential /
+        │ another trusted authentication mechanism
+        ▼
+Rails Host Application
+        │
+        ├─ 1. Authenticate or identify the external Agent
+        ├─ 2. Resolve it to an ActingFor::Agent
+        ├─ 3. Resolve the Principal
+        ├─ 4. Load the Resource and trusted Context
+        ▼
+ActingFor.authorize(...)
+        │
+        ├─ Delegation
+        ├─ Constraints
+        ├─ Expiration
+        └─ Revocation
+        ▼
+allow / require_approval / deny
+```
+
+**Authentication answers “Which Agent is this?” ActingFor answers “What may this Agent do on behalf of this Principal?”**
+
+### Agent and User are different records
+
+An Agent does not need a second record in the host application's `users` table.
+
+```text
+users
+└─ User A                         ← Principal
+
+acting_for_agents
+└─ Shopping Agent                ← Agent
+
+acting_for_delegations
+└─ User A → Shopping Agent → purchase
+```
+
+Conceptually:
+
+```ruby
+user
+# => #<User id: 1>
+
+shopping_agent
+# => #<ActingFor::Agent id: 10>
+```
+
+The host may call these values `current_user` and `current_agent`, but ActingFor does not provide a `current_agent` authentication helper. Agent authentication and external-identity resolution belong to the host application.
+
+### Responsibility split
+
+| Question | Responsibility |
+| --- | --- |
+| Which external Agent sent this request? | Host application / authentication layer |
+| Which `ActingFor::Agent` does that identity map to? | Host application |
+| Which Principal is the Agent acting for? | Host application + Delegation relationship |
+| May this Agent perform `purchase` for that Principal? | ActingFor |
+| Do amount, expiry, and revocation constraints pass? | ActingFor |
+| Should the business operation actually run? | Host application |
+
+### Do I need Agent Authentication before installing ActingFor?
+
+No. ActingFor can be installed independently.
+
+However, if an external AI Agent will call the Rails application directly, the host must authenticate or otherwise reliably identify that Agent and resolve it to an `ActingFor::Agent` before calling `ActingFor.authorize(...)`.
+
+If the application already knows the Agent through an internal trusted workflow, ActingFor can be used without adding an external Agent authentication system first.
+
+### Example Rails stack: Devise + Doorkeeper + MCP + ActingFor
+
+A Rails application can combine familiar components without making ActingFor responsible for authentication or MCP transport.
+
+> **This is one possible Rails integration, not a required ActingFor stack.**
+
+```text
+Human User
+    │
+    │ Devise
+    │ authenticate the human
+    ▼
+Rails Host Application
+    │
+    │ Doorkeeper / OAuth
+    │ issue and validate access tokens
+    ▼
+MCP Client / AI Agent
+    │
+    │ MCP tool call
+    │ purchase_product(product_id)
+    ▼
+Rails MCP endpoint
+    │
+    ├─ validate the surrounding authentication / OAuth context
+    ├─ resolve the external identity to an ActingFor::Agent
+    ├─ resolve the Principal
+    ├─ load the Resource
+    └─ establish trusted Context
+    ▼
+ActingFor.authorize(...)
+    │
+    ├─ Was :purchase delegated?
+    ├─ Do constraints pass?
+    ├─ Is the Delegation active?
+    └─ Is approval required?
+    ▼
+allow / require_approval / deny
+    │
+    ▼
+Rails Business Logic
+```
+
+The responsibilities remain separate:
+
+| Component | Example responsibility |
+| --- | --- |
+| Devise | Authenticate the human User / Principal |
+| Doorkeeper | Provide OAuth authorization and access-token handling for the Rails application |
+| MCP | Expose Rails capabilities such as `purchase_product` to AI clients |
+| Rails host application | Validate the caller context, resolve Agent + Principal, load trusted business data, and enforce the Decision |
+| ActingFor | Decide what the resolved Agent may do on behalf of the resolved Principal |
+
+The important boundary is that **MCP makes a capability callable, while ActingFor decides whether the resolved Agent may use that capability for this Principal**.
+
+An illustrative host-side mapping might look like:
+
+```ruby
+oauth_application = doorkeeper_token.application
+user = User.find(doorkeeper_token.resource_owner_id)
+
+shopping_agent = ActingFor::Agent.find_by!(
+  identifier: oauth_application.uid
+)
+
+decision = ActingFor.authorize(
+  agent: shopping_agent,
+  principal: user,
+  action: :purchase,
+  resource: product,
+  context: { amount: product.price }
+)
+```
+
+This example is intentionally simplified. A Doorkeeper application or OAuth client is **not necessarily identical to one AI Agent instance**. For example, one MCP client may front multiple logical Agents. Production applications may therefore need an explicit identity-mapping layer:
+
+```text
+Authenticated OAuth / MCP identity
+            ↓
+Rails identity mapping
+            ↓
+ActingFor::Agent
+            ↓
+Principal + Delegation
+            ↓
+ActingFor.authorize(...)
+```
+
+ActingFor does not require Devise, Doorkeeper, or MCP. Existing applications may use another authentication provider, OAuth/OIDC service, API credential, transport, or trusted internal workflow as long as the host can reliably establish the Agent and Principal before calling ActingFor.
+
+## Security / Responsibility Boundary
+
+```text
+Host Authorization
+       AND
+ActingFor Authorization
+       ↓
+Business Logic
+```
+
+The host must authenticate the Agent, resolve the Principal, check the Principal's current permissions, provide trusted Context, enforce the returned Decision, and execute the business operation. ActingFor does not call host authorization libraries directly.
+
+Important parts of the security contract:
+
+- Agent and Principal are separate actors. ActingFor does not authenticate Agents or provide login/session management.
+- `require_approval != allow`; approval-required operations must not execute automatically.
+- `ActingFor::Decision` describes the result at authorization time. It is not a reusable authorization token or capability.
+- Authorize close to the protected operation. Do not reuse cached Decisions or cached Delegations as authorization proof.
+- ActingFor automatically persists an AuditEvent inside `authorize`. If Audit persistence fails, no Decision is returned and the host must not proceed.
+- ActingFor does not execute business operations or guarantee atomicity with them. The host owns transaction, concurrency, retry, and TOCTOU handling.
+
+See the [Getting Started security guidance](docs/getting_started.md#security-and-responsibility-boundary) and formal [Security Model](docs/security_model_v0_1.md).
+
+## What ActingFor is not
+
+ActingFor is not an authentication provider, OAuth/OIDC server, Agent framework, MCP server, approval workflow, payment system, or general-purpose policy engine. It does not fetch or validate business data, provision external Agents, or perform the authorized operation.
+
+## Official Demo
+
+[ActingFor Demo](https://github.com/cuichangquan/acting_for_demo) is the official real Rails host application. It demonstrates Public API integration, automated host-integration verification, and a workflow for human manual verification. The gem repository remains the source of truth for gem behavior, the Public API, and the Security Contract; the demo verifies those public boundaries without depending on `ActingFor::Internal::*`.
+
+## Documentation
+
+Project documents are maintained primarily in Japanese:
+
+- [Getting Started](docs/getting_started.md)
+- [Current State](docs/CURRENT_STATE.md)
+- [Progress](docs/PROGRESS.md)
+- [Project scope, roadmap, and terminology](docs/PROJECT.md)
+- [Decisions and rationale](docs/DECISIONS.md)
+- [v0.1 Public API](docs/public_api_v0_1.md)
+- [v0.1 Security Model](docs/security_model_v0_1.md)
+- [v0.1 Domain Model](docs/domain_model_v0_1.md)
+- [v0.1 Gem Structure](docs/gem_structure_v0_1.md)
+- [v0.1 Test Strategy](docs/test_strategy_v0_1.md)
+- [GitHub Issues](https://github.com/cuichangquan/acting_for/issues)
+
+## Supported Versions
+
+The formal GitHub Actions matrix verifies PostgreSQL 16 with:
+
+| Ruby | Rails |
+| --- | --- |
+| 3.4 | 8.0 |
+| 3.4 | 8.1 |
+| 4.0 | 8.0 |
+| 4.0 | 8.1 |
+
+Other database adapters are outside v0.1 official support. Formal Minitest and core RuboCop are CI gates. See the [support policy](docs/PROJECT.md#46-対応環境公開方針d045d048).
+
+## License
+
+ActingFor is available under the [MIT License](LICENSE).

data/app/models/acting_for/agent.rb

@@ -0,0 +1,29 @@
+module ActingFor
+  class Agent < ApplicationRecord
+    has_many :delegations,
+             class_name: "ActingFor::Delegation",
+             dependent: :restrict_with_exception
+
+    validates :identifier, uniqueness: { case_sensitive: true }
+    validate :identifier_format
+    validate :name_format
+
+    private
+
+    def identifier_format
+      value = read_attribute_before_type_cast(:identifier)
+      return if value.is_a?(String) && value.length.between?(1, 255) && !value.match?(/[[:space:]]/)
+
+      errors.add(:identifier, "must be a String of 1..255 characters without whitespace")
+    end
+
+    def name_format
+      value = read_attribute_before_type_cast(:name)
+      return if value.nil?
+
+      return if value.is_a?(String) && value.length.between?(1, 255) && !value.blank?
+
+      errors.add(:name, "must be a nonblank String of 1..255 characters")
+    end
+  end
+end

data/app/models/acting_for/application_record.rb

@@ -0,0 +1,5 @@
+module ActingFor
+  class ApplicationRecord < ActiveRecord::Base
+    self.abstract_class = true
+  end
+end

data/app/models/acting_for/audit_event.rb

@@ -0,0 +1,50 @@
+module ActingFor
+  class AuditEvent < ApplicationRecord
+    DECISION_REASONS = {
+      "allow" => "delegation_allowed",
+      "require_approval" => "delegation_requires_approval",
+      "deny" => "no_matching_delegation"
+    }.freeze
+
+    validates :agent_id, :agent_identifier, :principal_type, :principal_id,
+              :action, :decision, :reason_code, presence: true
+    validates :decision, inclusion: { in: DECISION_REASONS.keys }
+    validates :reason_code, inclusion: { in: DECISION_REASONS.values }
+    validate :decision_reason_pair
+    validate :resource_scope
+    validate :matched_delegations
+    validate :context_format
+
+    def readonly?
+      persisted? || super
+    end
+
+    private
+
+    def decision_reason_pair
+      errors.add(:reason_code, "does not match decision") unless DECISION_REASONS[decision] == reason_code
+    end
+
+    def resource_scope
+      errors.add(:resource_type, "is required when resource_id is set") if resource_type.nil? && !resource_id.nil?
+    end
+
+    def matched_delegations
+      ids = matched_delegation_ids
+      unless ids.is_a?(Array) && ids.all?(Integer) && ids.uniq.length == ids.length
+        errors.add(:matched_delegation_ids, "must be an Array of unique Integers")
+        return
+      end
+
+      if decision == "deny" && !ids.empty?
+        errors.add(:matched_delegation_ids, "must be empty for deny")
+      elsif %w[allow require_approval].include?(decision) && ids.empty?
+        errors.add(:matched_delegation_ids, "must not be empty for allow or require_approval")
+      end
+    end
+
+    def context_format
+      errors.add(:sanitized_context, "must be a Hash") unless sanitized_context.is_a?(Hash)
+    end
+  end
+end

data/app/models/acting_for/delegation.rb

@@ -0,0 +1,74 @@
+module ActingFor
+  class Delegation < ApplicationRecord
+    IMMUTABLE_ATTRIBUTES = %w[
+      agent_id principal_type principal_id action resource_type resource_id
+      constraints effect expires_at revoked_at
+    ].freeze
+    CONSTRAINT_KEYS = %w[field operator value].freeze
+
+    belongs_to :agent, class_name: "ActingFor::Agent"
+    belongs_to :principal, polymorphic: true
+
+    validates :agent, :principal, :action, :effect, presence: true
+    validates :effect, inclusion: { in: %w[allow require_approval] }
+    validate :resource_scope
+    validate :canonical_constraints
+    validate :initial_timestamps, on: :create
+    validate :immutable_attributes, on: :update
+
+    def revoke!
+      raise ActiveRecord::RecordNotSaved.new("Cannot revoke an unsaved delegation", self) unless persisted?
+
+      time = ActingFor.current_time
+      self.class.where(id: id, revoked_at: nil).update_all(revoked_at: time, updated_at: time)
+      reload
+    end
+
+    private
+
+    def resource_scope
+      errors.add(:resource_type, "is required when resource_id is set") if resource_type.nil? && !resource_id.nil?
+    end
+
+    def initial_timestamps
+      errors.add(:expires_at, "must be in the future") if expires_at && expires_at <= ActingFor.current_time
+      errors.add(:revoked_at, "must be nil on creation") unless revoked_at.nil?
+    end
+
+    def immutable_attributes
+      IMMUTABLE_ATTRIBUTES.each do |attribute|
+        errors.add(attribute, "cannot be changed") if will_save_change_to_attribute?(attribute)
+      end
+    end
+
+    def canonical_constraints
+      # JSON casting stringifies Hash keys; also check the original assigned value.
+      values = [constraints]
+      values << read_attribute_before_type_cast(:constraints) if constraints_came_from_user?
+      return if values.all? { |value| value.is_a?(Array) && value.all? { |entry| canonical_constraint?(entry) } }
+
+      errors.add(:constraints, "must be an Array of canonical constraints")
+    end
+
+    def canonical_constraint?(entry)
+      return false unless entry.is_a?(Hash) && entry.keys.size == 3 && (CONSTRAINT_KEYS - entry.keys).empty?
+      return false unless entry["field"].is_a?(String) && !entry["field"].empty?
+
+      value = entry["value"]
+      case entry["operator"]
+      when "eq"
+        scalar_constraint_value?(value)
+      when "lt", "lte", "gt", "gte"
+        value.is_a?(Integer)
+      when "in"
+        value.is_a?(Array) && value.all? { |element| scalar_constraint_value?(element) }
+      else
+        false
+      end
+    end
+
+    def scalar_constraint_value?(value)
+      value.is_a?(String) || value.is_a?(Integer) || value.is_a?(TrueClass) || value.is_a?(FalseClass)
+    end
+  end
+end

data/app/services/acting_for/internal/authorization.rb

@@ -0,0 +1,175 @@
+require "bigdecimal"
+
+module ActingFor
+  module Internal
+    class Authorization
+      FORBIDDEN_AUDIT_CONTEXT_KEYS = %i[
+        password password_confirmation token access_token refresh_token
+        api_key secret client_secret credential
+      ].freeze
+      private_constant :FORBIDDEN_AUDIT_CONTEXT_KEYS
+
+      class << self
+        def call(agent:, principal:, action:, resource:, context:, audit_context_keys:)
+          unless agent.is_a?(ActingFor::Agent) && agent.persisted?
+            raise InvalidRequestError, "agent must be a persisted ActingFor::Agent"
+          end
+          unless principal.is_a?(ActiveRecord::Base) && principal.persisted?
+            raise InvalidRequestError, "principal must be a persisted ActiveRecord record"
+          end
+
+          action = string_value(action, "action")
+          raise InvalidRequestError, "action must not be blank" if action.blank?
+
+          resource_type, resource_id = resource_identity(resource)
+          raise InvalidRequestError, "context must be a Hash" unless context.is_a?(Hash)
+
+          audit_context = sanitized_context(context, audit_context_keys)
+
+          matches = candidate_delegations(
+            agent: agent,
+            principal: principal,
+            action: action,
+            resource_type: resource_type
+          ).select do |delegation|
+            resource_matches?(delegation, resource_type, resource_id) &&
+              ConstraintEvaluator.call(constraints: delegation.constraints, context: context)
+          end
+
+          decision = ActingFor::Decision.new(decision_status(matches))
+          audit_attributes = audit_event_attributes(
+            agent: agent,
+            principal: principal,
+            action: action,
+            resource_type: resource_type,
+            resource_id: resource_id,
+            decision: decision,
+            matches: matches,
+            sanitized_context: audit_context
+          )
+          persist_audit_event!(audit_attributes)
+
+          decision
+        end
+
+        private
+
+        def string_value(value, name)
+          return value if value.is_a?(String)
+          return value.to_s if value.is_a?(Symbol)
+
+          raise InvalidRequestError, "#{name} must be a String or Symbol"
+        end
+
+        def resource_identity(resource)
+          return [nil, nil] if resource.nil?
+
+          klass = resource.is_a?(Class) ? resource : resource.class
+          raise InvalidRequestError, "resource class must provide model_name" unless klass.respond_to?(:model_name)
+
+          model_name = klass.model_name
+          raise InvalidRequestError, "resource model_name must provide name" unless model_name.respond_to?(:name)
+
+          resource_type = model_name.name
+          return [resource_type, nil] if resource.is_a?(Class)
+
+          raise InvalidRequestError, "resource instance must provide id" unless resource.respond_to?(:id)
+
+          id = resource.id
+          raise InvalidRequestError, "resource id must not be nil" if id.nil?
+
+          resource_id = id.to_s
+          raise InvalidRequestError, "resource id must not be empty" if resource_id.empty?
+
+          [resource_type, resource_id]
+        end
+
+        def sanitized_context(context, audit_context_keys)
+          unless audit_context_keys.is_a?(Array) &&
+                 audit_context_keys.all?(Symbol)
+            raise InvalidRequestError, "audit_context_keys must be an Array of Symbols"
+          end
+
+          keys = audit_context_keys.uniq
+          forbidden_key = keys.find { |key| FORBIDDEN_AUDIT_CONTEXT_KEYS.include?(key) }
+          raise InvalidRequestError, "audit_context_keys contains forbidden key: #{forbidden_key}" if forbidden_key
+
+          keys.each_with_object({}) do |key, sanitized|
+            next unless exact_symbol_key?(context, key)
+
+            sanitized[key.to_s] = sanitized_audit_value(context[key], key)
+          end
+        end
+
+        def exact_symbol_key?(context, key)
+          context.each_key.any? { |existing_key| existing_key.is_a?(Symbol) && existing_key == key }
+        end
+
+        def sanitized_audit_value(value, key)
+          return value.to_s("F") if value.is_a?(BigDecimal)
+          return value if value.nil? ||
+                          value.is_a?(String) ||
+                          value.is_a?(Integer) ||
+                          value.is_a?(Float) ||
+                          value.is_a?(TrueClass) ||
+                          value.is_a?(FalseClass)
+
+          raise InvalidRequestError, "unsupported audit context value for #{key}"
+        end
+
+        def candidate_delegations(agent:, principal:, action:, resource_type:)
+          ActingFor::Delegation
+            .where(
+              agent: agent,
+              principal: principal,
+              action: action,
+              resource_type: resource_type,
+              revoked_at: nil
+            )
+            .where("expires_at IS NULL OR expires_at > ?", ActingFor.current_time)
+        end
+
+        def resource_matches?(delegation, resource_type, resource_id)
+          return delegation.resource_id.nil? && resource_id.nil? if resource_type.nil?
+          return false unless delegation.resource_type == resource_type
+          return delegation.resource_id.nil? if resource_id.nil?
+
+          delegation.resource_id.nil? || delegation.resource_id == resource_id
+        end
+
+        def decision_status(matches)
+          return :require_approval if matches.any? { |delegation| delegation.effect == "require_approval" }
+          return :allow if matches.any? { |delegation| delegation.effect == "allow" }
+
+          :deny
+        end
+
+        def audit_event_attributes(
+          agent:, principal:, action:, resource_type:, resource_id:, decision:, matches:, sanitized_context:
+        )
+          decision_value = decision.status.to_s
+
+          {
+            agent_id: agent.id,
+            agent_identifier: agent.identifier,
+            principal_type: principal.class.polymorphic_name,
+            principal_id: principal.id.to_s,
+            action: action,
+            resource_type: resource_type,
+            resource_id: resource_id,
+            decision: decision_value,
+            reason_code: ActingFor::AuditEvent::DECISION_REASONS.fetch(decision_value),
+            matched_delegation_ids: matches.map(&:id).sort,
+            sanitized_context: sanitized_context
+          }
+        end
+
+        def persist_audit_event!(attributes)
+          ActingFor::AuditEvent.create!(attributes)
+        rescue ActiveRecord::ActiveRecordError => e
+          raise ActingFor::AuditPersistenceError, "Failed to persist audit event", cause: e
+        end
+      end
+    end
+  end
+end

data/app/services/acting_for/internal/constraint_evaluator.rb

@@ -0,0 +1,92 @@
+module ActingFor
+  module Internal
+    class ConstraintEvaluator
+      CONSTRAINT_KEYS = %w[field operator value].freeze
+      private_constant :CONSTRAINT_KEYS
+
+      class << self
+        def call(constraints:, context:)
+          return false unless constraints.is_a?(Array) && context.is_a?(Hash)
+
+          constraints.all? { |constraint| constraint_matches?(constraint, context) }
+        end
+
+        private
+
+        def constraint_matches?(constraint, context)
+          return false unless canonical_constraint?(constraint)
+
+          field = constraint["field"]
+          key = field.to_sym
+          return false unless context.key?(key)
+
+          actual = context[key]
+          return false if actual.nil?
+
+          expected = constraint["value"]
+
+          case constraint["operator"]
+          when "eq"
+            same_scalar_type?(actual, expected) && actual == expected
+          when "lt"
+            integer_comparison?(actual, expected) && actual < expected
+          when "lte"
+            integer_comparison?(actual, expected) && actual <= expected
+          when "gt"
+            integer_comparison?(actual, expected) && actual > expected
+          when "gte"
+            integer_comparison?(actual, expected) && actual >= expected
+          when "in"
+            expected.any? do |candidate|
+              same_scalar_type?(actual, candidate) && actual == candidate
+            end
+          else
+            false
+          end
+        end
+
+        def canonical_constraint?(constraint)
+          return false unless constraint.is_a?(Hash)
+          return false unless constraint.keys.all?(String)
+          return false unless constraint.keys.sort == CONSTRAINT_KEYS
+
+          field = constraint["field"]
+          return false unless field.is_a?(String) && !field.empty?
+
+          value = constraint["value"]
+
+          case constraint["operator"]
+          when "eq"
+            scalar_value?(value)
+          when "lt", "lte", "gt", "gte"
+            value.is_a?(Integer)
+          when "in"
+            value.is_a?(Array) && value.all? { |element| scalar_value?(element) }
+          else
+            false
+          end
+        end
+
+        def integer_comparison?(actual, expected)
+          actual.is_a?(Integer) && expected.is_a?(Integer)
+        end
+
+        def same_scalar_type?(actual, expected)
+          return actual.is_a?(String) if expected.is_a?(String)
+          return actual.is_a?(Integer) if expected.is_a?(Integer)
+          return boolean_value?(actual) if boolean_value?(expected)
+
+          false
+        end
+
+        def scalar_value?(value)
+          value.is_a?(String) || value.is_a?(Integer) || boolean_value?(value)
+        end
+
+        def boolean_value?(value)
+          value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        end
+      end
+    end
+  end
+end

data/app/services/acting_for/internal/delegation_creator.rb

@@ -0,0 +1,121 @@
+module ActingFor
+  module Internal
+    class DelegationCreator
+      class << self
+        def call(agent:, principal:, action:, resource:, constraints:, effect:, expires_at:)
+          unless agent.is_a?(ActingFor::Agent) && agent.persisted?
+            raise InvalidRequestError, "agent must be a persisted ActingFor::Agent"
+          end
+          unless principal.is_a?(ActiveRecord::Base) && principal.persisted?
+            raise InvalidRequestError, "principal must be a persisted ActiveRecord record"
+          end
+
+          action = string_value(action, "action")
+          raise InvalidRequestError, "action must not be blank" if action.blank?
+
+          resource_type, resource_id = resource_identity(resource)
+          effect = string_value(effect, "effect")
+          unless %w[allow require_approval].include?(effect)
+            raise InvalidRequestError, "effect must be allow or require_approval"
+          end
+
+          constraints = canonical_constraints(constraints)
+          validate_expiration(expires_at)
+
+          ActingFor::Delegation.create!(
+            agent: agent, principal: principal, action: action,
+            resource_type: resource_type, resource_id: resource_id,
+            constraints: constraints, effect: effect,
+            expires_at: expires_at, revoked_at: nil
+          )
+        end
+
+        private
+
+        def string_value(value, name)
+          return value if value.is_a?(String)
+          return value.to_s if value.is_a?(Symbol)
+
+          raise InvalidRequestError, "#{name} must be a String or Symbol"
+        end
+
+        def resource_identity(resource)
+          return [nil, nil] if resource.nil?
+
+          klass = resource.is_a?(Class) ? resource : resource.class
+          raise InvalidRequestError, "resource class must provide model_name" unless klass.respond_to?(:model_name)
+
+          model_name = klass.model_name
+          raise InvalidRequestError, "resource model_name must provide name" unless model_name.respond_to?(:name)
+
+          resource_type = model_name.name
+          return [resource_type, nil] if resource.is_a?(Class)
+
+          raise InvalidRequestError, "resource instance must provide id" unless resource.respond_to?(:id)
+
+          id = resource.id
+          raise InvalidRequestError, "resource id must not be nil" if id.nil?
+
+          resource_id = id.to_s
+          raise InvalidRequestError, "resource id must not be empty" if resource_id.empty?
+
+          [resource_type, resource_id]
+        end
+
+        def canonical_constraints(constraints)
+          raise InvalidRequestError, "constraints must be an Array" unless constraints.is_a?(Array)
+
+          constraints.map.with_index do |constraint, index|
+            name = "constraints[#{index}]"
+            raise InvalidRequestError, "#{name} must be a Hash" unless constraint.is_a?(Hash)
+
+            canonical = {}
+            constraint.each do |key, value|
+              key = string_value(key, "#{name} key")
+              raise InvalidRequestError, "#{name} has duplicate key #{key}" if canonical.key?(key)
+
+              canonical[key] = value
+            end
+            unless canonical.keys.sort == %w[field operator value]
+              raise InvalidRequestError, "#{name} must have exactly field, operator and value keys"
+            end
+
+            field = string_value(canonical["field"], "#{name} field")
+            raise InvalidRequestError, "#{name} field must not be empty" if field.empty?
+
+            operator = string_value(canonical["operator"], "#{name} operator")
+            value = canonical["value"]
+            valid_value = case operator
+                          when "eq"
+                            scalar_value?(value)
+                          when "lt", "lte", "gt", "gte"
+                            value.is_a?(Integer)
+                          when "in"
+                            value.is_a?(Array) && value.all? { |element| scalar_value?(element) }
+                          else
+                            raise InvalidRequestError, "#{name} operator must be eq, lt, lte, gt, gte or in"
+                          end
+            raise InvalidRequestError, "#{name} value has an invalid type for #{operator}" unless valid_value
+
+            { "field" => field, "operator" => operator, "value" => operator == "in" ? value.dup : value }
+          end
+        end
+
+        def scalar_value?(value)
+          value.is_a?(String) || value.is_a?(Integer) || value.is_a?(TrueClass) || value.is_a?(FalseClass)
+        end
+
+        def validate_expiration(expires_at)
+          return if expires_at.nil?
+
+          unless expires_at.is_a?(Time) || expires_at.is_a?(ActiveSupport::TimeWithZone)
+            raise InvalidRequestError, "expires_at must be a Time or ActiveSupport::TimeWithZone"
+          end
+          return if expires_at > ActingFor.current_time
+
+          raise InvalidRequestError, "expires_at must be in the future"
+        end
+      end
+    end
+  end
+end

data/db/migrate/20260918030001_create_acting_for_agents.rb

@@ -0,0 +1,11 @@
+class CreateActingForAgents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :acting_for_agents do |t|
+      t.string :identifier, null: false
+      t.string :name
+      t.timestamps null: false
+    end
+
+    add_index :acting_for_agents, :identifier, unique: true
+  end
+end

data/db/migrate/20260918030002_create_acting_for_delegations.rb

@@ -0,0 +1,30 @@
+class CreateActingForDelegations < ActiveRecord::Migration[8.0]
+  def change
+    create_table :acting_for_delegations do |t|
+      t.bigint :agent_id, null: false
+      t.string :principal_type, null: false
+      t.string :principal_id, null: false
+      t.string :action, null: false
+      t.string :resource_type
+      t.string :resource_id
+      t.string :effect, null: false
+      t.json :constraints, null: false, default: []
+      t.datetime :expires_at
+      t.datetime :revoked_at
+      t.timestamps null: false
+    end
+
+    add_foreign_key :acting_for_delegations, :acting_for_agents, column: :agent_id
+    add_index :acting_for_delegations, :agent_id
+    add_index :acting_for_delegations,
+              %i[agent_id principal_type principal_id action resource_type],
+              name: "idx_acting_for_delegations_authorization_lookup"
+
+    add_check_constraint :acting_for_delegations,
+                         "resource_type IS NOT NULL OR resource_id IS NULL",
+                         name: "chk_acting_for_delegations_resource_scope"
+    add_check_constraint :acting_for_delegations,
+                         "effect IN ('allow', 'require_approval')",
+                         name: "chk_acting_for_delegations_effect"
+  end
+end

data/db/migrate/20260918030003_create_acting_for_audit_events.rb

@@ -0,0 +1,29 @@
+class CreateActingForAuditEvents < ActiveRecord::Migration[8.0]
+  def change
+    create_table :acting_for_audit_events do |t|
+      t.bigint :agent_id, null: false
+      t.string :agent_identifier, null: false
+      t.string :principal_type, null: false
+      t.string :principal_id, null: false
+      t.string :action, null: false
+      t.string :resource_type
+      t.string :resource_id
+      t.string :decision, null: false
+      t.string :reason_code, null: false
+      t.json :matched_delegation_ids, null: false, default: []
+      t.json :sanitized_context, null: false, default: {}
+      t.datetime :created_at, null: false
+    end
+
+    add_check_constraint :acting_for_audit_events,
+                         "resource_type IS NOT NULL OR resource_id IS NULL",
+                         name: "chk_acting_for_audit_events_resource_scope"
+    add_check_constraint :acting_for_audit_events,
+                         "decision IN ('allow', 'deny', 'require_approval')",
+                         name: "chk_acting_for_audit_events_decision"
+    add_check_constraint :acting_for_audit_events,
+                         "reason_code IN ('delegation_allowed', 'delegation_requires_approval', " \
+                         "'no_matching_delegation')",
+                         name: "chk_acting_for_audit_events_reason_code"
+  end
+end

data/lib/acting_for/decision.rb

@@ -0,0 +1,27 @@
+module ActingFor
+  class Decision
+    STATUSES = %i[allow deny require_approval].freeze
+    private_constant :STATUSES
+
+    attr_reader :status
+
+    def initialize(status)
+      raise ArgumentError, "invalid decision status" unless STATUSES.include?(status)
+
+      @status = status
+      freeze
+    end
+
+    def allowed?
+      status == :allow
+    end
+
+    def denied?
+      status == :deny
+    end
+
+    def approval_required?
+      status == :require_approval
+    end
+  end
+end

data/lib/acting_for/engine.rb

@@ -0,0 +1,7 @@
+require "rails"
+
+module ActingFor
+  class Engine < ::Rails::Engine
+    isolate_namespace ActingFor
+  end
+end

data/lib/acting_for/errors.rb

@@ -0,0 +1,13 @@
+module ActingFor
+  class Error < StandardError
+  end
+
+  class InvalidRequestError < Error
+  end
+
+  class InternalError < Error
+  end
+
+  class AuditPersistenceError < InternalError
+  end
+end

data/lib/acting_for/version.rb

@@ -0,0 +1,3 @@
+module ActingFor
+  VERSION = "0.1.0"
+end

data/lib/acting_for.rb

@@ -0,0 +1,24 @@
+require "acting_for/version"
+require "acting_for/engine"
+require "acting_for/errors"
+require "acting_for/decision"
+
+module ActingFor
+  def self.authorize(agent:, principal:, action:, resource: nil, context: {}, audit_context_keys: [])
+    Internal::Authorization.call(
+      agent: agent, principal: principal, action: action, resource: resource, context: context,
+      audit_context_keys: audit_context_keys
+    )
+  end
+
+  def self.delegate(agent:, principal:, action:, resource: nil, constraints: [], effect:, expires_at: nil)
+    Internal::DelegationCreator.call(
+      agent: agent, principal: principal, action: action, resource: resource,
+      constraints: constraints, effect: effect, expires_at: expires_at
+    )
+  end
+
+  def self.current_time
+    Time.current
+  end
+end

metadata

@@ -0,0 +1,132 @@
+--- !ruby/object:Gem::Specification
+name: acting_for
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ChangQuan Cui
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.91'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.91'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- app/models/acting_for/agent.rb
+- app/models/acting_for/application_record.rb
+- app/models/acting_for/audit_event.rb
+- app/models/acting_for/delegation.rb
+- app/services/acting_for/internal/authorization.rb
+- app/services/acting_for/internal/constraint_evaluator.rb
+- app/services/acting_for/internal/delegation_creator.rb
+- db/migrate/20260918030001_create_acting_for_agents.rb
+- db/migrate/20260918030002_create_acting_for_delegations.rb
+- db/migrate/20260918030003_create_acting_for_audit_events.rb
+- lib/acting_for.rb
+- lib/acting_for/decision.rb
+- lib/acting_for/engine.rb
+- lib/acting_for/errors.rb
+- lib/acting_for/version.rb
+homepage: https://github.com/cuichangquan/acting_for
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/cuichangquan/acting_for
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: '4.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Rails-native delegated authorization for AI agents.
+test_files: []