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: 995bd46

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

This PR includes changesets to release 10 packages

Name	Type
emdash	Major
@emdash-cms/admin	Major
@emdash-cms/auth-atproto	Major
@emdash-cms/auth	Major
@emdash-cms/cloudflare	Major
@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.

[ascorbic]

@jimray it would be great to get your eyes on the atproto part of this

[ascorbic]

@simnaut the conflicts here are mostly related to the i18n. Once you've reolved the conflicts in the JSX you should be able to run pnpm locale:extract to resolve the .po conflicts

[simnaut]

@ascorbic Conflicts resolved, also suppressed lint warnings at some library boundaries.

[ascorbic]

This doesn't work in local dev for me, because by default Astro expects to be loaded on localhost not 127.0.0.1

[simnaut]

Hmm. Interesting. 127.0.0.1 is required by the OAuth spec (RFC 8252), and the atcute library enforces it: loopbackRedirectUriSchema explicitly rejects localhost in redirect URIs. The server-side normalization is working on my end but I want it to work universally. What kind of error did you run in to?

[ascorbic]

The callback tries to load 127.0.0.1:4321 and just gets no server response

[jimray]

@jimray it would be great to get your eyes on the atproto part of this

I can take a look in a bit

[ascorbic]

This is generally great, and aside from the loclahost thing it worked great for me. My main other comment is that we should standardise on the Kumo components that are used elsewhere in the admin to keep things consistent. I'd make it a peer dependency of the auth packages.

[ascorbic]

Yeah, sorry I just meant LinkButton for the ones that were actually links. Others should use Button.