feat: teach agents to author allowedActions for shared connections

[Esteban Chavez (eschavez)]

Follows bic/PowerPlatform-Managed-Host#1004 (authoring surface + validation) and #1077 (runtime policy plumbing):

• https://microsoft.ghe.com/bic/PowerPlatform-Managed-Host/pull/1004
• https://microsoft.ghe.com/bic/PowerPlatform-Managed-Host/pull/1077

Those PRs added a connector runtime policy contract that the plugin knew nothing about. A shared connection reference (non-empty sharedConnectionId) must declare allowedActions in ms.config.json -- per table for tabular sources, connector-level for action connectors -- and both ms app pack and ms app deploy hard-fail without it.

sharedConnectionId is written automatically by the CLI whenever the connector and auth type are shareable, so agents hit this failure without ever opting in. That framed the whole design: the agent can't wait to be told a connection is shared, it has to read the config back after every add.

Approach

One canonical reference wired into the two moments that matter. Because all eleven /add-* skills delegate to add-data-source, a single step there covers every connector.

• shared/allowed-actions.md (new) -- the source of truth. Why the field exists, how to detect a shared reference, both authoring shapes, least-privilege inference, verbatim validation errors, gotchas.
• add-data-source Step 4 -- reads ms.config.json back after every add; infers from actual usage in src/, proposes, confirms, writes.
• deploy Step 4 -- blocking preflight gate, so a missing policy surfaces before it can reach a failing deploy.
• list-connectors -- documents the real list-actions output columns and that id values feed connector-level allowedActions, filtered to behavior: Allow.
• Supporting updates to shared-instructions.md, connector-reference.md, the architect agent, memory-bank.md, and AGENTS.md.
• schemas/ms.config.schema.json -- adds allowedActions at both nodes. The published schema was stale and closed (additionalProperties: false), so a correctly authored config drew a red squiggle in VS Code.
• Version 2.0.2 -> 2.1.0 (new required agent behavior, not a fix).

Notes for review

Enforcement attribution. RP translates the declaration into an executionRestrictions policy; APIHub runs every connector request through it. The managed apps host only addresses the policy (URL rewrite + x-ms-shared-connection-id header). The app is not in the enforcement path -- the doc says this explicitly so agents stop trying to invent a client-side allow-list check.

Deferral path. /create-app Step 8 mandates no per-connector prompts, and at that point src/ doesn't exist so inference is impossible. Rather than let the two instructions contradict, a shared reference created during /create-app is recorded as policy pending and decided once app code exists. Safe because assertAppConfigSchemaValid is called only from the pack/deploy path -- Dev.ts never validates, so local iteration is unaffected, and /deploy's gate catches it before it matters.

node -e, not jq, for the deploy gate. jq isn't on PATH on Windows and the plugin treats PowerShell as first-class; a blocking gate depending on it would silently break. Node 22+ is already a hard prerequisite. Verified against fixtures covering missing per-table, whitespace-only entries, missing connector-level, clean, and non-shared configs.

Stage overlays intentionally untouched. StageConnectionReferenceSchema is .strict() and doesn't whitelist allowedActions, so stage-overlay.schema.json correctly has no such field.

Two follow-ups worth a look

1. The product doc docs/features/connector-runtime-policies.md shows ["GetItems", "PatchItem"] for a tabular example, which contradicts the get/post/patch/delete vocabulary. I followed the latter, corroborated by the Schema.ts comment (e.g. `["get", "delete"]`). That doc example may need a correction PR.
2. schemas/README.md says the schemas are generated, not hand-edited. I copied the exact shape from the product repo's regenerated JsonSchema snapshot, but the official path would be a regeneration PR.

[Copilot]

🟡 Changes recommended

Unresolved validation, schema-generation, and deployment-overlay issues remain.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

This PR teaches managed-app agents to author and validate least-privilege allowedActions policies for shared connections.

Changes:

• Adds canonical guidance and policy authoring flows.
• Adds add-data-source and deploy validation, including create-app deferral.
• Updates schemas, agent documentation, memory guidance, and plugin versions to 2.1.0.

File summaries

File	Summary	Final review findings
schemas/ms.config.schema.json	Adds connector- and table-level allowedActions.	Moderate (3 votes): update the source contract and regenerate the schema instead of hand-editing the generated snapshot.
plugins/microsoft-managed-apps/skills/list-connectors/SKILL.md	Documents action output and IDs.	No final review findings.
plugins/microsoft-managed-apps/skills/deploy/SKILL.md	Adds shared-policy preflight validation.	Moderate (3 votes): return a nonzero status on failure. Moderate (1 vote each): validate optional connector-level arrays, reject non-string entries, and account for deployment overlays.
plugins/microsoft-managed-apps/skills/create-app/SKILL.md	Documents deferred policy handling.	No final review findings.
plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md	Adds post-add policy authoring.	Moderate (2 votes): return a nonzero status on failure. Moderate (1 vote each): validate optional connector-level arrays and reject non-string entries.
plugins/microsoft-managed-apps/shared/shared-instructions.md	Adds shared-policy rules.	Nit (3 votes): clarify that allowing every action removes the restriction.
plugins/microsoft-managed-apps/shared/memory-bank.md	Tracks policy state and actions.	No final review findings.
plugins/microsoft-managed-apps/shared/connector-reference.md	Documents shared connection requirements.	Nit (1 vote): qualify the guidance to preserve the create-app deferral path.
plugins/microsoft-managed-apps/shared/allowed-actions.md	Provides canonical policy guidance.	Moderate (2 votes): return a nonzero status on failure, including the corresponding check at line 194. Moderate (1 vote each): validate optional connector-level arrays and reject non-string entries.
plugins/microsoft-managed-apps/agents/microsoft-apps-architect.md	Adds architectural policy guidance.	No final review findings.
plugins/microsoft-managed-apps/AGENTS.md	Registers the new shared reference.	No final review findings.
plugins/microsoft-managed-apps/.claude-plugin/plugin.json	Bumps the plugin version.	No final review findings.
.claude-plugin/marketplace.json	Bumps the marketplace version.	No final review findings.

Review details

Suppressed comments (9)

plugins/microsoft-managed-apps/shared/allowed-actions.md:195

• This repeats the misleading claim that declaring every action “grants exactly nothing.” It actually grants all operations available to the connection; the intended warning is that it narrows nothing. Please correct the wording so the least-privilege guidance is unambiguous.

Declaring every verb, or every action the connector exposes, passes validation and grants
exactly nothing — don't do it.

plugins/microsoft-managed-apps/shared/allowed-actions.md:93

• When a tabular reference also has an optional connector-level policy, this branch only checks the per-table arrays. A config with r.allowedActions: [] (or a whitespace entry) plus valid table policies therefore prints OK, even though the validation rules below require every present array to be non-empty and pack/deploy rejects it. Validate a present connector-level array in the t.length branch.

  if (t.length) {
    for (const [p, v] of t) if (!ok(v.allowedActions)) { bad++; console.log("MISSING per-table allowedActions: " + name + " -> " + p); }
  } else if (!ok(r.allowedActions)) { bad++; console.log("MISSING connector-level allowedActions: " + name); }

plugins/microsoft-managed-apps/shared/allowed-actions.md:85

• String(x).trim() lets numeric, boolean, or object entries pass this preflight even though ms.config.schema.json requires each allowedActions item to be a string. The check can report OK and defer the real schema failure to pack/deploy; require a string type before trimming.

const ok = (a) => Array.isArray(a) && a.length > 0 && a.every((x) => String(x).trim());

plugins/microsoft-managed-apps/shared/connector-reference.md:53

• This wording conflicts with the documented /create-app deferral path: when the app has no code yet, add-data-source is instructed to leave the policy unset and record it as pending rather than declare actions immediately. Qualify this bullet so agents do not prompt or write guessed actions during app creation.

- `sharedConnectionId` set → declare the actions before moving on.

plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md:174

• When a tabular reference also has an optional connector-level policy, this branch only checks the per-table arrays. A config with r.allowedActions: [] (or a whitespace entry) plus valid table policies therefore prints OK, even though the validation rules require every present array to be non-empty and pack/deploy rejects it. Validate a present connector-level array in the t.length branch.

  if (t.length) {
    for (const [p, v] of t) if (!ok(v.allowedActions)) { bad++; console.log("MISSING per-table allowedActions: " + name + " -> " + p); }
  } else if (!ok(r.allowedActions)) { bad++; console.log("MISSING connector-level allowedActions: " + name); }

plugins/microsoft-managed-apps/skills/add-data-source/SKILL.md:166

• String(x).trim() lets numeric, boolean, or object entries pass this preflight even though ms.config.schema.json requires each allowedActions item to be a string. The check can report OK and defer the real schema failure to pack/deploy; require a string type before trimming.

const ok = (a) => Array.isArray(a) && a.length > 0 && a.every((x) => String(x).trim());

plugins/microsoft-managed-apps/skills/deploy/SKILL.md:67

• When a tabular reference also has an optional connector-level policy, this branch only checks the per-table arrays. A config with r.allowedActions: [] (or a whitespace entry) plus valid table policies therefore prints OK, even though the validation rules require every present array to be non-empty and pack/deploy rejects it. Validate a present connector-level array in the t.length branch.

  if (t.length) {
    for (const [p, v] of t) if (!ok(v.allowedActions)) { bad++; console.log("MISSING per-table allowedActions: " + name + " -> " + p); }
  } else if (!ok(r.allowedActions)) { bad++; console.log("MISSING connector-level allowedActions: " + name); }

plugins/microsoft-managed-apps/skills/deploy/SKILL.md:59

• String(x).trim() lets numeric, boolean, or object entries pass this preflight even though ms.config.schema.json requires each allowedActions item to be a string. The check can report OK and defer the real schema failure to pack/deploy; require a string type before trimming.

const ok = (a) => Array.isArray(a) && a.length > 0 && a.every((x) => String(x).trim());

plugins/microsoft-managed-apps/skills/deploy/SKILL.md:58

• This preflight reads only the base ms.config.json, so it skips a base reference whose sharedConnectionId is supplied by a deployment overlay. The new overlay guidance says that case is still a shared effective reference whose base policy must satisfy validation; the gate currently prints OK and leaves the failure to pack/deploy. Inspect the selected ms.<deployment>.config.json overlay or explicitly handle overlay-based sharing here.

const refs = JSON.parse(fs.readFileSync("ms.config.json", "utf8")).connectionReferences || {};

• Files reviewed: 13/13 changed files
• Comments generated: 5
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.