elsa-core/specs/013-rbac-authorization-model/plan.md

Implementation Plan: Authorization Model

Status: Draft — pending approval

Tracking: #7974

Branch: 013-rbac-authorization-model | Date: 2026-08-23 | Spec: spec.md

Input: Feature specification from /specs/013-rbac-authorization-model/spec.md, grounded in research.md

Summary

Replace Elsa's ad-hoc permission vocabulary with a two-axis authorization model: a hierarchical resource axis and an open verb axis, both module-contributed, evaluated by a single evaluator that every enforcement path routes through.

Both axes are open because Elsa is a framework third parties extend, and because ADR 0017 commits to an open vocabulary. Prefix matching on the resource axis makes section-wide grants a single token, which removes the pressure for a second, coarse-grained gate. Wildcards are the only construct with forward reach on either axis, so *:* is superuser with no sentinel and no aggregate to reinterpret. A closed verb enumeration was drafted and rejected; see research.md D13.

Storage is unchanged: Role.Permissions remains a string collection of flat {resource}:{verb} entries.

Technical Context

Language/Version: C# latest; nullable reference types and implicit usings; multi-target net8.0, net9.0, net10.0.

Primary Dependencies: Elsa.Api.Common (FastEndpoints base classes, permission constants), Elsa.Identity (roles, users, applications, token issuance), Elsa.Features / CShells shell features, ASP.NET Core authorization, Elsa.Mediator for audit notifications, Entity Framework Core for Identity persistence.

Storage: No schema change for grants. Role.Permissions stays ICollection<string> persisted through the existing comma-joining converter in src/modules/Elsa.Persistence.EFCore/Modules/Identity/Configurations.cs, which forbids commas inside a permission string. The tenancy milestone changes Identity indexes only and requires migrations across all five providers.

Testing: xUnit unit tests for the resource and verb matchers; a reflection-driven gate asserting every in-repository endpoint declares a permission resolving to a registered descriptor; integration tests for introspection, revocation, and per-tenant isolation; regression tests proving legacy strings no longer authorize and that the whole-vocabulary grant still does.

Target Platform: ASP.NET Core Elsa Server; consumed by Elsa Studio and other clients through the catalog and introspection endpoints.

Project Type: Modular .NET server libraries with REST endpoints.

Performance Goals: Evaluation is O(number of grants held) with no store access on the request path; no measurable regression against today's ordinal set lookup. The catalog is built once per shell and cached.

Constraints: No new infrastructure may become a prerequisite for correct authorization — in particular the optional security stamp must not depend on cross-node cache invalidation, which Elsa does not have (ChangeTokenSignalInvoker is per-process). Elsa remains the only authority expanding roles into permission claims (ADR 0022). Permission strings may not contain commas. No cross-tenant principal is introduced.

Scale/Scope: 47 resources and 23 verbs at publication, rising as modules contribute descriptors; 160 endpoint files; 174 declaration call sites; hand-rolled claim inspections across 15 files; 3 named-policy usages; 4 SignalR hubs. A further 15 mid-handler NotReadOnlyPolicy calls exist but are out of scope — read-only mode is a separate axis.

Constitution Check

GATE: PASS before research and after design.

Principle	Verdict	Evidence
I. Modular Architecture	PASS	The model and evaluator live in Elsa.Api.Common; each module owns its own descriptors and constants. The descriptor registry moves out of an optional module into core, correcting an existing inversion.
II. Composition & Extensibility	PASS	The resource axis is open and contributed through IPermissionDescriptorProvider. Third-party modules keep working through an obsolete-but-functional declaration API with graceful degradation.
III. Convention-Driven Design	PASS	Adopts the established Permissions/<Module>Permissions.cs pattern already proven in External Authentication, refined to one constant per resource. Verb coherence is maintained by a recommended core set as convention rather than by enforcement.
IV. Async & Pipeline Execution	PASS	Evaluation is synchronous and allocation-light by design; catalog contribution and introspection follow existing async contracts.
V. Testing Discipline	PASS	Unit, integration, regression, and an automated coverage gate; the gate is itself a deliverable.
VI. Trunk-Based Development	PASS	Milestones are independently shippable; the cutover is split one pull request per module, landing in any order because the obsolete declaration path and the seeded admin grant keep trunk green throughout.
VII. Simplicity, SRP, DRY & KISS	PASS	Two axes, one matching rule shape, one wildcard. No enumeration, no mask, no aggregates, no second gate, no sentinel. Collapses four parallel permission-checking mechanisms into one and six duplicated method bodies into one; read-only mode correctly keeps its own axis.

Project Structure

Documentation

specs/013-rbac-authorization-model/
├── spec.md          # feature specification
├── plan.md          # this file
├── research.md      # grounded assessment and decisions log
└── contracts/
    ├── rest-api.md      # catalog and introspection contracts
    └── permissions.md   # the resource tree and supported verbs
docs/
├── adr/00NN-two-axis-authorization-model.md
└── migrations/authorization-model.md

Elsa Core Repository

src/common/Elsa.Api.Common/
├── Authorization/
│   ├── CoreVerbs.cs                    # recommended verb constants (convention)
│   ├── Permission.cs                   # (resource, verb) with parse/format
│   ├── IPermissionEvaluator.cs
│   ├── PermissionEvaluator.cs          # the single decision point
│   ├── PermissionMatcher.cs            # exact and wildcard, on both axes
│   ├── PermissionRequirement.cs
│   └── PermissionAuthorizationHandler.cs
├── Permissions/
│   ├── PermissionDescriptor.cs         # promoted from Elsa.ExternalAuthentication
│   ├── IPermissionDescriptorProvider.cs
│   ├── IPermissionDescriptorRegistry.cs
│   └── DefaultPermissionDescriptorRegistry.cs
├── Abstractions/Endpoints.cs           # RequirePermission(resource, verb); collapse 6 duplicates
├── PermissionNames.cs                  # reduced to claim type and the whole-vocabulary grant
└── EndpointSecurityOptions.cs          # remove dead role-name fields

src/modules/<Module>/Permissions/<Module>Permissions.cs   # constants + descriptors, per module
src/modules/Elsa.Identity/
├── Endpoints/Me/Permissions/Endpoint.cs                  # introspection
├── Services/DefaultAccessTokenIssuer.cs                  # emit new-format claims
├── Services/RoleAuthorizationService.cs                  # delegate to the evaluator
└── Options/IdentityTokenOptions.cs                       # shorter default lifetime; stamp options

src/modules/Elsa.Persistence.EFCore/Modules/Identity/Configurations.cs   # per-tenant indexes
src/modules/Elsa.Common/Services/MemoryStore.cs                          # tenant filtering

Phase 0: Research

Complete. See research.md for the grounded assessment and the decision record D1–D26 that this plan implements. Note that D1–D12 are partly superseded — most importantly D3 by D13, which opened the verb axis — so the governing set is the record as a whole, not its first twelve entries. Two findings materially shaped the design and are recorded there rather than restated: the resource axis had to become hierarchical for the model to remove the need for a coarse second gate, and Elsa.Caching provides no distributed invalidation, which constrains the revocation design.

Phase 1: Data Model and Contracts

Produce contracts/permissions.md — the full resource tree with supported verbs per resource, derived from the current 33 resources and the endpoint census — and contracts/rest-api.md for the catalog and introspection endpoints. Publish the legacy-to-new mapping as doc/migrations/authorization-model.md, following the shape of doc/migrations/external-authentication-persistence.md. Record the model in an ADR.

The resource tree is the highest-value artefact to review early: it is the vocabulary every module and client will hold, and it is expensive to change once published.

Implementation Sequence

Milestone 1: Model and Evaluator

Additive only; nothing changes behavior.

• CoreVerbs, Permission, PermissionMatcher, IPermissionEvaluator and its implementation.
• Promote the descriptor registry from Elsa.ExternalAuthentication into Elsa.Api.Common, leaving type-forwarding shims so External Authentication keeps compiling.
• Unit tests for the matcher table: exact match on both axes, subtree wildcard, verb wildcard, whole-vocabulary, absence denying, and a wildcard covering a newly registered resource or verb.

Milestone 2: Catalog Coverage

Still additive.

• Every module with protected endpoints contributes a Permissions/<Module>Permissions.cs carrying one constant per resource and its descriptors, following the External Authentication pattern.
• The catalog endpoint, and the reach report backing "this grant currently covers these resources".
• External Authentication's existing unknown_permission_descriptor warning becomes meaningful for core permissions for the first time.

Milestone 3: Cutover

The breaking change. One pull request per module.

• Endpoints migrate to RequirePermission(resource, verb).
• The hand-rolled claim inspections (15 files), 3 named-policy usages, and 4 SignalR hub checks all route through the evaluator. The 15 mid-handler NotReadOnlyPolicy calls are deliberately excluded — read-only mode is a separate axis.
• ConfigurePermissions(params string[]) becomes obsolete but functional, with unresolvable strings registering implicit unverified descriptors and logging warnings.
• The fail-closed gate lands, asserting every in-repository endpoint declares a permission resolving to a registered descriptor.
• The token issuer emits new-format claims; the startup validator reports unresolvable stored permissions by role.
• No migration scaffold is required: the obsolete ConfigurePermissions(string[]) path translates legacy endpoint declarations through the migration table, and the seeded admin * grant satisfies every endpoint throughout, so module PRs can land in any order. Module-specific authorization fixtures migrate with their module.

Milestone 4: Introspection, Revocation, and Audit

• GET /identity/me/permissions, including denied resources with an empty verbs array.
• Access-token lifetime default lowered from 1 hour to 15 minutes, documented as the revocation bound. Refresh already rotates both tokens and re-reads roles, so no client change is required; refresh-token lifetime is unchanged at 2 hours.
• Optional per-principal security stamp with a per-node cache and configurable interval, dependent on no new infrastructure.
• Typed security notifications for role and assignment mutations, per ADR 0020.

Milestone 5: Tenancy Hardening

Independently justified as a latent-defect fix; sequenced last so the unresolved isolation-boundary question does not block delivery.

• Per-tenant composite unique indexes for role, user, and application names, with migrations across all five providers.
• Tenant filtering in MemoryStore, so the default stores isolate rather than relying on the Entity Framework path.
• Explicit tenant filters on role and user listing, and on user creation.

Excluded: Elsa.Secrets tenancy, tracked as #7972.

Post-Design Constitution Re-check

GATE: performed 2026-08-23, after the Phase 1 contracts landed. PASS.

Principle	Verdict	Evidence
I. Modular Architecture	PASS	Model and evaluator in Elsa.Api.Common; each module owns its own resources. The descriptor registry moves out of an optional module into core, correcting an existing inversion.
II. Composition & Extensibility	PASS	Both axes open and module-contributed; third-party modules keep working through an obsolete-but-functional declaration path with graceful degradation.
III. Convention-Driven Design	PASS	Follows the proven Permissions/<Module>Permissions.cs pattern; verb coherence is convention (a recommended core set) rather than enforcement. American English throughout.
IV. Async & Pipeline Execution	PASS	Evaluation is synchronous and allocation-light by design; catalog contribution and introspection follow existing async contracts.
V. Testing Discipline	PASS	Unit, integration, regression, plus the coverage gate as a deliverable.
VI. Trunk-Based Development	PASS	Milestones independently shippable; the cutover is one PR per module, landing in any order.
VII. Simplicity, SRP, DRY & KISS	PASS with a note	Two axes, one matching rule shape, one wildcard; no enumeration, mask, aggregates, second gate or sentinel. Note: the tree carries 47 resources and 23 verbs, of which 17 verbs are module-specific and used once or twice. Each traces to a distinction an existing endpoint already makes, and the alternative — a closed verb set — was measured and rejected in D13. Re-examine at Milestone 2 if any module proposes a verb no endpoint distinguishes.

Complexity Tracking

Item	Justification	Exit condition
Obsolete ConfigurePermissions(params string[]) retained indefinitely	Third-party modules outside this repository must keep compiling across the upgrade.	Removed at the next major version.
Implicit unverified descriptors for unrecognized third-party permissions	Failing a host at boot because a module the operator does not own uses an unknown string is disproportionate; the existing unknown_permission_descriptor precedent warns instead.	None; permanent, with the gap visible in the catalog.
Wildcard grants confer forward reach on the resource axis	This is the property that makes section-wide grants viable and removes the need for a second gate.	None; mitigated by catalog reach reporting.