Export Page

01 · Permissify Authorization Contract

Status: Proposed · Gem: StockLive-Group/permissify · Rich companion: 01-authorization-contract.html

Purpose

Permissify gives applications one explicit authorization question:

decision = Permissify.decide(actor: user, action: :edit, resource: article)
decision.allowed?

user.can?(:edit, article) # convenience projection

It is a separately packaged Ruby gem so its API, dependency graph, boot behavior, and test suite remain inspectable in isolation. StockLive still remains one deployable platform.

Why use it instead of Pundit?

Pundit is a good default when an application benefits from one policy object per resource and conventional controller authorization. Permissify is justified only when StockLive's activity vocabulary and cross-resource composition are more important than policy-class locality.

Concern Pundit Permissify
Primary unit policy method on a resource policy named permission composed from named facts
Public question policy(record).update? actor.can?(:edit, record)
Composition ordinary Ruby across policy methods/classes registered checks with dependency/explanation metadata
Explanation application-specific structured Decision is part of the core contract
Audit inventory policy files and methods central Registry of resources, permissions, facts and aliases
Collection authorization policy scope explicit database-level scope adapter
Adoption mature Rails convention custom gem that must earn its maintenance cost

Choose Pundit when its policy shape stays clear. Choose Permissify when the same activity language must be shared across controllers, views, workflows, background jobs and integrations; when explanations and registry-level audits are first-class; and when reusable facts materially reduce duplication. Do not migrate merely to shorten syntax.

Runtime architecture

caller
  -> Permissify.decide(actor:, action:, resource:, environment:)
  -> explicit action alias lookup
  -> Registry permission lookup
  -> DecisionContext construction
  -> named fact evaluation
  -> Decision(allowed, permission, checks, reason, metadata)
  -> enforcement / boolean convenience / explanation

Registry

The Registry is populated at boot and holds immutable definitions:

  • resource keys
  • permission names
  • explicit action aliases
  • named checks and their dependencies
  • optional scope builders

The DSL has no runtime authority by itself. It is a registration script that builds Registry entries.

Permissify.define(:article) do
  fact(:draft) { |ctx| ctx.resource.status == "draft" }
  fact(:owned_by_actor) { |ctx| ctx.resource.user_id == ctx.actor.id }
  fact(:actor_admin) { |ctx| ctx.fact(:admin) }

  permission(:editable) { |ctx| ctx.all?(:draft, :owned_by_actor) }
  permission(:publishable) { |ctx| ctx.all?(:draft, :actor_admin) }

  action :edit, maps_to: :editable
  action :publish, maps_to: :publishable
end

DecisionContext

DecisionContext is typed and explicit:

DecisionContext.new(
  actor: actor,
  resource: resource,
  action: :edit,
  environment: { tenant: Current.organization },
  fact_source: fact_source
)

It does not call attributes, inject _user keys, or hash arbitrary object graphs. Adapters decide which environment inputs are permitted. This keeps cache identity, privacy, and mutation behavior visible.

Decision

Every evaluation returns a structured result:

Decision.new(
  allowed: false,
  permission: :editable,
  reason: :missing_fact,
  checks: [{ name: :owned_by_actor, result: false }],
  metadata: { resource_type: "Article" }
)

can? returns decision.allowed?; authorize! raises with the decision attached. Logs and debugging tools may record safe identifiers, never arbitrary actor/resource attributes.

Safety contracts

  1. Unknown resource, action, alias, permission, or fact denies.
  2. Fact and permission exceptions deny and remain observable; they are not converted into silent allows.
  3. There is no global superuser lambda. Elevated access is a named fact inside the relevant permission and appears in explanations.
  4. No permission name is generated from arbitrary action text. Aliases are explicitly registered.
  5. No decision caching in the baseline. A later cache requires measured need, complete key identity, explicit invalidation, bounded storage, safe failure behavior, and cached/uncached equivalence tests.
  6. authorized_scope must translate authorization to a database query. Ruby-side filtering is not an acceptable security boundary.
  7. Registry mutation is synchronized and limited to boot/reload boundaries.

How Permissify works without Predicate

Predicate is not a runtime dependency. The host supplies a FactSource:

class ArticleFacts
  def fetch(name, context)
    case name
    when :admin then context.actor.admin?
    when :organization_member
      context.actor.organization_ids.include?(context.resource.organization_id)
    else
      Permissify::FactSource::Missing
    end
  end
end

Plain Ruby facts can call models, repositories, or value objects through injected collaborators. The core gem, DSL, decision model, enforcement, explanations and scopes all work without Predicate.

How Permissify leverages Predicate

Predicate may implement the same fact port:

class PredicateFactSource
  def initialize(registry: Predicate)
    @registry = registry
  end

  def fetch(name, context)
    @registry.for(context.resource).call(
      name,
      actor: context.actor,
      resource: context.resource,
      tenant: context.environment.fetch(:tenant)
    )
  end
end

The adapter may reuse Predicate's boolean composition, validation helpers, instrumentation, or memoization for business facts. It must not:

  • decide the requested permission
  • map actions to permissions
  • raise authorization errors
  • expose Predicate-specific objects through Permissify's public API
  • change outcomes compared with a conforming plain-Ruby fact source

Contract tests run the same permission examples against both fact sources. Removing Predicate must require only swapping the adapter, not rewriting permission declarations or callers.

Rails integration

Rails support is optional and isolated from core:

  • Permissify::Subject adds can?, cannot?, and decision_for.
  • Permissify::Controller adds explicit authorize!(action, resource); no controller-action inference is required for correctness.
  • authorized_scope(actor:, action:, relation:) delegates to a registered SQL-capable scope builder.
  • the Railtie handles permission-file loading and development reloads without asking Zeitwerk to constantize registration scripts.

Views may use can? for presentation, but controllers, commands, jobs, and model entry points enforce authorization independently. Hidden buttons are not enforcement.

Pundit coexistence and migration

  1. Inventory every Pundit policy method and scope, including organization and role sources.
  2. Capture characterization tests for current outcomes and protected entry points.
  3. Implement one resource in Permissify while Pundit remains authoritative.
  4. Shadow both decisions and record unexplained differences without changing the user outcome.
  5. Switch one enforcement path behind a reversible flag.
  6. Migrate its database scope and verify tenant isolation.
  7. Repeat resource by resource.
  8. Remove Pundit only when the inventory is complete, no fallback calls remain, and rollback is no longer needed.

Gem boundary and dependencies

Core runtime dependencies: Ruby standard library only. Rails and Predicate adapters are optional files loaded only when their host constants are available. The public gem examples remain generic; StockLive-specific permission definitions remain in StockLive.

During active development StockLive pins the gem by Git SHA. Releases follow semantic versioning once the API stabilizes.

Verification matrix

  • standalone Ruby boot without Rails or Predicate
  • registry and DSL definition validation
  • default-deny cases for every unknown/missing/error state
  • structured decision and explanation stability
  • action alias collision detection
  • plain Ruby and Predicate FactSource equivalence
  • controller enforcement and exception payload
  • SQL scope tenant isolation
  • development reload safety
  • shadow parity against the migrated Pundit policy and scope

Made with Kuickr

01 · Permissify Authorization Contract
‹ 2 / 6 ›