feat(plugins): expose authenticated caller to route handlers as ctx.user

[swissky]

What does this PR do?

The plugin API catch-all resolves the authenticated user, uses it to enforce plugins:manage + scope + CSRF — and then drops it before invoking the plugin's handler. Plugins had no first-class way to know who is calling a private route, forcing bad workarounds (reading a user id from the request body is trivially spoofable).

This threads the validated caller through handlePluginApiRoute into the route context, exactly as proposed in #812:

• Native format: ctx.user on RouteContext.
• Standard (sandboxed) format: routeCtx.user — wired through the in-process adapter, the Cloudflare Worker Loader wrapper, and both workerd runners (SerializedRequest.user is structured-clone/JSON-safe).
• The exposed shape is the existing read-only UserInfo ({ id, email, name, role, createdAt }) — the same shape ctx.users returns, with sensitive host-side fields (avatarUrl, data, …) stripped by toRouteCallerInfo().

Semantics (per the issue):

• Private routes: ctx.user is the authenticated caller, validated by the existing requirePerm/requireScope checks one frame up.
• Public routes: ctx.user is undefined — the catch-all only forwards the caller after private-route auth, so an ambient admin session browsing the site is never bound to a public route.
• Machine tokens with no bound user: undefined.

Purely additive — no change for plugins that don't read ctx.user, no migration, no flag. Caller identity is intentionally not gated by the users:read capability (it's the caller's own identity, not a directory lookup).

Tests: route handler exposes/omits ctx.user (unit), catch-all forwards the caller only for private routes (unit, including the ambient-session case), sandbox adapter puts user on routeCtx and strips it from pluginCtx, toRouteCallerInfo mapping (Date→ISO, field stripping). Docs updated in the API-routes guide (new "The authenticated caller" section + route context reference) and the native-plugin guide.

Closes #812
Discussion: #1757

Type of change

• Bug fix
• Feature (requires maintainer-approved Discussion)
• Refactor (no behavior change)
• Translation
• Documentation
• Performance improvement
• Tests
• Chore (dependencies, CI, tooling)

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm lint passes
• pnpm test passes (or targeted tests for my change)
• pnpm format has been run
• I have added/updated tests for my changes (if applicable)
• User-visible strings in the admin UI are wrapped for translation (if applicable). Do not include messages.po changes except in translation PRs — a workflow extracts catalogs on merge to main. — n/a, no admin UI strings
• I have added a changeset (if this PR changes a published package)
• New features link to an approved Discussion: Expose authenticated `user` to plugin route handlers via `RouteContext` #1757

AI-generated code disclosure

• This PR includes AI-generated code — model/tool: Cursor + Fable 5

Screenshots / test output

tests/unit/plugins + tests/unit/astro/plugin-api-route-auth.test.ts
 Test Files  30 passed (30)
      Tests  629 passed (629)

tests/integration/plugins + tests/unit/astro
 Test Files  26 passed (26)
      Tests  276 passed (276)

@emdash-cms/sandbox-workerd: 76 passed · @emdash-cms/cloudflare: 222 passed

[changeset-bot]

🦋 Changeset detected

Latest commit: 872b71e

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 16 packages

Name	Type
emdash	Minor
@emdash-cms/cloudflare	Minor
@emdash-cms/sandbox-workerd	Minor
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/do-demo-site	Patch
@emdash-cms/do-solo-demo-site	Patch
@emdash-cms/admin	Minor
@emdash-cms/auth	Minor
@emdash-cms/blocks	Minor
@emdash-cms/gutenberg-to-portable-text	Minor
@emdash-cms/x402	Minor
create-emdash	Minor
@emdash-cms/auth-atproto	Patch
@emdash-cms/plugin-embeds	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@emdash-cms/admin

npm i https://pkg.pr.new/@emdash-cms/admin@1947

@emdash-cms/auth

npm i https://pkg.pr.new/@emdash-cms/auth@1947

@emdash-cms/auth-atproto

npm i https://pkg.pr.new/@emdash-cms/auth-atproto@1947

@emdash-cms/blocks

npm i https://pkg.pr.new/@emdash-cms/blocks@1947

@emdash-cms/cloudflare

npm i https://pkg.pr.new/@emdash-cms/cloudflare@1947

@emdash-cms/contentful-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/contentful-to-portable-text@1947

emdash

npm i https://pkg.pr.new/emdash@1947

create-emdash

npm i https://pkg.pr.new/create-emdash@1947

@emdash-cms/gutenberg-to-portable-text

npm i https://pkg.pr.new/@emdash-cms/gutenberg-to-portable-text@1947

@emdash-cms/plugin-cli

npm i https://pkg.pr.new/@emdash-cms/plugin-cli@1947

@emdash-cms/plugin-types

npm i https://pkg.pr.new/@emdash-cms/plugin-types@1947

@emdash-cms/registry-client

npm i https://pkg.pr.new/@emdash-cms/registry-client@1947

@emdash-cms/registry-lexicons

npm i https://pkg.pr.new/@emdash-cms/registry-lexicons@1947

@emdash-cms/sandbox-workerd

npm i https://pkg.pr.new/@emdash-cms/sandbox-workerd@1947

@emdash-cms/x402

npm i https://pkg.pr.new/@emdash-cms/x402@1947

@emdash-cms/plugin-ai-moderation

npm i https://pkg.pr.new/@emdash-cms/plugin-ai-moderation@1947

@emdash-cms/plugin-atproto

npm i https://pkg.pr.new/@emdash-cms/plugin-atproto@1947

@emdash-cms/plugin-audit-log

npm i https://pkg.pr.new/@emdash-cms/plugin-audit-log@1947

@emdash-cms/plugin-color

npm i https://pkg.pr.new/@emdash-cms/plugin-color@1947

@emdash-cms/plugin-embeds

npm i https://pkg.pr.new/@emdash-cms/plugin-embeds@1947

@emdash-cms/plugin-field-kit

npm i https://pkg.pr.new/@emdash-cms/plugin-field-kit@1947

@emdash-cms/plugin-forms

npm i https://pkg.pr.new/@emdash-cms/plugin-forms@1947

@emdash-cms/plugin-webhook-notifier

npm i https://pkg.pr.new/@emdash-cms/plugin-webhook-notifier@1947

commit: 872b71e

[github-actions]

Overlapping PRs

This PR modifies files that are also changed by other open PRs:

• feat(plugins): auto-generate admin settings UI from settingsSchema (#341) #1893 (3 shared files)
• Harden plugin MCP tool registration #988 (6 shared files)

This may cause merge conflicts or duplicated work. A maintainer will coordinate.

[github-actions]

This PR has been inactive for 14 days. It will be closed automatically in 7 days if there is no further activity.

If you're still working on this, please push an update or leave a comment.