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
- Unknown resource, action, alias, permission, or fact denies.
- Fact and permission exceptions deny and remain observable; they are not converted into silent allows.
- There is no global superuser lambda. Elevated access is a named fact inside the relevant permission and appears in explanations.
- No permission name is generated from arbitrary action text. Aliases are explicitly registered.
- 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.
-
authorized_scopemust translate authorization to a database query. Ruby-side filtering is not an acceptable security boundary. - 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::Subjectaddscan?,cannot?, anddecision_for. -
Permissify::Controlleradds explicitauthorize!(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
- Inventory every Pundit policy method and scope, including organization and role sources.
- Capture characterization tests for current outcomes and protected entry points.
- Implement one resource in Permissify while Pundit remains authoritative.
- Shadow both decisions and record unexplained differences without changing the user outcome.
- Switch one enforcement path behind a reversible flag.
- Migrate its database scope and verify tenant isolation.
- Repeat resource by resource.
- 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
FactSourceequivalence - controller enforcement and exception payload
- SQL scope tenant isolation
- development reload safety
- shadow parity against the migrated Pundit policy and scope