krayin-authorization
GitHub用于理解、实现、调试、审查和测试 Krayin CRM 2.2 的授权架构,涵盖 ACL、角色管理、Bouncer 中间件、路由权限映射及数据作用域。
触发场景
安装
npx skills add krayin/laravel-crm --skill krayin-authorization -g -y
SKILL.md
Frontmatter
{
"name": "krayin-authorization",
"license": "MIT",
"metadata": {
"author": "webkul"
},
"description": "Understand, implement, debug, review, and test Krayin CRM branch 2.2 authorization. Covers ACL permissions, roles, Bouncer middleware, route-to-permission mapping, view permissions, data scoping, role privilege ceilings, user authorization, and authorization security testing."
}
Krayin CRM 2.2 Authorization Skill
Purpose
This skill defines the authorization architecture used by Krayin CRM branch 2.2.
Use this skill whenever a task involves:
- ACL
- permissions
- roles
- authorization
- access control
- Bouncer
- route permissions
- role management
- user role assignment
- view permissions
- global/group/individual access
- data scoping
- privilege escalation
- authorization bugs
- security testing
- permission-related UI
- authorization middleware
- authorization regression tests
The authorization model has two orthogonal dimensions:
- Action authorization through ACL.
- Record/data authorization through view permission.
A user must satisfy both dimensions when an operation requires record-level authorization.
0. Verified Source Anchors
These paths and symbols exist in branch 2.2 and were verified against the source. Start here rather than searching blind. Re-verify before relying on any behavioral detail — this section is an index, not a substitute for reading the code.
| Concern | Location |
|---|---|
| ACL permission vocabulary | packages/Webkul/Admin/src/Config/acl.php |
| Permission tree + route map | packages/Webkul/Core/src/Acl.php |
| Request-level enforcement | packages/Webkul/Admin/src/Http/Middleware/Bouncer.php |
| Permission + scope helpers | packages/Webkul/Admin/src/Bouncer.php |
bouncer() helper |
packages/Webkul/Admin/src/Http/helpers.php |
acl() helper |
packages/Webkul/Core/src/Http/helpers.php |
| Menu ACL filtering | packages/Webkul/Core/src/Menu.php |
| Role model / permissions cast | packages/Webkul/User/src/Models/Role.php |
User model / hasPermission() |
packages/Webkul/User/src/Models/User.php |
| Group member ID resolution | packages/Webkul/User/src/Repositories/UserRepository.php |
| Record + collection scope guards | packages/Webkul/Admin/src/Http/Controllers/Controller.php |
| Role escalation guards | packages/Webkul/Admin/src/Http/Controllers/Settings/RoleController.php |
| Role/scope assignment guards | packages/Webkul/Admin/src/Http/Controllers/Settings/UserController.php |
| Menu vocabulary | packages/Webkul/Admin/src/Config/menu.php |
| Administrator role seed | packages/Webkul/Installer/src/Database/Seeders/User/RoleSeeder.php |
Key symbols to grep for:
Acl::getItems()
Acl::getRoles()
Acl::getAuthorizedItems()
Bouncer::hasPermission()
Bouncer::allow()
Bouncer::getAuthorizedUserIds()
Middleware\Bouncer::isPermissionsEmpty()
Middleware\Bouncer::checkIfAuthorized()
Middleware\Bouncer::isAllowlistedRoute()
Middleware\Bouncer::isAuthorizedByFeature()
Controller::preventUnauthorizedAccess()
Controller::filterAuthorizedRecords()
RoleController::canManageRole()
UserController::preventUnauthorizedRoleAssignment()
UserController::preventUnauthorizedScopeAssignment()
UserRepository::getCurrentUserGroupsUserIds()
User::hasPermission()
1. Authorization Model
Krayin authorization is not represented by a single permission field.
There are two separate authorization dimensions.
Action authorization
Stored primarily through the user's role:
roles.permission_type
roles.permissions
The role determines which actions the user can perform.
Examples:
leads
leads.view
leads.create
leads.edit
leads.delete
settings.user.roles.create
settings.user.roles.edit
settings.user.roles.delete
Data authorization
Stored on the user:
users.view_permission
Supported values:
global
group
individual
This determines which records the user may access.
Therefore:
Effective authorization =
Action permission
AND
Authorized data scope
Do not treat ACL permission and view permission as interchangeable.
2. Core Authorization Tables
The primary database structures involved in authorization are:
| Table | Important fields | Purpose |
|---|---|---|
| roles | permission_type, permissions, created_by | Defines role-level action permissions |
| users | role_id, view_permission, status, created_by | Associates user with role and data scope |
| groups | id, name | Defines groups used by group-level visibility |
| user_groups | user_id, group_id | Associates users with groups |
Before changing authorization behavior, inspect the actual branch 2.2 migrations/models/controllers rather than assuming the schema.
3. ACL Permission Vocabulary
The ACL permission vocabulary is defined in:
packages/Webkul/Admin/src/Config/acl.php
The ACL configuration contains permission entries.
Typical structure:
[
'key' => 'leads.edit',
'name' => 'admin::app.acl.edit',
'route' => [
'admin.leads.edit',
'admin.leads.update',
'admin.leads.mass_update',
],
'sort' => 3,
],
Important:
The permission key and route name are not necessarily the same thing.
The ACL configuration maps routes to permission keys.
Always inspect the existing configuration before adding a new permission.
Do not invent a new naming convention if an established Krayin convention already exists.
4. ACL Source of Truth
The ACL configuration is consumed by the core ACL implementation.
Important concepts:
acl.php
|
+-- permission tree
|
+-- route -> permission mapping
The permission tree is used by role-management UI.
The route mapping is used by request authorization.
When debugging authorization, determine:
- What permission key is required?
- Which route is being requested?
- Is that route mapped?
- Which role permissions does the user have?
- Is the user an administrator?
5. Bouncer Middleware
Admin authorization is enforced by:
packages/Webkul/Admin/src/Http/Middleware/Bouncer.php
The middleware is the authoritative request-level security boundary.
Do not assume that hiding a button or menu item provides security.
A request must be protected server-side.
Conceptually:
Request
|
v
Authentication
|
v
User status
|
v
Role
|
v
Administrator check
|
v
Permission resolution
|
v
ACL authorization
|
+-- denied -> 401
|
v
Controller
The exact implementation must always be verified against the current Krayin branch before modifying authorization code.
6. Administrator Behavior
Krayin supports an administrator/full-permission role through:
permission_type = all
When working with administrator authorization:
- inspect the administrator short-circuit in middleware;
- inspect how
hasPermission()handlesall; - inspect how role permissions are represented;
- do not assume that
permissions = nullor an empty array has the same meaning in every authorization method.
Important:
Different authorization entry points may implement administrator handling differently.
Concrete example in branch 2.2: the seeded administrator role has
permission_type = 'all' and permissions = null. The instance method
Admin\Bouncer::hasPermission() checks permission_type == 'all' and
returns true, but the static Bouncer::allow() does not — it delegates
straight to User::hasPermission(), which reads role->permissions
directly. That path is only safe because the middleware short-circuits
administrators in isPermissionsEmpty() before checkIfAuthorized()
ever calls allow().
When reviewing authorization code, verify the actual execution path
rather than relying on the value of permission_type alone.
7. Route Authorization
Authorization should be understood as:
HTTP request
|
v
Route name
|
v
ACL route mapping
|
v
Permission key
|
v
User role permissions
|
v
Allow / Deny
Example:
admin.leads.update
|
v
leads.edit
|
v
user role contains leads.edit?
|
+--+--+
YES NO
| |
allow 401
Never assume that a controller method is protected merely because the corresponding UI button is hidden.
Always test direct route access.
8. Ancestor / Feature Authorization
Some routes may not have an explicit ACL entry.
When the branch 2.2 implementation supports feature/ancestor fallback,
authorization must be evaluated according to the actual
isAuthorizedByFeature() behavior.
Conceptually:
admin.leads.search
|
v
admin.leads
|
v
leads.*
An unmapped child route must not accidentally become publicly accessible to an authenticated user.
When adding a new route:
- Search for an exact ACL mapping.
- Search for ancestor/feature authorization.
- Determine whether an allow-list applies.
- Confirm the final middleware behavior.
- Add an authorization regression test.
9. Allow-list
Some routes may intentionally bypass normal ACL authorization.
Examples may include:
- account/profile functionality
- password-related functionality
- session-related endpoints
- saved filters
- TinyMCE upload
- web-form endpoints
- inbound mail processing
Do not add a route to an authorization allow-list simply to make a failing test pass.
Before modifying the allow-list:
- Understand what data the route exposes.
- Determine whether authentication is sufficient.
- Determine whether the route performs a privileged operation.
- Check whether an existing ACL permission should protect it.
- Add a security regression test.
Prefer explicit authorization over broad allow-list exceptions.
10. UI Permission Checks
ACL is also used to control UI visibility.
Common locations include:
Menu
Blade views
Admin components
Action buttons
Mass actions
Settings tiles
Typical pattern:
bouncer()->hasPermission('leads.delete')
This can determine whether the user sees:
- Delete buttons
- Create buttons
- Edit actions
- Mass actions
- Navigation entries
- Settings options
However:
UI permission != security boundary
A hidden button does not prevent:
POST /admin/...
The server-side authorization layer must still reject unauthorized requests.
11. View Permission
View permission controls the data scope of a user.
Values:
global
group
individual
Conceptual behavior:
global
|
v
unrestricted data scope
group
|
v
records associated with users
in the caller's groups
individual
|
v
records belonging to the current user
The implementation should be traced through:
Bouncer::getAuthorizedUserIds()
before changing behavior.
12. Authorized User IDs
The data-scope system should resolve to an authorized user-ID set.
Conceptually:
global
-> null
-> no user_id restriction
group
-> group member IDs
individual
-> current user's ID
Important:
null must be interpreted according to the actual call site.
Do not automatically add:
whereIn('user_id', null)
for global access.
Check how each repository/datagrid/controller handles the
authorized-ID result. The prevailing branch 2.2 idiom relies on
truthiness, so a null result adds no constraint at all:
if ($userIds = bouncer()->getAuthorizedUserIds()) {
$query->whereIn('leads.user_id', $userIds);
}
13. Data-Scoping Enforcement
Data scope can be enforced in several ways.
Query filtering
Example:
$query->whereIn('user_id', $authorizedUserIds);
Potential locations include datagrids and repositories.
Single-record authorization
A controller may check ownership before returning a record.
Conceptually:
requested record
|
v
record owner
|
v
authorized user IDs
|
+-- match -> allow
|
+-- no match -> 401
Collection filtering
An already-loaded collection may be filtered to authorized records.
When modifying data scope, search for all three patterns.
14. Record Ownership
Data visibility commonly depends on an ownership field such as:
user_id
When creating records, check whether the owner is assigned.
A non-global user may otherwise create or receive a record that cannot later be retrieved through normal scoped queries.
When modifying record creation:
- Identify the owner field.
- Determine the default owner.
- Determine behavior when owner is null.
- Verify global users.
- Verify group users.
- Verify individual users.
- Add regression tests.
Never assume all Krayin entities use the same ownership mechanism.
15. Two-Gate Authorization Example
Example user:
Role:
permission_type = custom
Permissions:
leads
leads.view
leads.edit
View permission:
group
Request:
GET /admin/leads/view/42
Authorization flow:
1. Authenticate user
2. Verify active status
3. Resolve role
4. Resolve route ACL
5. Check leads.view
6. Pass action authorization
7. Load lead 42
8. Resolve authorized user IDs
9. Check lead ownership/scope
10. Allow or deny
Therefore:
ACL permission exists
+
record belongs to authorized scope
=
request allowed
Having the ACL permission alone does not automatically grant access to every record.
16. Privilege Escalation Protection
Role administration is itself a privileged operation.
A non-administrator must not be able to create or assign privileges greater than the privileges they possess.
Conceptual permission ceiling:
Actor permissions
|
v
Target permissions
|
v
Target is a subset of Actor
If:
Actor:
leads.view
leads.edit
The actor must not create a role containing:
leads.view
leads.edit
leads.delete
because leads.delete is not in the actor's permissions.
This prevents privilege escalation through role administration.
17. Role Management Guards
When changing role-management functionality, inspect guards such as:
Acl::getAuthorizedItems()
canManageRole()
self-role edit protection
preventUnauthorizedRoleAssignment()
Expected security principles:
- Non-admin users cannot create unrestricted administrator roles.
- Non-admin users cannot grant permissions they do not possess.
- Non-admin users cannot edit a role broader than their own authority.
- Users cannot bypass permission restrictions through role assignment.
- Self-role modification must be protected against privilege escalation.
Always verify actual branch 2.2 implementation before changing these rules.
18. Data-Scope Escalation Protection
View permissions represent increasing authority.
Conceptually:
individual < group < global
A user should not be able to assign a broader data scope than the authorization rules allow.
When modifying scope assignment:
- Identify actor scope.
- Identify target scope.
- Check target's existing scope.
- Apply the branch 2.2 ceiling rules.
- Test escalation attempts.
- Test administrator behavior.
- Test self-edit restrictions.
19. Self-Privilege Protection
A user modifying their own account must not be able to use a normal account-edit operation to grant themselves greater authority.
Test:
Own role
Own view_permission
Own status
Pay special attention to:
role_id
view_permission
status
A privilege escalation test should attempt to modify the user's own authorization state directly through the request layer.
20. User Status
User status participates in authorization.
Conceptually:
active user
|
v
request continues
inactive user
|
v
session invalidation / logout
|
v
request denied
When modifying user-status authorization behavior, test:
- User is active.
- User becomes inactive.
- Existing session makes another request.
- New request is rejected.
- Session/token state is handled correctly.
21. Security Testing Strategy
Every authorization change must be tested at multiple levels.
Positive test
Verify an authorized user can perform the operation.
permission = present
scope = authorized
result = success
Negative ACL test
Remove the required permission.
permission = absent
scope = authorized
result = 401/denied
Negative scope test
Keep the ACL permission but use a record outside the user's scope.
permission = present
scope = unauthorized
result = 401/denied
Direct-request test
Do not rely only on UI.
Attempt the protected operation directly through:
- browser URL
- HTTP request
- API request where applicable
- POST/PUT/PATCH/DELETE request
- mass-action endpoint
Use the pest-testing skill for the test-authoring mechanics.
22. Required ACL Test Matrix
For a new permission, test:
| Scenario | Expected |
|---|---|
| Administrator | Allowed |
| Permission present | Allowed |
| Permission absent | Denied |
| UI permission absent | Action hidden |
| Direct route without permission | Denied |
| Direct POST without permission | Denied |
| Correct permission + unauthorized record | Denied |
| Correct permission + authorized record | Allowed |
Where applicable also test:
global
group
individual
23. Role Escalation Test Matrix
For role management:
| Scenario | Expected |
|---|---|
| Admin creates role | Allowed |
| Non-admin creates subset role | Allowed |
| Non-admin grants missing permission | Denied |
| Non-admin creates administrator role | Denied |
| Non-admin edits broader role | Denied |
| User edits own role | Denied |
| User assigns unauthorized role | Denied |
Adjust this matrix to the exact branch 2.2 implementation.
24. Scope Escalation Test Matrix
Test:
individual -> individual
individual -> group
individual -> global
group -> individual
group -> group
group -> global
global -> individual
global -> group
global -> global
Expected behavior must follow the branch 2.2 scope-ceiling implementation.
Do not assume that all transitions are allowed or denied without checking the actual controller logic.
25. Debugging Workflow
When an authorization bug is reported, follow this order:
1. Identify user
2. Identify role
3. Identify permission_type
4. Inspect role permissions
5. Identify view_permission
6. Identify requested route
7. Resolve route -> ACL key
8. Inspect Bouncer middleware
9. Check UI permission
10. Check controller authorization
11. Check data-scope filtering
12. Check ownership
13. Reproduce authorized case
14. Reproduce unauthorized case
15. Add regression test
Never fix an authorization bug by changing only the UI.
26. Adding a New ACL Permission
When implementing a new feature:
Step 1
Find similar existing permissions.
Step 2
Add the permission to the appropriate ACL configuration.
Step 3
Map all required routes.
For example:
index
create
store
edit
update
delete
mass actions
Do not assume one route automatically protects all related actions.
Step 4
Check menu permissions.
Step 5
Check Blade/component permissions.
Step 6
Verify middleware authorization.
Step 7
Verify controller/data authorization.
Step 8
Add automated tests.
27. Adding a New Role
Before creating a role:
Inspect actor permissions
|
v
Build requested permission set
|
v
Check requested is a subset of actor
|
v
Check role type
|
v
Check existing role restrictions
|
v
Create/update role
For non-administrators, never silently broaden privileges.
28. Code Review Rules
When reviewing a Krayin authorization PR:
Check:
- Does every privileged route have authorization?
- Is the ACL permission mapped correctly?
- Does the permission naming follow existing conventions?
- Is the UI check present where appropriate?
- Is server-side authorization enforced?
- Is record-level scope enforced?
- Can a user bypass authorization through a direct request?
- Can a user escalate through role management?
- Can a user escalate through view permission?
- Are existing roles backward compatible?
- Are regression tests included?
- Are administrator paths still correct?
- Are allow-list changes justified?
Treat missing server-side authorization as a security issue.
29. Important Distinction
Always distinguish these three concepts:
ACL
|
v
Can the user perform this action?
View Permission
|
v
Which records can the user access?
UI Permission Check
|
v
Should the interface show this action?
They are related but not interchangeable.
Correct:
ACL -> action authorization
Scope -> record authorization
UI -> presentation
Incorrect:
Button hidden -> operation secure
30. Security Principles
Follow these principles for every authorization change:
- Fail closed.
- Enforce authorization server-side.
- Never rely on hidden UI controls.
- Do not grant permissions implicitly.
- Prevent privilege escalation.
- Treat role management as a privileged operation.
- Treat data scope separately from action permissions.
- Validate direct requests.
- Add regression tests for authorization bugs.
- Follow existing Krayin branch 2.2 patterns.
- Inspect actual implementation before making architectural assumptions.
- Prefer the smallest safe change.
31. Expected Agent Behavior
When asked to modify Krayin authorization:
-
Inspect the existing implementation.
-
Identify the authorization layer involved.
-
Determine whether the issue concerns:
- ACL
- route mapping
- UI permission
- data scope
- ownership
- role escalation
- scope escalation
-
Find a comparable existing implementation.
-
Explain the affected authorization flow.
-
Make the smallest appropriate change.
-
Add/update regression tests.
-
Test both positive and negative authorization cases.
-
Check for privilege escalation.
-
Report any assumptions explicitly.
Never invent Krayin classes, routes, permission keys, or database behavior.
Always verify them against the branch 2.2 source.
32. Definition of Done
An authorization feature is complete only when:
- ACL permission is defined correctly.
- Required routes are mapped.
- Middleware authorization works.
- UI permissions are correct.
- Data scope is enforced.
- Record ownership is validated.
- Administrator behavior is verified.
- Unauthorized direct requests are rejected.
- Role escalation is prevented.
- Scope escalation is prevented where applicable.
- Regression tests exist.
- Existing functionality is not unintentionally restricted.
- Code follows Krayin branch 2.2 conventions.
33. Canonical Authorization Flow
Use this flow when explaining Krayin 2.2 authorization:
USER
|
+-- role_id ---------------> ROLES
| |
| +-- permission_type
| +-- permissions
|
+-- view_permission
|
v
DATA SCOPE
|
+-- global
+-- group ------> user_groups ------> groups
+-- individual
ADMIN REQUEST
|
v
Authentication
|
v
User status
|
v
Role
|
v
Administrator?
|
+-- YES ---------------> ACL action gate passed
|
+-- NO
|
v
Route -> ACL key
|
v
User has permission?
|
+--+--+
YES NO
| |
| 401
v
Controller
|
v
Record/data scope
|
v
Authorized owner?
|
+--+--+
YES NO
| |
ALLOW 401
The key architectural principle is:
ACTION AUTHORIZATION
+
DATA AUTHORIZATION
=
EFFECTIVE ACCESS
Do not collapse these into a single ACL concept.
版本历史
- 999b596 当前 2026-10-20 03:48


