Make app.auth.provider a required discriminated union: waspAuth() or an external provider manifest by FranjoMindek · Pull Request #4726 · wasp-lang/wasp

FranjoMindek · 2026-08-14T16:02:26Z

Description

Stack 3/7. The semantic heart of the feature: app.auth.provider becomes a required discriminated union — waspAuth({ methods, onAuthSucceededRedirectTo, ...hooks }) for Wasp's own auth, or an external provider manifest (produced by an adapter package's spec helper or customAuthProvider()).

Public spec surface (@wasp.sh/spec): the union, waspAuth(), defineAuthProviderManifest() with validation invariants, customAuthProvider(). Everything that only makes sense when Wasp runs signup/login (methods, hooks, success redirect) moves off Auth into waspAuth(), so none of it can leak into an external-provider app.
Manifest fields, final from birth: id, server (package entry or user-code module ref), routes, capabilities (open string set), env (server+client var requirements with docs), userSignupFields, setupFn, options, contractVersion.
Haskell IR: AuthProvider = WaspAuthProvider WaspAuthConfig | ExternalAuthProvider ExternalAuthProviderSpec, hand-written kind-discriminated JSON codecs, HasCustomEvaluation, accessor shims so the generator compiles unchanged.
Mechanical migration of every spec in the repo to waspAuth() (kitchen-sink, tutorials, waspello, websockets, ask-the-documents, the basic starter, and all four auth example apps) — this is exactly the migration the union imposes on users.
Docs API markdown snapshots regenerated (new Auth + Experimental sections).

The generator does not consume external manifests yet: they are legal but inert until stacks 4-6. Mapper acceptance of server: { package } entries is likewise latent until 6/7.

Review guidance: spend the effort on waspSpec.ts, constructors.ts and Auth.hs (~800 lines); the per-app waspAuth() wraps are mechanical and identical.

Type of change

🔧 Just code/docs improvement
🐞 Bug fix
🚀 New/improved feature
💥 Breaking change

Checklist

cloudflare-workers-and-pages · 2026-08-14T16:13:33Z

Deploying wasp-docs-on-main with Cloudflare Pages

Latest commit:	`ed34ccc`
Status:	✅ Deploy successful!
Preview URL:	https://67456a2c.wasp-docs-on-main.pages.dev
Branch Preview URL:	https://franjo-auth2-3-spec-provider.wasp-docs-on-main.pages.dev

View logs

pkg-pr-new · 2026-08-14T18:13:53Z

Open in StackBlitz

@wasp.sh/spec

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/spec@4726

@wasp.sh/wasp-cli

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli@4726

@wasp.sh/wasp-cli-darwin-arm64-unknown

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-darwin-arm64-unknown@4726

@wasp.sh/wasp-cli-darwin-x64-unknown

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-darwin-x64-unknown@4726

@wasp.sh/wasp-cli-linux-arm64-glibc

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-linux-arm64-glibc@4726

@wasp.sh/wasp-cli-linux-x64-glibc

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-linux-x64-glibc@4726

@wasp.sh/wasp-cli-linux-x64-musl

npx https://pkg.pr.new/wasp-lang/wasp/@wasp.sh/wasp-cli-linux-x64-musl@4726

commit: ed34ccc

FranjoMindek · 2026-08-14T19:16:43Z

Follow-up to the contract change in #4725: defineAuthProviderManifest (and therefore customAuthProvider and every adapter spec helper) now rejects external provider ids that do not start with external:, with a test. The manifest id docs explain the reserved unprefixed namespace.

FranjoMindek · 2026-08-15T09:03:00Z

-    },
    onAuthFailedRedirectTo: "/login",
-    onAuthSucceededRedirectTo: "/",
+    // Wasp's own auth, selected explicitly. Everything that only makes sense


These comments are unnecessary.
Also remove the original ones from the first PR.
Maybe just leave a short TODO: to be replaced with better-auth adapter e.g. in correct example.

This is true for all examples.

FranjoMindek · 2026-08-15T09:07:16Z

+-- independently of Wasp releases, so a closed enum here would break decoding of
+-- every manifest built against a newer adapter. Unknown entries are ignored.
+data ExternalAuthProviderSpec = ExternalAuthProviderSpec
+  { -- | Stable identifier ("clerk", "better-auth"). Identities Wasp provisions


Update to follow external convention

FranjoMindek · 2026-08-15T09:08:44Z

+    serverPackage :: Maybe String,
+    -- | User-code module implementing the provider (the hand-written adapter
+    -- escape hatch), reached through a virtual user module like every other
+    -- ext import.
+    serverModule :: Maybe ExtImport,


If these are exclusive make them Either

FranjoMindek · 2026-08-15T09:10:15Z

+    -- | Populates the user entity when Wasp provisions a local user for a
+    -- subject it has not seen before.
+    userSignupFields :: Maybe ExtImport,
+    -- | Setup function for the provider's underlying library (the


Please remove reudundant information like @prismaSetupFn@ convention.
Keep field descriptions minimal.

FranjoMindek · 2026-08-15T09:12:47Z

+  // pattern would rewrite it into `provider: SMTP({...})` and corrupt the spec.
  const waspSMTPAppSpec = waspTsSpec.replace(
-    /provider:\s+[A-Za-z0-9_][A-Za-z0-9_]*/g,
+    /provider:\s+(SMTP|SendGrid|Mailgun|Resend|Dummy)\b/g,


We replace SMTP with SMTP?

…an external provider manifest

FranjoMindek · 2026-08-15T14:44:00Z

Review fixes applied:

Example spec comments removed; the three to-flip apps carry a short TODO: to be replaced with the X adapter until their flip.
Auth.hs doc examples now follow the external: convention.
serverPackage/serverModule are now exclusive by construction: a single server :: ExternalProviderServer (newtype over Either String ExtImport) with a {package}|{module} JSON codec; the mapper emits the tagged shape and Valid.hs's exclusivity check is deleted as impossible-by-construction. Accessor functions keep the old names, so downstream generator code is untouched.
Field docs trimmed (prismaSetupFn convention reference and other redundancy removed).
mailcrab: SMTP dropped from its own replacement alternation — behavior identical, tautology gone.

This was referenced Aug 14, 2026

Make the auth provider selectable, with JIT user provisioning #4715

Closed

Make app.auth.provider a discriminated union: waspAuth() or an external provider manifest #4719

Closed

FranjoMindek force-pushed the franjo/auth2-3-spec-provider-union branch from d4fccef to 4fa8644 Compare August 14, 2026 16:31

FranjoMindek had a problem deploying to railway-deploy-test August 14, 2026 18:11 — with GitHub Actions Failure

FranjoMindek temporarily deployed to fly-deploy-test August 14, 2026 18:11 — with GitHub Actions Inactive

FranjoMindek force-pushed the franjo/auth2-3-spec-provider-union branch from 4fa8644 to 36c80e7 Compare August 14, 2026 19:16

FranjoMindek mentioned this pull request Aug 14, 2026

Extract the session layer behind an AuthProvider contract in @wasp.sh/auth-contract #4725

Draft

15 tasks

FranjoMindek deployed to fly-deploy-test August 14, 2026 20:50 — with GitHub Actions Active

FranjoMindek had a problem deploying to railway-deploy-test August 14, 2026 20:50 — with GitHub Actions Failure

FranjoMindek force-pushed the franjo/auth2-3-spec-provider-union branch from 36c80e7 to f75f6ed Compare August 14, 2026 21:57

FranjoMindek had a problem deploying to railway-deploy-test August 14, 2026 22:12 — with GitHub Actions Failure

FranjoMindek deployed to fly-deploy-test August 14, 2026 22:12 — with GitHub Actions Active

FranjoMindek force-pushed the franjo/auth2-3-spec-provider-union branch from f75f6ed to 0d133ef Compare August 15, 2026 08:28

FranjoMindek commented Aug 15, 2026

View reviewed changes

FranjoMindek deployed to fly-deploy-test August 15, 2026 09:18 — with GitHub Actions Active

FranjoMindek had a problem deploying to railway-deploy-test August 15, 2026 09:18 — with GitHub Actions Failure

Make app.auth.provider a required discriminated union: waspAuth() or …

ed34ccc

…an external provider manifest

FranjoMindek force-pushed the franjo/auth2-3-spec-provider-union branch from 0d133ef to ed34ccc Compare August 15, 2026 14:43

FranjoMindek deployed to fly-deploy-test August 15, 2026 15:32 — with GitHub Actions Active

FranjoMindek had a problem deploying to railway-deploy-test August 15, 2026 15:32 — with GitHub Actions Failure

Navigation Menu

Uh oh!

Uh oh!

Make app.auth.provider a required discriminated union: waspAuth() or an external provider manifest - #4726

Make app.auth.provider a required discriminated union: waspAuth() or an external provider manifest#4726
FranjoMindek wants to merge 1 commit into
franjo/auth2-2-auth-contractfrom
franjo/auth2-3-spec-provider-union

FranjoMindek commented Aug 14, 2026

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 14, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Aug 14, 2026 •

edited

Loading

Uh oh!

FranjoMindek commented Aug 14, 2026

Uh oh!

FranjoMindek Aug 15, 2026 •

edited

Loading

Uh oh!

FranjoMindek Aug 15, 2026

Uh oh!

FranjoMindek Aug 15, 2026

Uh oh!

FranjoMindek Aug 15, 2026

Uh oh!

FranjoMindek Aug 15, 2026

Uh oh!

FranjoMindek commented Aug 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

FranjoMindek commented Aug 14, 2026

Description

Type of change

Checklist

Uh oh!

cloudflare-workers-and-pages Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deploying wasp-docs-on-main with Cloudflare Pages

Uh oh!

pkg-pr-new Bot commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FranjoMindek commented Aug 14, 2026

Uh oh!

FranjoMindek Aug 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Aug 15, 2026

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Aug 15, 2026

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Aug 15, 2026

Choose a reason for hiding this comment

Uh oh!

FranjoMindek Aug 15, 2026

Choose a reason for hiding this comment

Uh oh!

FranjoMindek commented Aug 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

cloudflare-workers-and-pages Bot commented Aug 14, 2026 •

edited

Loading

pkg-pr-new Bot commented Aug 14, 2026 •

edited

Loading

FranjoMindek Aug 15, 2026 •

edited

Loading