25: Role-derived access and permission patterns

[AmaraNecib]

What changed

Extends the decision path so that:

1. Permission patterns — Added matchesPermission() supporting exact keys, global *, and namespace files.* patterns. The evaluate() function now uses pattern matching for fact resolution.
2. Role-derived access — Roles carry permission facts; assignments link principals to roles (already supported via MemoryAdapter from First decision: trusted principal, memory facts, can, and decide #24). Role-derived + direct grants are additive; a matching denial wins.
3. Tests — 26 new tests covering pattern matching, multi-role additive grants, deny precedence, namespace boundaries.

Changes by file

File	Change
packages/core/src/index.ts	Added matchesPermission(), updated evaluate() to use pattern matching
packages/core/__tests__/decision.test.ts	26 new tests for patterns + role-derived access
packages/core/__tests__/smoke.test.ts	Added matchesPermission export test

Bug fix (TDD)

Code-review found a namespace dot-boundary bug — "filesX.read" incorrectly matched "files.*". Fixed test-first.

Acceptance criteria

• A role can carry permission facts and a principal can receive a role through an assignment
• Role-derived grants, direct grants, and grants from multiple roles are additive
• A direct matching denial overrides role-derived and direct grants for that permission
• Removing or denying one permission does not remove unrelated permissions
• Exact permission keys, global pattern *, and namespace patterns such as files.* are supported
• Patterns do not make otherwise unknown permission keys valid by themselves
• Tests cover multiple roles, direct access, deny precedence, exact matching, global matching, and namespace matching

Verification

• Typecheck: ✅
• Tests: 51 core + 16 memory — all pass
• Lint: ✅
• Build: ✅

Refs #25

Summary by CodeRabbit

• New Features

  • Added wildcard permission matching, including global (*) and namespace patterns such as files.*.
  • Permission evaluation now supports pattern-based grants and denials.
  • Added the ability to combine access from roles and direct permissions while preserving explicit denials.

• Tests

  • Expanded coverage for wildcard matching, role-derived access, denials, and multiple permission sources.

[AmaraNecib]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d114c87d-dd1e-4630-8109-67e1f9133405

📥 Commits

Reviewing files that changed from the base of the PR and between 327a634 and 93d1e35.

📒 Files selected for processing (3)

• packages/core/__tests__/decision.test.ts
• packages/core/__tests__/smoke.test.ts
• packages/core/src/index.ts

---

📝 Walkthrough

Walkthrough

The core package adds exported exact, global, and namespace permission matching, integrates it into authorization evaluation, and expands tests for pattern grants, denials, role-derived access, and additive behavior.

Changes

Permission pattern authorization

Layer / File(s)	Summary
Permission matcher and evaluator integration packages/core/src/index.ts	Adds and exports matchesPermission, then uses it to filter authorization facts during evaluation.
Pattern and role access validation packages/core/__tests__/decision.test.ts, packages/core/__tests__/smoke.test.ts	Tests exact and wildcard matching, denial precedence, namespace behavior, role-derived grants, and the public export.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related issues

• AmaraNecib/mizan#25 — Covers permission patterns, role-derived access, additive grants, and denial precedence implemented by this PR.

Possibly related PRs

• AmaraNecib/mizan#40 — Establishes the core evaluation and deny-overrides-grant flow extended here with pattern-based permission filtering.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the main changes: role-derived access and permission pattern matching.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/25-role-derived-access

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[AmaraNecib]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.