/audit-permissions

name: audit-permissions
description: >-
  Audits existing table permissions on a Power Pages site by analyzing them against site code
  and Dataverse metadata. Generates an HTML audit report with findings grouped by severity
  (critical, warning, info, pass) and suggests fixes for issues found. Use when the user wants
  to review, verify, or check table permissions for security issues.
user-invocable: true
argument-hint: "[optional: specific table or concern]"
allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Agent
model: opus

> **Plugin check**: Run `node "${PLUGIN_ROOT}/scripts/check-version.js"` — if it outputs a message, show it to the user before proceeding.

Audit Permissions

Audit existing table permissions on a Power Pages code site. Analyze permissions against the site code and Dataverse metadata, then generate a visual HTML audit report with findings, reasoning, and suggested fixes.

Workflow

1. **Verify Site Deployment** — Check that `.powerpages-site` folder and table permissions exist 2. **Gather Configuration** — Read all web roles, table permissions, and site code 3. **Run Local Schema Validation** — Use the shared validator to detect invalid permission/site-setting YAML before deeper analysis 4. **Analyze & Discover** — Query Dataverse for relationships and lookup columns using deterministic scripts 5. **Run Audit Checks** — Compare permissions against code usage and best practices 6. **Generate Report** — Create the HTML audit report and display in browser 7. **Present Findings & Track** — Summarize findings, record skill usage, and ask user if they want to fix issues

**Important:** Do NOT ask the user questions during analysis. Autonomously gather all data, then present findings.

Task Tracking

At the start of Step 1, create all tasks upfront using `TaskCreate`. Mark each task `in_progress` when starting and `completed` when done.

| Task subject | activeForm | Description | |-------------|------------|-------------| | Verify site deployment | Verifying site deployment | Check .powerpages-site folder and table permissions exist | | Gather configuration | Gathering configuration | Read web roles, table permissions, and site code | | Run local schema validation | Validating local permissions schema | Run shared validator against existing table permission and site setting YAML | | Discover relationships | Discovering relationships | Query Dataverse for lookup columns and relationships | | Run audit checks | Running audit checks | Create per-table tasks and run checklist (A–K) for each table, then cross-validate | | Generate audit report | Generating audit report | Create HTML report and display in browser | | Present findings | Presenting findings | Summarize results, record usage, and offer to fix issues |

**Note:** The "Run audit checks" phase creates **additional per-table tasks** dynamically in Step 4.2. These per-table tasks track the systematic A–K checklist for each table independently.

---

Step 1: Verify Site Deployment

Use `Glob` to find:

• `**/powerpages.config.json` — identifies the project root
• `**/.powerpages-site/table-permissions/*.tablepermission.yml` — existing permissions

If no `.powerpages-site` folder exists, stop and tell the user to deploy first using `/deploy-site`. If no table permissions exist, note this as a critical finding (the site may have no data access configured) and continue the audit — there may still be code references that need permissions.

---

Step 2: Gather Configuration

2.1 Read Web Roles

Read all files matching `**/.powerpages-site/web-roles/*.yml`. Extract `id`, `name`, `anonymoususersrole`, `authenticatedusersrole` from each.

2.2 Read Table Permissions

Read all files matching `**/.powerpages-site/table-permissions/*.tablepermission.yml`. For each permission, extract:

• `entityname` (permission name)
• `entitylogicalname` (table)
• `scope` (numeric code)
• `read`, `create`, `write`, `delete`, `append`, `appendto` (boolean flags)
• `adx_entitypermission_webrole` (array of web role UUIDs)
• `contactrelationship`, `accountrelationship` (if Contact/Account scope)
• `parententitypermission`, `parentrelationship` (if parent scope)

2.3 Analyze Site Code

Search the site source code for:

• Web API calls (`/_api/`)
• Lookup bindings (`@odata.bind`)
• File uploads (`uploadFileColumn`, `uploadFile`, `upload*Photo`, `upload*Image`)
• `$expand` usage (`$expand`, `buildExpandClause`, `ExpandOption`)

Also check for `.datamodel-manifest.json` in the project root for the authoritative table list.

Build a map of: which tables are referenced in code, which CRUD operations are performed on each, which lookup relationships are used, and which related tables are fetched via `$expand` (these need read permissions too).

2.4 Run Shared Schema Validator

Run the shared validator against the existing site:

node "${PLUGIN_ROOT}/scripts/validate-permissions-schema.js" --projectRoot "<PROJECT_ROOT>"

Parse the JSON output and carry the findings into the audit. Treat:

• `error` findings as **critical**
• `warning` findings as **warning**
• `info` findings as **info**

These findings should be included in the final audit report even if the later code/Dataverse analysis also finds additional issues.

If the validator reports wildcard field access in a `Webapi/<table>/fields` setting, add this critical finding to the report:

• **Severity:** `critical`
• **Title:** `Unsupported wildcard Web API fields for <table>`
• **Reasoning:** The fields setting uses wildcard access, which is unsupported beginning September 14, 2026
• **Fix:** Replace the wildcard using `${PLUGIN_ROOT}/references/webapi-field-allowlist.md`: LogicalNames for ordinary columns, `_<LogicalName>_value` for lookup reads, and exact Navigation Properties used by `@odata.bind`
• **Details:** Include the site-setting file path and setting name from the validator finding

After Step