feat(skills): RBAC extension — grant skills to roles (PR-2)

[philmerrell]

Scope — PR-2 of admin-managed Skills (RBAC extension)

Second PR of the admin-managed Skills feature. Extends the RBAC engine so skills are granted to AppRoles exactly like tools/models, and adds the server-side access service that resolves a user's accessible skills. No route, frontend, or runtime wiring yet (PR-3 = admin API, PR-4 = frontend, PR-5 = runtime) — so there is no user-visible behavior change: nothing grants or reads skills at runtime until a later PR, and the skill catalog is still empty.

Design spec (on develop): docs/specs/admin-skills-rbac-tool-binding.md — implements §4.2 (RBAC model), §5 (reverse lookup), §7 (access service); §11 PR-2.

Everything mirrors the existing tool RBAC path so the engine stays uniform.

Changes (apis/shared/rbac/)

• models.py
  • EffectivePermissions gains skills (+ to_dict/from_dict); from_dict defaults skills=[] so roles persisted before skills resolve to none.
  • AppRole gains granted_skills (+ to_dict/from_dict).
  • UserEffectivePermissions gains skills (trailing defaulted field, so existing construction sites are non-breaking).
  • AppRoleCreate/AppRoleUpdate gain grantedSkills; AppRoleResponse/EffectivePermissionsResponse gain grantedSkills/skills (defaulted → additive, non-breaking for the existing roles admin).
• admin_service.py — _compute_effective_permissions unions granted_skills across single-level inheritance; create_role threads granted_skills. New mirror methods: get_roles_granting_skill, add_skill_to_role, remove_skill_from_role.
• service.py — _merge_permissions unions skills (with "*" wildcard); new can_access_skill / get_accessible_skills.
• repository.py — _build_role_items writes SKILL_GRANT#{skill_id} reverse-lookup items, reusing the GSI2 keyspace (ToolRoleMappingIndex) with a disjoint SKILL# partition value (spec §5 — no new GSI). New get_roles_for_skill. (_delete_mapping_items already clears these on update/delete.)
• seeder.py — system_admin gets granted_skills=["*"] + effective_permissions.skills=["*"] (mirror of its tools/models wildcard); default explicitly [] (skills are gated, not open-by-default).

Access service (app_api/admin/services/skill_access.py)

New SkillAccessService mirroring ToolAccessService: get_user_allowed_skills, can_access_skill (wildcard), filter_allowed_skills (intersect against the DynamoDB-backed catalog via skills.freshness.get_all_skill_ids), check_access_and_filter. Drops the tool service's gateway_* prefix passthrough — skills have no dynamically-loaded form.

Bootstrap (scripts/seed_bootstrap_data.py)

seed_system_admin_role (the fresh-creation path that actually runs in real deploys; the in-app seeder.py only fires when the role is absent) now also writes grantedSkills=["*"], effectivePermissions.skills=["*"], and a SKILL_GRANT#* reverse-lookup item — so the full-access role has the skill wildcard end-to-end. Seeding the example skill catalog entries remains PR-5; this only concerns the system_admin role's grants.

Tests

• tests/rbac/test_app_role_skills.py — skills union merge, wildcard, can_access_skill, only-enabled-roles, inheritance merge, add/remove, reverse-lookup (direct + inherited classification).
• tests/shared/test_rbac_repository.py — granted_skills round-trip, get_roles_for_skill, tool↔skill partition non-collision (same id as both a tool and a skill), and stale-grant cleanup on update.
• tests/apis/app_api/admin/services/test_skill_access.py — wildcard expansion, unknown-skill filtering, intersection, deny, strict raise.
• tests/test_seed_system_admin_jwt.py — asserts the new grantedSkills/SKILL_GRANT#*.
• tests/rbac/conftest.py — make_app_role factory gains granted_skills/skills.

Verification

• ✅ uv run python -m pytest tests/ -v — full suite green (see below); ruff clean; import-boundary test passes.
• No infra change (reverse lookup reuses the existing GSI2), so no cdk/jest run needed.

Acceptance

A role can carry granted_skills; effective permissions union them (incl. inheritance + "*"); the reverse lookup answers "which roles grant this skill"; SkillAccessService resolves/filters a user's accessible skills. Wired into no route yet — zero behavior change.

🤖 Generated with Claude Code