awesome-copilot/skills/webmcpify/references/security.md

Security checklist

Apply at two points: before the manifest gate (classify + flag) and at the final audit (verify). Any unchecked box on a mutating: "server" tool blocks it. Client-only mutations (mutating: "client") still must pass the Trust boundary and Honesty & hints boxes.

Threat model in one paragraph

Any Chrome extension with host permissions — and any agent the user runs — can enumerate and execute your tools with the user's live session. The spec has no agent-identity mechanism. Page-visible strings (descriptions, labels, enum values, tool outputs) all enter the model's context, so they are prompt-injection surface in both directions. Design every tool as if it were a public, authenticated API endpoint — because effectively it is one.

Checklist

Trust boundary

• Every execute() calls only code paths the UI already uses — same endpoints, same validation, same authz, same rate limits. No new endpoints, no bypasses.
• No secrets, tokens, or privileged config inside tool code or descriptions.
• Role-based apps: tools registered per role/session and re-scoped on auth changes; nothing registered the current session couldn't do via the UI.

Human-in-the-loop

• No toolautosubmit on any state-changing form.
• No destructive/irreversible/payment tools at all in a first integration. If the human explicitly insists later: an in-page manual confirmation the user performs, PLUS a server-side two-step (short-lived confirm token). No client-side API exists that can force an agent to confirm — never rely on one.
• Initiation tools (start_*_flow) genuinely only navigate/open — they must not pre-execute any part of the mutation, and never carry readOnlyHint.

Production side effects (verification)

• Any verification that unavoidably causes a real production effect (e.g. an Origin-allow-listed mailer) has explicit gate approval recorded in the tool's approval.productionSideEffect — without it, the live path is skipped, never executed.
• Every such test payload is marked [webmcpify verification], and every caused effect is listed in report.md.
• The Origin-replay pattern (heal.md) lives only in the env-gated harness (WEBMCP_LIVE_MUTATIONS=1) — never in shipped code, never default-on in CI.

Honesty & hints

• Description says exactly what execute() does — no more, no less (agents make consent decisions from it).
• readOnlyHint: true ONLY on genuinely pure data reads (agents skip confirmation based on it; mislabeling is the worst single mistake).
• untrustedContentHint: true on every tool returning user-generated or external content.
• Outputs capped (~1.5k chars) and free of instruction-like content where possible.

Privacy

• Schemas request no more personal data than the equivalent visible form — agents auto-fill anything you declare (over-parameterization = silent profiling vector).

Containment

• HTTPS/secure context; Permissions-Policy tools left at default 'self'; cross-origin exposedTo/allow="tools" only with explicit human sign-off.
• Pages that must never expose tools (un-audited checkout, admin consoles you didn't inventory) can send Permissions-Policy: tools=() — suggest it in the report where relevant.
• No third-party WebMCP runtime added to the project; enumeration/execution surfaces (getTools/executeTool, legacy modelContextTesting) appear nowhere in shipped application code.
• Component-side webmcp:* event bridges attach only when isWebMCPAvailable() and validate their event payloads — a page script can dispatch the same CustomEvents; the bridge must not become an unvalidated side door into app actions.