Proposal: first-class native plugin HTTP, asset, and CSP contracts

[connorblack]

Proposal: first-class native plugin HTTP, asset, and CSP contracts

Problem

Native plugins can own server behavior and page fragments, but several missing
contracts force production integrations back into site-specific code:

• a private route cannot identify its authenticated caller without reaching
  outside RouteContext;
• every successful plugin route is wrapped in EmDash JSON, even when a trusted
  native plugin must preserve a standard protocol response;
• a plugin cannot declare a browser entrypoint and receive a stable same-origin
  URL, so sites copy bundles into public/ themselves; and
• trusted inline page fragments do not register their bodies with Astro CSP.

An editor-only browser assistant is one concrete consumer, but these gaps also
affect webhooks, protocol adapters, widgets, and other native plugins that pair a
server route with a browser bundle.

Proposed contracts

Authenticated route actor

Add RouteContext.actor as a minimal principal:

interface PluginRouteActor {
  id: string;
  role: RoleLevel;
  permissions: Permission[];
}

Private routes receive the authenticated actor after core authorization. Public
routes receive null. The value excludes profile, email, session, credential,
and secret data. The serialized sandbox request gains an optional additive actor
field so older transports remain compatible.

Explicit raw responses

Allow trusted native routes to declare response: "raw" and return a Response
without EmDash's JSON success envelope. Core still enforces authentication,
permission, and CSRF before dispatch. Route code still owns method and input
validation.

Caching stays conservative: private responses, public errors, and public methods
other than successful GET/HEAD use Cache-Control: private, no-store. Only a
public 2xx GET/HEAD may use its declared cacheControl value. Sandboxed
plugins cannot opt into raw mode.

Native browser assets

Allow a native PluginDescriptor to declare owned Vite entrypoints:

assets: [
  { path: "client.js", entrypoint: "@example/emdash-assistant/client" },
]

EmDash builds the entrypoint and exposes a lookup-only same-origin alias:

/_emdash/assets/plugins/{pluginId}/{version}/{path}

The versioned alias redirects to Vite's generated asset and can be cached for one
year as immutable. Validation rejects absolute/traversal-like paths, query/hash
suffixes, duplicate logical keys, cross-descriptor collisions, unsafe redirect
targets, and non-native descriptors. The route never loads auth, sessions, the
database, or the plugin runtime.

Trusted fragment CSP hashes

When Astro CSP is enabled, EmDash computes SHA-256 sources from the exact inline
script bodies it renders in head, body:start, and body:end. Hashing shares
the renderer's existing </ escape and leaves rendered bytes unchanged. CSP
access stays lazy when the host disables CSP. External script hosts remain the
site operator's script-src responsibility.

Compatibility and scope

These changes add fields and modes without changing existing JSON routes,
descriptors, or sandbox wire payloads. Existing native plugins continue to work
unchanged. The proposal does not add generic filesystem serving, expose secrets,
weaken CSRF, add unsafe-inline, or make public page fragments depend on a user
session.

The implementation includes focused Node, Cloudflare, and workerd transport
tests; raw response and cache tests; asset validation/generation/routing tests;
and a real Astro static-build CSP regression.

Would maintainers approve this direction for a minor emdash release?