Security And Idempotency
Mika keeps security decisions at the host boundary: browser forms, provider webhooks, admin runners, and agent projections each need different protection.
Browser forms should keep Astro’s origin checks enabled and add host guards for rate limits, bot checks, account policy, and feature gates.
Provider webhooks need raw-body verification through provider adapters.
Trusted, admin, and agent runner paths need idempotency where Mika marks it as required. Idempotency records live in host durable storage.
Protected agent tools require host-owned auth, confirmation, replay handling, and provider/payment verification.
Idempotency keys come from the calling surface. Browser/Action and trusted projections can place them in the MikaRequestContext; ACP checkout handlers read the Idempotency-Key request header; EmDash admin runner calls read the Idempotency-Key header first and otherwise use invocationId. Durable records live in host storage: session checkout metadata, stock events, workflow/admin audit rows, webhook records, and ACP session stores.
Guard And Policy Hooks
Section titled “Guard And Policy Hooks”Use createMikaActions({ guard }) for host checks that run before an Astro Action calls Mika: rate limits, account/session checks, bot checks, and temporary feature gates.
Use operationPolicy when the same authorization rule should apply at the operation layer, including plugin routes or trusted runner paths that dispatch through operation descriptors. A policy can allow, forbid, or return a Mika failure envelope.
Boundary Checklist
Section titled “Boundary Checklist”| Surface | Baseline |
|---|---|
| Astro form actions | Keep Astro’s origin check enabled, then add createMikaActions({ guard }) for host rate limits, account checks, bot checks, and feature gates. |
| Provider webhooks | Use a host endpoint and provider adapter verification over the raw request body before accepting payment or subscription state. |
| Return paths | Use Mika’s same-origin return-path sanitizer for checkout, magic links, and post-auth redirects; it rejects open redirects, protocol-relative URLs, and dot-segment traversal. |
| Checkout success | Confirm provider-backed order status through Mika checkout status; do not trust the return URL alone. Checkout start can replay safely when a host idempotency key is present. |
| Checkout cancel | Treat as an abandonment/UX surface that may call checkout.cancel; do not treat it as payment proof. Release expired stock reservations from scheduled maintenance. |
| Admin actions | Run through the trusted EmDash actions runner and require idempotency keys where Mika marks them required. |
| Agent/tool projections | Keep host-owned auth, confirmation, replay handling, provider verification, and audit trails outside public metadata endpoints. |
Webhook deduplication uses provider evidence, not the browser return URL. Provider adapters verify the raw body and return a payloadHash; Mika persists webhook records and uses the provider event ID or payload hash for downstream workflow idempotency.
Related Tasks
Section titled “Related Tasks”- Astro Storefront shows
createMikaActions({ guard }). - Stripe And Webhook Cookbook shows raw-body webhook handling.
- Operations lists operation visibility, confirmation, and idempotency metadata.
External References
Section titled “External References”- Astro Actions for form actions and standardized
ActionErrorhandling. - EmDash plugin guide for the plugin API/admin extension surface Mika plugs into.
Source Anchors
Section titled “Source Anchors”- ⓟ
../emdash-mika/src/api/operation-agent-metadata.ts - ⓟ
../emdash-mika/src/api/operation-policy.ts - ⓟ
../emdash-mika/src/api/redirect-policy.ts - ⓟ
../emdash-mika/src/api/route-handlers.ts - ⓟ
../emdash-mika/src/api/backend.ts - ⓟ
../emdash-mika/src/provider.ts - ⓟ
../emdash-mika/src/astro-actions.ts - ⓐ
../emdash-mika/src/templates/astro/README.md - ⓐ
../emdash-mika/src/templates/astro/pages/api/mika-webhook/[provider].ts