feat: pluggable auth providers — add AT Protocol, refactor GitHub/Google

[simnaut]

What does this PR do?

Introduces a pluggable auth provider system and uses it to add AT Protocol authentication as the first plugin-based provider. GitHub and Google OAuth are refactored from hardcoded buttons into the same provider interface. All auth methods — passkey, AT Protocol, GitHub, Google — are equal options on the login page and setup wizard.

Auth provider descriptor

Every provider implements AuthProviderDescriptor:

emdash({
  authProviders: [atproto(), github(), google()],
})

Each descriptor declares an adminEntry (React components for login/setup UI), optional routes (Astro route handlers), and publicRoutes (middleware bypass prefixes). Components are distributed to the admin app via a virtual:emdash/auth-providers Vite virtual module.

What changed

Scope note: The entire pluggable auth provider system is new in this PR — none of it existed on main. The pre-existing AuthDescriptor / AuthProviderModule (transparent auth for Cloudflare Access) is unchanged.

New pluggable infrastructure (core):

• AuthProviderDescriptor / AuthRouteDescriptor types in auth/types.ts
• authProviders config field on EmDashConfig
• virtual:emdash/auth-providers virtual module with generateAuthProvidersModule()
• injectAuthProviderRoutes() for generic route injection from descriptors
• Dynamic public routes in auth middleware (merged from all providers)
• AuthProviderContext in admin for distributing provider UI components
• Public /_emdash/api/auth/mode endpoint returning available providers
• emdash/api/route-utils public export for API utilities used by plugin routes
• finalizeSetup() shared helper for setup completion (idempotent, used by all auth callbacks)

Shared OAuth user creation (@emdash-cms/auth):

• findOrCreateOAuthUser() extracted as a shared export — handles OAuth account lookup, email auto-linking, and user creation with canSelfSignup policy
• Used by all OAuth providers (GitHub, Google, AT Protocol) for consistent signup gating and role assignment

Login page:

• Removed hardcoded OAUTH_PROVIDERS array
• All providers render from virtual module via useAuthProviderList()
• Providers with LoginButton show in a button grid; those with LoginForm expand inline on click

Setup wizard:

• All configured auth providers appear as equal options alongside passkey
• Clicking a provider button either navigates directly (GitHub/Google OAuth) or expands a form (AT Protocol handle input)
• OAuth callback is setup-aware: first user becomes admin, site config is persisted, setup is marked complete
• First-user admin creation uses a database transaction to prevent TOCTOU race conditions
• URL error params displayed in a banner (previously errors were silently lost)

AT Protocol (new — @emdash-cms/plugin-atproto):

• atproto() returns AuthProviderDescriptor with routes for login, callback, setup-admin, and client metadata
• Route handlers live in the plugin package (@emdash-cms/plugin-atproto/routes/*), not in core — removing the plugin removes the routes
• LoginButton (compact butterfly icon), LoginForm (handle input), SetupStep exported from @emdash-cms/plugin-atproto/admin
• Uses @atcute/oauth-node-client with PKCE (public client, no key management needed)
• First user becomes Admin during setup; subsequent users get the configured default role (Subscriber by default)
• allowedDIDs allowlist for access control by permanent DID identifiers
• allowedHandles allowlist with wildcard support for org-level domain gating (e.g., *.mycompany.com). Handle ownership is independently verified via DNS-over-HTTPS and HTTP well-known resolution using @atcute/identity-resolver — the PDS's handle claim is never trusted directly
• If both are set, matching either list grants access
• Uses shared findOrCreateOAuthUser() with canSelfSignup policy for consistent signup gating

GitHub / Google (refactored to descriptors):

• github() and google() return AuthProviderDescriptor with adminEntry pointing to -admin.tsx components
• LoginButton components with provider icons, reusing core's existing [provider] OAuth routes
• No new routes needed — they reuse core's shared OAuth infrastructure

OAuth error handling:

• OAuth initiation route checks Referer to redirect errors back to the originating page (setup wizard vs login)
• Error messages include which env vars need to be set when a provider isn't configured

Configuration

import { atproto } from "@emdash-cms/plugin-atproto/auth";
import { github } from "emdash/auth/providers/github";
import { google } from "emdash/auth/providers/google";

emdash({
  authProviders: [atproto(), github(), google()],
})

AT Protocol options:

atproto({
  // Permanent DID-based allowlist
  allowedDIDs: ["did:plc:abc123"],
  // Domain-based allowlist (independently verified via DNS/HTTP)
  allowedHandles: ["*.mycompany.com", "alice.bsky.social"],
  // Default role for new users (default: 10 / Subscriber)
  defaultRole: 20, // Contributor
})

New routes (AT Protocol)

• POST /_emdash/api/auth/atproto/login — initiate OAuth flow (handle → PDS authorization URL)
• GET /_emdash/api/auth/atproto/callback — handle PDS redirect, create/find user, establish session
• POST /_emdash/api/setup/atproto-admin — setup wizard flow
• GET /.well-known/atproto-client-metadata.json — client metadata (PDS fetches this)

Type of change

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

Checklist

• I have read CONTRIBUTING.md
• pnpm typecheck passes
• pnpm --silent lint:json | jq '.diagnostics | length' returns 0
• pnpm test passes (or targeted tests for my change)
• pnpm format has been run
• I have added/updated tests for my changes (if applicable)
• I have added a changeset (if this PR changes a published package)
• New features link to an approved Discussion: Feat: ATProto PDS as primary auth #320

AI-generated code disclosure

• This PR includes AI-generated code

Screenshots / test output

Test results (2026-04-12)

Full CI suite run locally after addressing review comments. All 3,470 tests pass across 10 packages (204 test files, 0 failures). Typecheck clean across all 21 packages. Lint returns 18 diagnostics (all pre-existing, none introduced by this PR).

emdash (core): 2,279 tests, 131 files — all passing

 Test Files  131 passed (131)
      Tests  2279 passed (2279)

@emdash-cms/auth-atproto: 30 tests, 3 files — all passing

 ✓ tests/auth.test.ts (16 tests) 4ms
 ✓ tests/resolve-handle.test.ts (3 tests) 11ms
 ✓ tests/oauth-client.test.ts (11 tests) 53ms

 Test Files  3 passed (3)
      Tests  30 passed (30)

@emdash-cms/auth: 45 tests, 3 files — all passing

 Test Files  3 passed (3)
      Tests  45 passed (45)

@emdash-cms/admin: 723 tests, 49 files — all passing

 Test Files  49 passed (49)
      Tests  723 passed (723)

Other packages: all passing

gutenberg-to-portable-text  2 files   140 tests ✓
marketplace                 5 files    48 tests ✓
blocks                      3 files    61 tests ✓
x402                        1 file     17 tests ✓
cloudflare                  7 files   127 tests ✓

[changeset-bot]

🦋 Changeset detected

Latest commit: 2ec5dce

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

This PR includes changesets to release 13 packages

Name	Type
emdash	Major
@emdash-cms/admin	Major
@emdash-cms/auth-atproto	Major
@emdash-cms/auth	Major
@emdash-cms/cloudflare	Major
@emdash-cms/fixture-perf-site	Patch
@emdash-cms/perf-demo-site	Patch
@emdash-cms/cache-demo-site	Patch
@emdash-cms/blocks	Major
@emdash-cms/gutenberg-to-portable-text	Major
@emdash-cms/x402	Major
create-emdash	Major
@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

[github-actions]

All contributors have signed the CLA ✍️ ✅
_{Posted by the CLA Assistant Lite bot.}

[github-actions]

Scope check

This PR changes 2,616 lines across 55 files. Large PRs are harder to review and more likely to be closed without review.
This PR spans 4 different areas (area/core, area/admin, area/plugins, area/auth). Consider breaking it into smaller, focused PRs.

If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs.

See CONTRIBUTING.md for contribution guidelines.

[Copilot]

Pull request overview

This PR introduces a new pluggable auth provider system in emdash, adds AT Protocol authentication as the first plugin-based provider, and refactors GitHub/Google OAuth into the same provider interface so all login methods are rendered uniformly in the login page and setup wizard.

Changes:

• Add AuthProviderDescriptor + route injection + virtual:emdash/auth-providers registry generation.
• Add @emdash-cms/plugin-atproto auth provider (routes, OAuth client, handle/DID verification, admin UI components).
• Refactor admin login/setup UI to render configured providers dynamically and add a public /_emdash/api/auth/mode endpoint.

Reviewed changes

Copilot reviewed 52 out of 55 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pnpm-lock.yaml	Adds workspace links and new dependencies for the AT Protocol plugin and demo site updates.
packages/plugins/atproto/tests/resolve-handle.test.ts	Adds tests for independent handle→DID verification error paths.
packages/plugins/atproto/tests/plugin.test.ts	Updates plugin descriptor tests to new expected entrypoint/format/storage.
packages/plugins/atproto/tests/oauth-client.test.ts	Adds tests for AT Protocol OAuth client metadata and singleton behavior.
packages/plugins/atproto/tests/auth.test.ts	Adds tests for atproto() auth provider descriptor contract/config passthrough.
packages/plugins/atproto/src/routes/setup-admin.ts	Implements setup-step route to initiate AT Protocol OAuth and persist setup state.
packages/plugins/atproto/src/routes/login.ts	Implements login initiation route for AT Protocol OAuth.
packages/plugins/atproto/src/routes/client-metadata.ts	Serves /.well-known/atproto-client-metadata.json for AT Protocol OAuth.
packages/plugins/atproto/src/routes/callback.ts	Implements AT Protocol OAuth callback, user provisioning, allowlist enforcement, setup finalization, session creation.
packages/plugins/atproto/src/resolve-handle.ts	Adds independent handle resolution via DNS-over-HTTPS + well-known HTTP.
packages/plugins/atproto/src/oauth-client.ts	Adds OAuth client singleton + DB-backed state/session storage support for Workers.
packages/plugins/atproto/src/env.d.ts	References core locals types for plugin route context typing.
packages/plugins/atproto/src/db-store.ts	Adds DB-backed store implementation for atcute OAuth state/sessions.
packages/plugins/atproto/src/auth.ts	Exposes atproto() returning an AuthProviderDescriptor (adminEntry, routes, public routes).
packages/plugins/atproto/src/admin.tsx	Adds provider UI components (LoginButton/LoginForm/SetupStep) for admin app.
packages/plugins/atproto/package.json	Exports new auth/admin/routes modules and declares deps/peers.
packages/core/tsconfig.json	Includes new *-admin.tsx auth provider admin components in TS compilation.
packages/core/src/virtual-modules.d.ts	Adds typing for virtual:emdash/auth-providers and config authProviders.
packages/core/src/index.ts	Re-exports new auth provider types.
packages/core/src/auth/types.ts	Defines AuthProviderDescriptor, AuthRouteDescriptor, and admin export contract types.
packages/core/src/auth/providers/google.ts	Adds google() provider descriptor returning adminEntry for UI integration.
packages/core/src/auth/providers/google-admin.tsx	Adds Google provider LoginButton component.
packages/core/src/auth/providers/github.ts	Adds github() provider descriptor returning adminEntry for UI integration.
packages/core/src/auth/providers/github-admin.tsx	Adds GitHub provider LoginButton component.
packages/core/src/auth/mode.ts	Re-exports new auth provider types from core auth mode module.
packages/core/src/astro/routes/PluginRegistry.tsx	Passes authProviders registry into the admin app.
packages/core/src/astro/routes/api/setup/status.ts	Adjusts setup status commentary for external auth mode.
packages/core/src/astro/routes/api/setup/index.ts	Adjusts setup state persistence comments for provider-based flows.
packages/core/src/astro/routes/api/setup/admin.ts	Merges admin info into existing setup state (preserve step 1 values).
packages/core/src/astro/routes/api/auth/oauth/[provider]/callback.ts	Makes OAuth callback setup-aware (first user becomes admin; finalize setup).
packages/core/src/astro/routes/api/auth/oauth/[provider].ts	Improves OAuth initiation error redirect target and missing-env error messaging.
packages/core/src/astro/routes/api/auth/mode.ts	Adds public endpoint exposing active auth mode + provider list + signupEnabled.
packages/core/src/astro/middleware/auth.ts	Merges provider-supplied public route bypass prefixes into middleware checks; whitelists /_emdash/api/auth/mode.
packages/core/src/astro/middleware.ts	Adds fast-path bypass for non-/_emdash injected provider routes like /.well-known/*.
packages/core/src/astro/integration/vite-config.ts	Adds virtual module IDs and generator for auth providers registry.
packages/core/src/astro/integration/virtual-modules.ts	Implements generateAuthProvidersModule() to bundle provider adminEntry exports.
packages/core/src/astro/integration/runtime.ts	Adds authProviders to EmDashConfig.
packages/core/src/astro/integration/routes.ts	Injects core auth mode route + provider-declared routes.
packages/core/src/astro/integration/index.ts	Wires authProviders through resolved config and injects provider routes.
packages/core/src/api/setup-complete.ts	Introduces shared idempotent finalizeSetup() helper.
packages/core/src/api/schemas/setup.ts	Adds schemas for AT Protocol login/setup request bodies.
packages/core/src/api/route-utils.ts	Public re-export bundle for plugin route handlers (parse/api helpers + finalizeSetup).
packages/core/package.json	Exposes new public exports for provider descriptors/admin components + route utils/schemas; adds optional peer for atproto plugin.
packages/auth/src/oauth/consumer.ts	Extracts shared findOrCreateOAuthUser() and updates callback path to use it.
packages/auth/src/index.ts	Re-exports findOrCreateOAuthUser + CanSelfSignup type.
packages/admin/src/lib/auth-provider-context.tsx	Adds React context for provider UI modules and helper hooks (list ordering).
packages/admin/src/lib/api/index.ts	Re-exports fetchAuthMode().
packages/admin/src/lib/api/client.ts	Adds fetchAuthMode() client for public auth mode endpoint.
packages/admin/src/index.ts	Re-exports auth provider context utilities from admin package.
packages/admin/src/components/SetupWizard.tsx	Refactors setup wizard to offer passkey + provider methods and show URL error banners.
packages/admin/src/components/LoginPage.tsx	Refactors login page to render providers dynamically and fetch auth mode from public endpoint.
packages/admin/src/App.tsx	Wires auth provider registry into admin app via context provider.
demos/simple/package.json	Adds atproto plugin to demo dependencies.
demos/simple/astro.config.mjs	Configures authProviders: [github(), google(), atproto()] in the demo.
.changeset/stale-knives-fix.md	Changeset documenting the new pluggable auth provider system and AT Protocol support.

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[simnaut]

I have read the CLA Document and I hereby sign the CLA

[github-actions]

Overlapping PRs

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

• fix: add siteUrl to resolve origin mismatch behind reverse proxies #382 (8 shared files)
• feat(admin): add Lingui i18n infrastructure #234 (5 shared files)
• feat(auth): add Google Authenticator 2FA flows and setup options #73 (8 shared files)
• Store CSS classes, make editor toolbar extensible #143 (3 shared files)
• fix: repair invite flow — URL prefix + registration UI #81 (3 shared files)
• fix: bundle sandbox entries with esbuild & normalize CodeBlock languages #179 (3 shared files)

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

[ascorbic]

Great! The test failures are just an outdated lockfile. I have a few things I'd like addressing, but I need to dig into it a bit deeper. I'll leave another review in a few hours.

[syhily]

Hi @ascorbic, this feature is quite cool. What's the block for merging this PR?

[ascorbic]

@simnaut this just needs conflicts resolving and the correct Button types to be used!

[simnaut]

@ascorbic Merged in main and updated the Button type.

[ascorbic]

Amazing work! Thanks for getting this over the line. It needs docs, but I'll follow this up an another PR. We'll also need the warning about setting server.host to 127.0.0.1