add-permission-group-item
Add a new governed item to Sim's enterprise permission groups — a boolean restriction, an allowlist, or a denylist — wired end-to-end from the field registry through the capability rule to the server gate that actually refuses. Use when adding a key to `PERMISSION_GROUP_FIELDS` or a capability to `CAPABILITY_RULES`.
simstudioai · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add simstudioai/sim --skill add-permission-group-itemAbout this skill
name: add-permission-group-item
description: Add a new governed item to Sim's enterprise permission groups — a boolean restriction, an allowlist, or a denylist — wired end-to-end from the field registry through the capability rule to the server gate that actually refuses. Use when adding a key to PERMISSION_GROUP_FIELDS or a capability to CAPABILITY_RULES.
argument-hint:
Add Permission Group Item Skill
You are adding one governed item an organization admin can withhold from a cohort of members. One entry in apps/sim/lib/permission-groups/fields.ts produces the write schema, the read schema, the PermissionGroupConfig type, the defaults, the tolerant parser, and (for a boolean) the admin editor row.
The registry does not produce enforcement. Twelve keys once shipped with a checkbox, a hint, and no server check — an organization that ticked hideCopilot believed it had withheld a capability while every route still answered. Hence the enforcement field, the required capability field on every operation, and scripts/check-permission-group-enforcement.ts. You are done when something refuses, not when the key parses.
Read the system first
lib/permission-groups/fields.ts— registry, three field builders,permissionGroupConfigSchema,tolerantArray,parsePermissionGroupConfig. There is notypes.ts(folded in here); the DB constraint maps live inconstraints.tslib/permission-groups/capabilities.ts—CAPABILITY_IDS,CAPABILITY_RULES,capabilityRefusal,refuseCapability, the static/parameterized splitlib/permission-groups/capability-assertions.ts— the sanctioned assertion API; re-exportscapabilityRefusal.capability-error.tsholds the thrown error,capability-response.tsthe raw-route 403lib/permission-groups/integration-allowlist.ts— the canonicalizing allowlist algebra, over the generatedblock-successors.generated.tslib/permission-groups/resolve.server.ts—resolveWorkspaceGroup,resolveVerifiedUserAccessControlContext,getUserPermissionConfig,getUserPermissionConfigForOrganization,mergeEnvAllowlist.ee/access-control/utils/permission-check.tsre-exports it and keeps the executor gateslib/permission-groups/config-scope.server.ts(resolvePermissionGroupConfig, the per-request memo every assertion resolves through) andrequest-scope.server.ts(withPermissionGroupScope, deliberately import-free becausewithRouteHandlerimports it)lib/core/application/workspace-operation.tsandworkspace-authorization.ts— the requiredcapabilityfield, and the funnelscripts/check-permission-group-enforcement.ts,check-application-graph.ts,check-capability-subject.ts
(Paths are under apps/sim/ unless noted.)
Step 0: Decide what kind of thing it is
| Kind | Builder | Default | Semantics |
|---|---|---|---|
| Boolean restriction | booleanRestriction(enforcement, feature) | false | true withholds. Name it hideX / disableX, never allowX |
| Allowlist | allowlist(item, enforcement, { limited, empty }) | null | null allows everything; a list names the only permitted members; [] permits none |
| Denylist | denylist(item, enforcement, phrasing) | [] | Empty permits everything; members are refused |
Allowlist when the safe posture is "only what the admin named" and the member set is enumerable (auth modes, connectors, model providers). Denylist when it is "everything except" and the set is open-ended (tool ids, models — an allowlist over a thousand tools grows a hole every time a tool ships).
Which mechanism refuses? The enforcement value is a claim the audit checks.
| Value | Meaning |
|---|---|
'capability' | An operation declares a capability whose rule reads the key; the funnel refuses before the use case runs. Default answer for anything reachable through an application operation |
'executor' | Read per block/tool/model at run time by assertPermissionsAllowed in ee/access-control/utils/permission-check.ts. Governs what a run may do, which no operation gate can express (one API call executes fifty blocks). Only allowedIntegrations, allowedModelProviders, deniedModels, deniedTools live here. The matching primitives these four keys are compared with live in lib/permission-groups/ — block-access.ts (exemptions, superseded-version resolution), operation-access.ts (createToolAccessGate), model-access.ts (createModelAccessGate), integration-allowlist.ts — shared so the run-time gate and the editor/Copilot projections cannot drift. allowedIntegrations alone is also asserted outside a run, by assertSelectorIntegrationAllowed (lib/selectors/server/integration-access.ts) ahead of the provider call in selectors.execute, against the selector's own resourceServiceId / integrationBlockTypes rather than the credentials it accepts — reaching a provider API is a use of the integration, so a key here can still need a non-run enforcement site |
'ui-only' | Hides a surface without withholding it. Almost never right — nothing ships as ui-only. Justify in the enforcement comment why a determined caller reaching the data is acceptable, and expect review to question it |
Is it per-operation at all? personal_api_key.use is the one capability that is not: it withholds a principal kind across every operation, checked in the funnel's personal_api_key branch (workspace-authorization.ts) and again in app/api/v1/middleware.ts, so no operation declares it and its absence from every capability: field is correct rather than a hole.
Is the decision knowable from the config alone? A rule needing a request value (an auth mode, a connector id) is parameterized and cannot be declared on an operation — see Step 3.
Is it a gate or a projection? A key that withholds fields from a response rather than the response is a projection. hideTraceSpans and hideCostInfo work thi