Nocobase Acl Manage

Goal

Turn ACL and permission governance into a task-driven workflow so users can ask for business outcomes while the skill handles:

• CLI command selection and argument shaping
• capability checks and safety guards
• write confirmation and readback evidence
• risk-oriented explanation for high-impact changes

Scope

• This skill is CLI-first for reads and writes.
• Tasks are grouped into five domains:
• role
• global role mode
• permission, including Portal entry access
• user
• risk assessment
• Every write task follows plan -> confirm -> apply -> readback.
• global role mode is treated as a global system policy, not a per-role field.

Non-Goals

• Do not bypass CLI by calling direct REST endpoints.
• Do not mutate ACL through ad-hoc database operations.
• Do not create temporary script files to execute ACL writes.
• Do not invoke other skills for env/plugin bootstrap; use direct nb commands in this skill.
• Do not hide high-impact blast radius (global mode, broad snippets, broad strategy actions).
• Do not claim one-click coverage for workflows that require governance review.

Canonical Task Model

A) Role Domain

B) Global Role-Mode Domain

role_mode enum mapping:

• default: independent role usage (no union mode)
• allow-use-union: union mode available, role switching still allowed
• only-use-union: force union mode for multi-role users

C) Permission Domain

D) User Domain

E) Risk Domain

Role creation interaction policy:

• always create with the same default read-only baseline (role.create-blank)
• role_name must use NocoBase role uid format with r_ prefix
• if user input has no r_ prefix, normalize to r_<normalized_name> and show normalized value in confirmation/readback
• do not ask users to choose role archetypes (for example, "employee/auditor/manager/custom")
• if role_name is provided, execute creation directly
• when the request includes the current resolved Portal, resolve it before confirmation; after role creation, immediately grant that role explicit entry to the Portal through permission.portal.access.set, then read back both the role and exact Portal association
• treat a failed Portal grant as partial completion and do not claim the new role is ready for that Portal
• when no Portal context is available, do not guess or grant access to an unrelated Portal; after creation succeeds, move to permission assignment guidance
• permission follow-up options: system snippets, desktop routes, Portal entry access, data-source global strategy, data-source resource strategy

Resource permission interaction policy:

• before executing permission.data-source.resource.set, always confirm:
• data source key (main by default unless user specifies another)
• resolved target collection(s)
• action list
• data scope (all by default when user does not specify)
• disambiguate operation verbs from ACL action names:
• phrases like add table permission / configure permission describe the operation, not ACL action create
• only treat create as selected action when user clearly asks for data-creation capability (can create records / can add data)
• user does not need to provide exact technical collection names
• accept business names or keywords as collection_hint(s)
• resolve real collection names from the selected data source collection list
• if matching is ambiguous, present candidates and ask user to choose
• if no match is found, ask user for a clearer business keyword
• resolve scope binding before write:
• if user does not specify scope, default to all
• all -> built-in scope key=all id in target data source
• own -> built-in scope key=own id in target data source
• custom -> user-specified scope id (or resolved scope key)
• do not leave action scope as null when final scope is all or own
• write completeness (hard rule):
• for permission.data-source.resource.set, execute one complete write payload per target collection
• the write payload must include usingActionsConfig: true
• the same payload must include the final actions[] set, with explicit scope binding (scopeId or scopeKey) for all|own and explicit non-empty fields arrays for field-configurable actions
• do not stage writes as "set actions first, then patch fields/scope/usingActionsConfig"
• before any write, show confirmation summary (data source + resolved collections + actions + scope)
• when scope is defaulted, confirmation must explicitly state scope=all (default) and allow user override
• if any required item is missing or unresolved, ask user first and do not write
• default field rule: all fields
• full-field default must be written as explicit field-name lists resolved from target collection metadata
• do not use fields=[] as a full-field default marker
• if user did not provide field-level restrictions, apply full-field permission for each selected action
• apply full-field default to every selected action that supports field configuration (create, view, update, export, importXlsx)
• full-field default must include system fields returned by metadata (for example sort, createdBy, createdById, updatedBy, updatedById) unless user explicitly asks to exclude them
• use technical field names (field.name) for writes, never display titles
• do not auto-drop fields only because they are system/context/relation/hidden; only exclude when user intent explicitly restricts them
• view action must default to all fields for that collection
• if user explicitly asks for all permissions on a collection, resolve runtime available actions and confirm expanded action set before write

Portal permission interaction policy:

• manage only whether a role may enter an existing custom Portal; do not treat this task as Portal-internal route, menu, page, region, control, or data permission configuration
• resolve one real enabled Portal with nb portal list -j before planning a write; accept a uid, name, path, title, or business hint, but require disambiguation when matches are not unique
• use the official roles.multiPortals:list/add/remove association actions exposed as nb api acl roles multi-portals ...; do not write the rolesMultiPortals through table directly
• Portal access for a union role is allowed when any effective role has the explicit Portal grant; root can enter all enabled Portals
• allowNewMultiPortal is a separate future-Portal default policy and is not evidence that a role can enter a specific existing Portal
• after a write, read back the role's Portal association and verify the exact Portal uid is present or absent
• if the Multi-portal capability or roles multi-portals runtime commands are unavailable, stop with capability guidance; do not emulate Portal grants in another collection

Input Contract

Default behavior when user says you decide:

• choose role tasks for role intent
• choose permission tasks for policy intent
• choose user tasks for assignment intent
• choose risk tasks for assessment intent
• for role creation intent, always use role.create-blank first
• data_source_key=main
• strict_mode=safe

Filter Authoring Gate

Before authoring any reusable custom ACL scope, scope_filter, user_filter, or other persisted permission filter, load the nocobase-utils skill with topic filter, then read Filter Condition Format in the current task. Resolve every terminal field's live frontend interface/type and use only that group's operator allowlist. Date fields use date-specific comparison operators; $lt, $lte, $gt, and $gte remain number-only even when the backend accepts them. Do not apply this UI-displayable allowlist mechanically to fixed CLI locator objects such as --filter-by-tk or direct control filters documented by a command.

Mandatory Clarification Gate

• max clarification rounds: 2
• max questions per round: 3
• never execute writes before required inputs are complete
• for role.create-blank, ask only for role_name when missing; do not ask role-type questions
• for write tasks with role_name, normalize to r_* uid and echo normalized value in confirmation
• for permission.data-source.resource.set, default data_source_key=main when omitted unless user explicitly provides another data source
• for permission.data-source.resource.set, if collection hint cannot be resolved or is ambiguous, ask follow-up questions before write
• for permission.data-source.resource.set, if actions are incomplete, ask follow-up questions before write
• for permission.data-source.resource.set, if scope is omitted, apply default all and require confirmation before write
• for permission.data-source.resource.set, if custom scope is requested but scope id/key is unresolved, ask follow-up questions before write
• for Portal writes, do not continue until one enabled custom Portal is resolved
• for permission.data-source.resource.set, if user has not confirmed the final write plan, do not write
• if user asks to set role mode for a specific role, clarify and normalize to global mode change
• if task implies writes and target identity is missing, stop and ask first
• if CLI returns auth errors (401, 403, Auth required), stop and instruct the agent to hand off environment/auth recovery to nocobase-env-manage

Workflow

1. Resolve intent and normalize task.

• map aliases to canonical tasks
• map natural-language role mode wording to default/allow-use-union/only-use-union
• normalize create-role wording to role.create-blank baseline first, then permission assignment

2. Capability gate (CLI).

• confirm direct nb CLI is available in PATH
• command assembly guard:
• command form must be nb <command> [subcommand ...] [flags ...]
• first token after nb must be a command (for example env or api), not a flag such as -e/-t/-j
• wrong: nb -e local
• correct: nb api resource list --resource users -e local -j
• raw JSON input guard (PowerShell/runtime):
• prefer structured body flags (for example --resources, --actions) over inline --body when possible
• if raw JSON body is required, prefer --body-file over inline --body
• --body-file content must be valid JSON encoded as UTF-8 without BOM
• if inline --body fails JSON parsing in PowerShell, regenerate payload as --body-file and retry once
• avoid Bash-style escaped JSON in PowerShell (for example {\"k\":\"v\"}), it may be parsed as invalid JSON
• policy payload guard (hard rule for independent resource writes):
• preflight must block api acl roles data-source-resources create|update and api acl roles apply-data-permissions when payload is missing or invalid (--body-file preferred, --body compatible)
• for those writes, payload must include usingActionsConfig: true and non-empty actions[]
• for actions create/view/update/export/importXlsx, each action must carry non-empty fields[]
• for every action item, scope binding must be explicit via one of:
• scopeId (for explicit id binding)
• scopeKey (for key-based resolution, such as all/own)
• scope.{id|key} (compatibility readback payload)
• if user intent is scope all or own, readback must show resolved non-null scopeId
• if guard fails, stop before CLI execution and return a fixable error
• parameter safety guard:
• command shape guard for resource permissions:
• roles data-source-resources only has create|get|update; do not call list
• for roles data-source-resources get|update, locator must be one of:
• --filter-by-tk <resource_config_id>
• --data-source-key <data_source_key> --name <collection_name>
• for action-level independent-permission readback, use roles data-source-resources get ... --appends actions
• for unified independent-permission writes (single or batch collections), prefer roles apply-data-permissions --filter-by-tk <role_name> --body-file <path>
• for roles data-sources-collections list, use --data-source-key <data_source_key> as the default locator; use --filter only for compatibility
• for collection/field resolution, prefer nb api resource list --resource collections --filter '{}' --appends fields -j as primary metadata source
• for roles desktop-routes add, request body must be JSON array of numeric route ids
• never execute write commands with uncertain, unresolved, or type-mismatched parameters
• Portal permission command guard:
• discover Portals through nb portal list -j
• require nb api acl roles multi-portals list|add|remove to resolve from the current runtime Swagger cache
• pass only the resolved Portal uid to add or remove; do not pass a title, path, or guessed uid
• perform a current-association read before the write and an immediate readback after it; an already-satisfied allow/deny request is a no-op
• lock execution base-dir before any ACL discovery/write (use one stable project root for the whole task)
• run execution guard sequence before ACL writes:
• nb env list
• nb env update <current_env_name>
• nb api acl --help
• nb api acl roles --help
• fail-closed policy:
• if nb api acl --help or nb api acl roles --help fails, stop and return capability-boundary message; do not switch to ad-hoc script execution.
• confirm current env context through direct CLI: run nb env list and resolve current env from the row marked with *
• if no env is configured/current, stop writes and instruct the agent to call nocobase-env-manage, then rerun the ACL task after env recovery
• if runtime command cache is missing/stale or command schema changed, run nb env update <current_env_name>
• if runtime refresh fails, stop writes and return the CLI error; instruct the agent to call nocobase-env-manage for env/auth/runtime recovery, or nocobase-plugin-manage only if the CLI error explicitly says a plugin must be enabled
• if token is missing/invalid, stop writes and instruct the agent to call nocobase-env-manage
• resolve runtime command names via intent-to-tool-map-v1 and command help discovery

3. Plan before writes.

• list proposed change set, readback checkpoints, and blast radius
• for high-impact writes require explicit confirmation
• for resource permission writes, include:
• data source key
• resolved target collection list
• action list
• scope choice (default all when omitted)
• resolved scope binding (scopeId / scope key)
• field policy (all fields by default unless user provided restrictions)
• resolved full-field list per action when field restrictions are omitted

4. Execute one task at a time.

• keep writes minimal and scoped
• prefer ACL-specific runtime commands generated from swagger
• for permission.data-source.resource.set, prefer unified write via nb api acl roles apply-data-permissions with complete resources[] payload; use roles data-source-resources create|update only as compatibility path

5. Readback verification.

• verify target data changed as requested
• include concise evidence blocks
• for independent resource permissions, use nb api acl roles data-source-resources get ... --appends actions when verifying action-level scope/fields
• for Portal entry access, read back the exact roleName + multiPortalUid grant and distinguish explicit access from allowNewMultiPortal

6. Risk and boundary reporting.

• return high-impact notes even on success
• use friendly boundary messaging for unsupported paths

Tooling Policy

Primary write path:

• ACL-specific CLI runtime commands (swagger-generated)
• for user-role membership writes, prefer dedicated ACL command path first (nb api acl roles users add/remove)

Guarded fallback path (user-role membership only):

• allowed only when dedicated ACL membership command is unavailable and allow_generic_association_write=true
• use generic nb api resource update/list only for users.roles association operations
• mandatory readback after write

Hard restrictions:

• never use direct HTTP fallback
• never use direct database mutation
• never use generic resource commands for ACL policy writes when ACL-specific runtime commands exist
• determine ACL support by checking nb api acl --help and nb api acl roles --help in the same locked base-dir before concluding capability status
• never create temporary .js/.ps1/.sh executor scripts to bypass runtime command discovery

Safety Gate

High-impact ACL actions:

• changing global role mode
• broad system snippets (ui.*, pm, pm.*, app)
• broad data-source actions (destroy, broad export/import grants)
• role assignment to many users

Safety rules:

• keep high-impact writes behind explicit confirmation
• include blast-radius summary before apply
• always perform readback verification after write

Capability Boundary Messaging

When a scenario is not supported by current CLI/runtime/tool policy:

• This scenario is currently blocked by capability or governance policy in this skill.
• Please complete the operation in NocoBase admin UI, or enable the guarded fallback option if available.
• If you want, I can provide exact UI navigation steps and field suggestions.

Verification Checklist

• task normalized to canonical task
• required inputs complete before writes
• CLI capability gate passes (env context available via direct nb env list, runtime commands resolvable)
• environment/auth prerequisites are available or explicit handoff guidance is emitted
• runtime command names resolved from command map/help
• execution guard evidence includes locked base-dir plus nb env list, nb env update <current_env_name>, nb api acl --help, and nb api acl roles --help
• every write has immediate readback evidence
• for permission.data-source.resource.set, data source + resolved collections + actions + scope were confirmed before write
• when user did not provide scope, confirmation/readback shows all as the applied default scope
• for permission.data-source.resource.set, readback confirms usingActionsConfig=true and action-level scope/fields in the same write cycle
• for action-level verification of independent permissions, readback command includes --appends actions
• for scope=all|own, readback shows non-null scopeId and matching scope key
• when field rules were omitted by user, full-field defaults were applied explicitly as non-empty field-name lists
• when full-field defaults are used, readback field lists match requested names and do not silently lose system fields
• command-level preflight blocks malformed independent-resource payloads before execution (missing/invalid usingActionsConfig, actions, scope binding scopeId|scopeKey, fields)
• roles data-source-resources get|update locator is explicit (filterByTk or data-source-key + name) before execution
• collection/field metadata is resolved through resource collections read path; roles data-sources-collections list is compatibility-only for role-facing view
• roles desktop-routes add uses JSON array body with numeric route ids
• Portal access writes resolve one enabled Portal, use exact role/Portal keys, and have immediate readback
• no write executes with uncertain or type-mismatched parameters
• global role-mode tasks do not require role_name
• every persisted custom scope/user filter was checked against the terminal field's frontend operator group; no date field uses a number comparison operator
• boundary messages are clear and actionable

Minimal Test Scenarios

1. global.role-mode.get and global.role-mode.set with readback.
2. role.create-blank then verify role exists and has conservative defaults.
3. permission.data-source.global.set and verify strategy actions.
4. permission.data-source.resource.set with business collection name should auto-resolve real collection name(s) from target data source.
5. permission.data-source.resource.set with ambiguous collection match should ask for disambiguation before write.
6. permission.data-source.resource.set with missing actions should ask for clarification before write.
7. permission.data-source.resource.set with missing scope should default to all, show this in confirmation, and allow user override before write.
8. permission.data-source.resource.set with view and no field restrictions should apply full-field permission by default via explicit non-empty field lists.
9. permission.data-source.resource.set with scope=all should write explicit built-in scope binding (non-null scopeId for key=all).
10. permission.data-source.resource.set should require pre-write confirmation including data source + resolved collections + actions + scope.
11. permission.data-source.resource.set should write independent policy in one complete payload (usingActionsConfig + actions + scope + fields), not multi-step patching.
12. user.assign-role in strict mode should use dedicated membership command when available; if unavailable, block with boundary guidance.
13. user.assign-role guarded fallback should run only when dedicated command is unavailable and guarded mode is explicitly enabled.
14. risk.assess-role should return score + evidence + recommendations.
15. Full-field default should preserve system fields in readback when metadata includes them.
16. Wrong base-dir or missing runtime command cache must fail-closed with boundary message, not ad-hoc script fallback.
17. permission.portal.access.set should grant and revoke one explicit role/Portal relation with readback.

Reference Loading Map

References

• Intent Presets v1
• Intent To Tool Map v1
• Execution Guard Template
• Result Format v1
• ACL Configuration Details
• Table Independent Permissions
• Portal Access
• Filter Condition Format
• ACL Capability Test Plan
• ACL Test Playbook
• ACL Refactor Plan v2
• ACL Capability Tests
• NocoBase ACL Handbook [verified: 2026-04-11]