Permissions (PBAC)
Design principles
- RBAC + ABAC hybrid: roles carry the standard grants, inline policies allow ad-hoc wildcard grants
- Weight precedence: an admin can only delegate permissions below their own rank
- App isolation with global visibility: expressed through the
GLOBALplaceholder - Deny first: a Deny statement always overrides Allow
- Permission points live in code, role policies live in the database
Permission registry
Codes follow the lowercase {app}:{resource}:{action} triple:
// src/app/oauth21/permission/index.js
const OAUTH_PERMISSIONS = createPermissionRegistry('oauth21', 'OAuth 2.1 authorization server', {
CLIENT: {
READ: { code: 'oauth:client:read', label: 'View clients', type: 'read' },
UPDATE: { code: 'oauth:client:update', label: 'Edit clients', type: 'write' }
},
TOKEN: {
READ: { code: 'oauth:token:read', label: 'View tokens', type: 'read' },
REVOKE: { code: 'oauth:token:revoke', label: 'Revoke tokens', type: 'high_risk' }
},
ADMIN: {
ALL: { code: 'oauth:admin:*', label: 'Admin wildcard', type: 'wildcard' }
}
});Roles
Hierarchy
superadmin (rank:99) → admin of every app (inherited automatically)
├── oauth_admin (rank:80) → authorization server admin
└── oauth_viewer (rank:10) → observer (granted by default)Definition
// src/app/oauth21/permission/roles.js
defineRoles([
{
code: 'oauth_viewer',
app_id: 'oauth21',
name: 'OAuth viewer',
rank_level: 10,
is_default: true, // granted automatically on authorization (see below)
policy: {
Version: '2026-06-06',
Statement: [
{ Effect: 'Allow', Action: [OAUTH_PERMISSIONS.CLIENT.READ, OAUTH_PERMISSIONS.TOKEN.READ] }
]
}
}
]);Default role (granted on authorization)
When a user authorizes an application for the first time, one "normal tier" role is granted automatically. It is declared in two places, resolved config first, code second:
default_roleinsrc/app/<app>/config.js— the primary source; editing config overrides code;is_default: trueon the role inroles.js— the secondary source, written next to the definition so it is hard to forget.
// src/app/oauth21/config.js
default_role: 'oauth_viewer',Resolution order (src/app/oauth21/dao/approval.dao.js): config.default_role → is_default → the lowest-ranked role in that permission namespace (must be rank_level <= 20). default_role: null means "intentionally grant nothing" (e.g. notice, which only has an admin role).
Closed applications: use null, assign roles manually
Some applications must not be reachable just because someone registered — the admin console is the obvious case: config.access declares a gate (anyPermission: ['admin:*']), and accounts without management capability are rejected during bind-session with access.denyMessage.
Such applications must use default_role: null and must not mark the role is_default:
- If the default role satisfies the gate (
admin_viewerholds every read code, soadmin:*matches), any registered user who clicks "authorize" can browse users, departments, roles and logs — the gate is decoration; - If it does not satisfy the gate, the user receives a role that cannot open a single page and gets a 403 on login — more confusing than granting nothing.
How roles are granted instead:
- an administrator assigns them in "Users → Assign roles" (
POST /admin/console/v1/users/roles/batch, append/remove, cross-application); - GLOBAL
superadmininherits every application's{appId}_adminautomatically viapermission-loader— no per-role assignment needed.
The boot-time auditDefaultRoles reports an error for "gate + default role", and __tests__/permission/role-rank-levels.test.js runs it against the real config.
Declaring roles means declaring the default role too
- Throws at registration (import time = boot failure): missing
app_id/rank_level/policy.Statement, twois_defaultroles for one app, or a default role above the normal tier (20). - Logged at boot (
auditDefaultRoles): a typo inconfig.default_role, a mismatch between the two declarations, or no declaration at all (falls back to lowest rank). The first two are errors, the last one is a warning. src/__tests__/permission/role-rank-levels.test.jsruns the audit against the real config and the realroles.js, so a mistake fails the test suite instead of a deployment.
Namespace note: the admin console's app id, OAuth client id and role namespace are all admin (the former console app was merged into admin on 2026-11-21; permission_app_id is gone). default_role uses a code from the admin namespace (e.g. admin_viewer).
rank_level has a hard ceiling
The range comes from src/models/iam/Role.js (validate: { min: 0, max: 99 }) — 99 is the maximum. Writing 100 does not fail locally, because once the role exists Role.findOrCreate() only takes the "update policy" branch. But a first deployment against an empty database (new environment, CI compose smoke test) really inserts, and then throws SequelizeValidationError: Validation max on rank_level failed — and because appsLoader is fail-fast, the application never boots. src/__tests__/permission/role-rank-levels.test.js guards this using the model's own boundaries (derived, not hard-coded 0/99).
A new rank must be strictly below your own
Both create-role and change-rank go through assertRankBelowActor: new rank < my highest rank, equal is rejected too. Rank is the gate for "who may manage whom" — same-rank roles are manageable: false in the list and rejected on the grant side (rank >= maxRank). Allowing "equal to myself" at write time therefore mints a role nobody can manage. That is why 99 only comes from code declarations (superadmin, poseadmin); the UI caps at 98.
On edit the check only fires when the value actually changes — the dialog re-submits untouched fields, and echoing the same rank is not "adjusting a rank".
Policy format
Statement form (recommended):
{
"Version": "2026-06-06",
"Statement": [
{ "Effect": "Allow", "Action": ["fw:config:read", "fw:config:write"] },
{ "Effect": "Deny", "Action": ["fw:config:delete"] }
]
}Loading permissions
loadUserPermissions(userId, appId)
→ query UserRole (current app + GLOBAL)
→ parse role.policy
→ superadmin gets the {appId}_admin role injected
→ query InlinePolicy (current app + GLOBAL)
→ merge allows / denies
→ cache in Redis for 5 minutesMatching engine
Single source of truth: src/framework/security/auth/permission/wildcard-match.js (isWildcardMatch), shared by the api/guard.js route guard and StpUtil._isMatch (previously two drifting copies).
// src/framework/security/auth/permission/wildcard-match.js (actual source)
function isWildcardMatch(pattern, target) {
if (typeof pattern !== 'string' || typeof target !== 'string') return false;
if (pattern === '*') return true;
if (pattern === target) return true;
if (!pattern.includes('*')) return false;
// escape all regex metacharacters first, then rejoin segments with .*
const regex = new RegExp(
'^' + pattern.split('*').map(seg => seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('.*') + '$'
);
return regex.test(target);
}
// deny first (direction: pattern = held permission pattern, target = concrete permission under test)
function matchSingle(perm, allows, denies) {
if (denies.some(d => isWildcardMatch(d, perm))) return false;
return allows.some(a => isWildcardMatch(a, perm));
}Semantics:
| Pattern | Meaning |
|---|---|
* | matches everything |
user:* | anything starting with user: (* spans : segments) |
user:*:read | mid-segment wildcards supported |
| otherwise | literal match — metacharacters are not interpreted; user:read never matches userXread (fixed 2026-11-01: the old implementation did not escape regex metacharacters) |
Delegation tiers
| Level | Rank | Scope | Authority |
|---|---|---|---|
| L1: super admin | 99 | GLOBAL | everything |
| L2: global admin | 80 | GLOBAL | cross-app administration |
| L3: app admin | 60 | specific_app | one app |
| L4: module admin | 40 | specific_app | part of one app |
OAuth 2.1 × PBAC
OAuth token scope = what the client asked for
PBAC allows / denies = what the user actually holds
effective permissions = token scope ∩ PBAC allows − PBAC deniesEven a token with the highest scope is blocked once an administrator issues a Deny statement.
StpUtil
Source: src/framework/security/auth/context/stp-util.js (business code should import it through the framework/security/auth/index.js facade re-export, not the subpath directly). Modeled after Java Sa-Token: all static methods, resolves the current request via AsyncLocalStorage — must be called inside an HTTP request context (throws outside ALS).
Two meanings of loginId — passing the wrong one fails silently
- Permission / role series operate on the current request user: no issue;
- Ban series (
disable/untieDisable/isDisable/checkDisable/getDisableTime):loginIdmust be the numeric primary key (the ban store keys by numericuserId:service) — passing the uid string returned bygetLoginId()does not error but never matches; resolveuser.idfrom uid in the admin DAO first; - Second-auth series (
openSafeetc.) already usesstate.user.userId(numeric) internally; just passservice.
Authentication & identity
| Method | Purpose | On failure |
|---|---|---|
getLoginId() | current user identifier (uid UUID; client token context returns the client name) | — |
check() | enforce login | throws 401 when not logged in |
checkRole(role) | role check (exact match, no wildcards; roles have no deny dimension) | throws 403 |
Permission checks (deny-first + wildcards)
Permission source is decoupled from the auth path: Session path reads the snapshot warmed at createSession; JWT path reads a real-time snapshot via perm-cache (numeric key + fingerprint check) — JWTs never embed permissions, so permission changes take effect immediately. Incomplete shapes are treated as empty sets (fail-closed); auth failures never masquerade as 500.
| Method | Purpose | On failure |
|---|---|---|
getPermissionList() | returns { allows, denies } (read-only reference, do not mutate) | — |
hasPermission(perm) | boolean test | — |
checkPermission(perm) | enforce one | throws NotPermissionException (403) |
checkPermissionAnd(...perms) | AND: all must pass | throws 403 on first failure; zero args throws explicitly (vacuous truth = no guard, likely a typo) |
checkPermissionOr(...perms) | OR: any must pass | throws 403 when none pass; zero args throws explicitly |
import { StpUtil } from '../../src/framework/security/auth/index.js';
StpUtil.hasPermission('user:admin:*'); // test: true / false
StpUtil.checkPermission('user:write'); // enforce: throws 403
StpUtil.checkPermissionAnd('a', 'b'); // AND: all must pass
StpUtil.checkPermissionOr('a', 'b'); // OR: any must passAccount bans (disable series, async)
Stored in Redis keyed by numeric userId:service, auto-unbanned at TTL expiry; service='login' blocks new logins, 'access' blocks requests, custom dimensions allowed. See the header of src/framework/security/auth/security/ban.js.
| Method | Purpose |
|---|---|
disable(loginId, service, time, opts?) | ban (seconds; -1 = permanent), opts: { reason, level, operator } |
disableLevel(loginId, service, level, time, opts?) | tiered ban by punishment level (level ≥ 1, business-defined) |
untieDisable(loginId, ...services) | unban, returns number of services actually untied |
isDisable(loginId, service) | banned? (ignores level) |
checkDisable(loginId, ...services) | enforce not banned; throws 403 (code=ACCOUNT_BANNED) |
getDisableTime(loginId, service) | remaining seconds: -2 = not banned, -1 = permanent |
Second authentication (openSafe series, async)
"Confirm again" mechanism for sensitive operations: after the business route verifies identity (re-enter password / OTP), openSafe opens a time window; safe routes pass inside the window, checkSafe throws 403 (code=SECOND_AUTH_REQUIRED) outside. Operates on the current request user; Redis failures fail closed (treated as not opened). See src/framework/security/auth/security/safe.js.
| Method | Purpose |
|---|---|
openSafe(service, safeTime?) | open the window (default 1800s), returns { openedAt, expireAt } |
isSafe(service) | inside the window? |
checkSafe(service) | enforce; throws 403 when not opened/expired (details.service for the frontend) |
closeSafe(service) | close proactively (after the sensitive operation, to shrink exposure) |
getSafeTime(service) | remaining seconds: -1 = not opened |
Why there is no StpUtil.login()
The login entry point is oauth21's login.service (full orchestration of password verification + createSession + cookie issuance). A placeholder login() once existed, but the ALS context only has the request — no reply — so cookies could never be sent; removed after the 2026-11-01 review.