Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Browser & automation

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-item

About 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 no types.ts (folded in here); the DB constraint maps live in constraints.ts
  • lib/permission-groups/capabilities.ts — CAPABILITY_IDS, CAPABILITY_RULES, capabilityRefusal, refuseCapability, the static/parameterized split
  • lib/permission-groups/capability-assertions.ts — the sanctioned assertion API; re-exports capabilityRefusal. capability-error.ts holds the thrown error, capability-response.ts the raw-route 403
  • lib/permission-groups/integration-allowlist.ts — the canonicalizing allowlist algebra, over the generated block-successors.generated.ts
  • lib/permission-groups/resolve.server.ts — resolveWorkspaceGroup, resolveVerifiedUserAccessControlContext, getUserPermissionConfig, getUserPermissionConfigForOrganization, mergeEnvAllowlist. ee/access-control/utils/permission-check.ts re-exports it and keeps the executor gates
  • lib/permission-groups/config-scope.server.ts (resolvePermissionGroupConfig, the per-request memo every assertion resolves through) and request-scope.server.ts (withPermissionGroupScope, deliberately import-free because withRouteHandler imports it)
  • lib/core/application/workspace-operation.ts and workspace-authorization.ts — the required capability field, and the funnel
  • scripts/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

KindBuilderDefaultSemantics
Boolean restrictionbooleanRestriction(enforcement, feature)falsetrue withholds. Name it hideX / disableX, never allowX
Allowlistallowlist(item, enforcement, { limited, empty })nullnull allows everything; a list names the only permitted members; [] permits none
Denylistdenylist(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.

ValueMeaning
'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

Read the complete source ↗