Teach codegen to consume adapter packages: serverPackage entries, setupFn, and manifest routes

Author: FranjoMindek

waspc/data/Generator/libs/auth-contract/README.md

@@ -2,9 +2,10 @@
 
 The contract between Wasp and pluggable auth providers.
 
-An auth provider implements this contract to make an external auth solution
-(Better Auth, Clerk, WorkOS, ...) usable as a Wasp auth provider: `AuthProvider`,
-`VerifiedSession`, and the optional `SessionIssuingAuthProvider` capability.
+An auth adapter package implements this contract to make an external auth
+solution (Better Auth, Clerk, WorkOS, ...) usable as a Wasp auth provider:
+`AuthProvider`, `VerifiedSession`, `WaspServerRuntime`, and the
+`createServerAdapter` factory shape adapter packages must export.
 
 The package is copied into generated Wasp apps as a tarball (like the other libs
 in this directory) and installed via a `file:` dependency, so both generated code

waspc/data/Generator/libs/auth-contract/src/index.ts

@@ -5,8 +5,15 @@
  * pages, `auth: true` operations, `context.user`, `useAuth()` -- so implementing it
  * is all it takes to make any auth solution (Better Auth, Clerk, WorkOS, ...) a
  * Wasp auth provider.
+ *
+ * An adapter package implements this contract in its server entry and exposes it
+ * as a named `createServerAdapter` export (see `ServerAdapterFactory`). Its
+ * client side, if it has one, ships as ordinary React exports on the package's
+ * own `/client` entry -- Wasp generates no client glue.
  */
 
+import type { IncomingMessage, ServerResponse } from "node:http";
+
 export type JsonValue =
   | string
   | number
@@ -199,3 +206,107 @@ export function canManageSessions(
     typeof p.revokeAllSessions === "function"
   );
 }
+
+/**
+ * Everything Wasp hands a server-side adapter about the app it runs in.
+ *
+ * This is the adapter's *only* window into the app: adapters must not import
+ * generated code (`wasp/...`) and must not read `process.env` themselves. Keeping
+ * the boundary here is what lets an adapter package typecheck and version
+ * independently of any particular Wasp app.
+ */
+export type WaspServerRuntime = {
+  /**
+   * The app's PrismaClient instance. Typed as `unknown` because the client's type
+   * is generated per app; adapters that need it narrow it themselves.
+   */
+  db: unknown;
+
+  /**
+   * The Prisma datasource provider of the app's database: `"sqlite"`,
+   * `"postgresql"`, ... Adapters that bring their own storage layer (Better
+   * Auth's prisma adapter, for one) need to know the dialect they are talking to.
+   */
+  dbProvider: string;
+
+  /**
+   * The server-side environment, already validated against the env vars the
+   * adapter's manifest declared.
+   */
+  env: Record<string, string | undefined>;
+
+  /** The URL the Wasp server is reachable at. */
+  serverUrl: string;
+
+  /** The URL the Wasp client is served from. Useful for trusted-origin checks. */
+  clientUrl: string;
+
+  /**
+   * Report that the provider just created one of its own users.
+   *
+   * For adapters that can observe their signup moment (in-process providers
+   * like Better Auth; a hosted provider cannot). Wasp provisions the
+   * corresponding local user eagerly, so it exists from signup rather than
+   * from the first authenticated request. Calling it is optional and always
+   * safe: provisioning is idempotent, and just-in-time provisioning on first
+   * request remains the backstop regardless.
+   */
+  onAuthUserCreated?(authUser: {
+    subjectId: string;
+    claims?: Record<string, JsonValue>;
+  }): Promise<void>;
+};
+
+/**
+ * What an adapter's server entry produces: the provider itself, plus, for
+ * providers that own HTTP endpoints of their own (Better Auth's `/sign-in` and
+ * friends), the handler Wasp should mount at the manifest's `basePath`.
+ *
+ * One factory returns both so they are guaranteed to share one configured
+ * instance -- a provider verifying against one configuration while its routes run
+ * another is a bug class this shape makes unrepresentable.
+ */
+export type ServerAdapter = {
+  provider: AuthProvider;
+
+  /**
+   * Node-style request handler for the provider's own routes. Wasp mounts it at
+   * the `basePath` the adapter's manifest declared, with the app's usual
+   * middleware around it (minus the JSON body parser when the manifest asked for
+   * raw bodies).
+   */
+  routeHandler?: (
+    req: IncomingMessage,
+    res: ServerResponse,
+  ) => void | Promise<void>;
+};
+
+/**
+ * User-code extensions Wasp delivers alongside the serializable options.
+ *
+ * `setupFn` follows the same convention as Wasp's `prismaSetupFn`: a user
+ * function the adapter calls with its integration configuration, whose return
+ * value becomes the configuration to use. It is the escape hatch for
+ * everything a manifest cannot carry -- functions, class instances, live
+ * values -- so the user can reach the underlying library's full surface
+ * (Better Auth's hooks, plugins and email callbacks, say) without giving up
+ * the packaged adapter. Adapters should re-assert the invariants their
+ * integration depends on (route base paths, required plugins, table name
+ * overrides) after applying it.
+ */
+export type ServerAdapterExtensions = {
+  setupFn?: (config: never) => unknown;
+};
+
+/**
+ * The required shape of an adapter package's server entry: a named
+ * `createServerAdapter` export of this type. `options` is the serializable
+ * configuration the adapter's spec helper captured in `main.wasp.ts`, delivered
+ * verbatim; `extensions` carries the user-code escape hatches referenced by the
+ * manifest.
+ */
+export type ServerAdapterFactory<Options = unknown> = (
+  runtime: WaspServerRuntime,
+  options: Options,
+  extensions?: ServerAdapterExtensions,
+) => ServerAdapter | Promise<ServerAdapter>;

waspc/data/Generator/templates/sdk/wasp/package.json

@@ -131,6 +131,11 @@
     {=! Server: the contract a custom auth provider implements. Adapters live in
         user code, so they need to import this as a normal module. =}
     "./server/auth/provider/types": "./dist/server/auth/provider/types.js",
+    {=# isCustomAuthProviderUsed =}
+    {=! Server: the selected provider and its route handler, for mounting the
+        provider's own routes. =}
+    "./server/auth/provider": "./dist/server/auth/provider/index.js",
+    {=/ isCustomAuthProviderUsed =}
     "./server/auth/session": "./dist/server/auth/session.js",
     "./server/auth/utils": "./dist/server/auth/utils.js",
     "./server/core/auth": "./dist/server/core/auth.js",

waspc/data/Generator/templates/sdk/wasp/server/auth/provider/index.ts

@@ -1,7 +1,17 @@
 {{={= =}=}}
 import { {=# isCustomAuthProviderUsed =}canManageSessions as canProviderManagesSessions, canRevokeSessions as canProviderRevokeSessions, {=/ isCustomAuthProviderUsed =}type AuthProvider } from './types.js'
 {=# isCustomAuthProviderUsed =}
+{=# isPackageAuthProvider =}
+import { provisionAuthUser } from '../session.js'
+import { createServerAdapter } from '{= serverPackage =}'
+import { config, prisma } from '../../index.js'
+{=# externalSetupFn.isDefined =}
+{=& externalSetupFn.importStatement =}
+{=/ externalSetupFn.isDefined =}
+{=/ isPackageAuthProvider =}
+{=^ isPackageAuthProvider =}
 {=& authProvider.importStatement =}
+{=/ isPackageAuthProvider =}
 {=/ isCustomAuthProviderUsed =}
 {=^ isCustomAuthProviderUsed =}
 import { waspAuthProvider } from './wasp.js'
@@ -17,6 +27,38 @@ export {
   canRevokeSessions,
 } from './types.js'
 
+{=# isPackageAuthProvider =}
+/**
+ * The adapter package's server factory, called with everything it may know
+ * about the app. This runtime object is the adapter's *only* window into the
+ * app: adapters never import generated code and never read `process.env`
+ * themselves, which is what lets them version independently of any app.
+ */
+const serverAdapter = await Promise.resolve(
+  createServerAdapter(
+    {
+      db: prisma,
+      dbProvider: '{= dbProvider =}',
+      env: process.env,
+      serverUrl: config.serverUrl,
+      clientUrl: config.frontendUrl,
+      // The eager-provisioning channel: an in-process adapter reports its own
+      // signups, and the local user exists from that moment. Idempotent; JIT
+      // provisioning on first request remains the backstop.
+      onAuthUserCreated: async (authUser) => {
+        await provisionAuthUser(authUser.subjectId, authUser.claims)
+      },
+    },
+    {=& optionsJson =},
+    {
+      // The user's setup function for the adapter's underlying library; the
+      // adapter calls it with its integration config and uses the result.
+      setupFn: {=# externalSetupFn.isDefined =}{= externalSetupFn.importIdentifier =}{=/ externalSetupFn.isDefined =}{=^ externalSetupFn.isDefined =}undefined{=/ externalSetupFn.isDefined =},
+    },
+  ),
+)
+
+{=/ isPackageAuthProvider =}
 // PRIVATE API
 /**
  * The auth provider this app runs on.
@@ -26,7 +68,16 @@ export {
  * needed to authenticate against something other than Wasp's own auth.
  */
 export const authProvider: AuthProvider =
-  {=# isCustomAuthProviderUsed =}{= authProvider.importIdentifier =}{=/ isCustomAuthProviderUsed =}{=^ isCustomAuthProviderUsed =}waspAuthProvider{=/ isCustomAuthProviderUsed =}
+  {=# isCustomAuthProviderUsed =}{=# isPackageAuthProvider =}serverAdapter.provider{=/ isPackageAuthProvider =}{=^ isPackageAuthProvider =}{= authProvider.importIdentifier =}{=/ isPackageAuthProvider =}{=/ isCustomAuthProviderUsed =}{=^ isCustomAuthProviderUsed =}waspAuthProvider{=/ isCustomAuthProviderUsed =}
+{=# isPackageAuthProvider =}
+
+// PRIVATE API
+/**
+ * Node handler for the provider's own routes, if it brought any. The server
+ * mounts it at the basePath the manifest declared.
+ */
+export const authProviderRouteHandler = serverAdapter.routeHandler
+{=/ isPackageAuthProvider =}
 {=# isCustomAuthProviderUsed =}
 
 /**

waspc/data/Generator/templates/sdk/wasp/server/auth/provider/types.ts

@@ -43,3 +43,16 @@ export type RegisteredAuthProviderUserSignupFields = FromRegister<
   'authProviderUserSignupFields',
   UserSignupFields
 >
+
+// PRIVATE API
+/**
+ * The `setupFn` the developer registered on the external provider's manifest,
+ * if any: the setup function (the `prismaSetupFn` convention) that lets an app
+ * reach the underlying auth library's full configuration surface (hooks,
+ * plugins, email callbacks) while keeping the packaged adapter. The adapter
+ * types its parameter precisely; here it only has to be *a* function.
+ */
+export type RegisteredAuthProviderSetupFn = FromRegister<
+  'authProviderSetupFn',
+  (config: never) => unknown
+>

waspc/data/Generator/templates/sdk/wasp/server/auth/session.ts

@@ -212,6 +212,20 @@ function isUniqueConstraintViolation(e: unknown): boolean {
     typeof e === 'object' && e !== null && 'code' in e && (e as { code: unknown }).code === 'P2002'
   );
 }
+
+// PRIVATE API
+/**
+ * Eager provisioning: the runtime channel an in-process adapter calls when it
+ * observes its own signup, so the local user exists from that moment instead
+ * of from the first authenticated request. Same code path as just-in-time
+ * provisioning, called sooner -- idempotent by the same unique constraint.
+ */
+export async function provisionAuthUser(
+  subjectId: string,
+  claims: VerifiedSession['claims'],
+): Promise<void> {
+  await resolveExternalSubject(subjectId, claims);
+}
 {=/ isCustomAuthProviderUsed =}
 
 // PRIVATE API

waspc/data/Generator/templates/server/src/routes/index.js

@@ -5,6 +5,9 @@ import { globalMiddlewareConfigForExpress } from '../middleware/index.js'
 {=# isAuthEnabled =}
 import auth from './auth/index.js'
 {=/ isAuthEnabled =}
+{=# externalAuthProviderRoutes =}
+import { authProviderRouteHandler } from 'wasp/server/auth/provider'
+{=/ externalAuthProviderRoutes =}
 {=# areThereAnyCustomApiRoutes =}
 import apis from './apis/index.js'
 {=/ areThereAnyCustomApiRoutes =}
@@ -41,6 +44,25 @@ router.get('/', middleware,
 {=# isAuthEnabled =}
 router.use('/auth', middleware, auth)
 {=/ isAuthEnabled =}
+{=# externalAuthProviderRoutes =}
+// The external auth provider's own routes, mounted where its manifest asked.
+// The usual middleware stack applies{=# rawBody =}, minus the body parsers: the
+// provider's handler reads the raw request stream itself, and a body that was
+// already consumed would make every request to it hang{=/ rawBody =}.
+const authProviderMiddleware = globalMiddlewareConfigForExpress((middlewareConfig) => {
+  {=# rawBody =}
+  middlewareConfig.delete('express.json')
+  middlewareConfig.delete('express.urlencoded')
+  {=/ rawBody =}
+  return middlewareConfig
+})
+router.use('{= basePath =}', authProviderMiddleware, (req, res, next) => {
+  if (authProviderRouteHandler === undefined) {
+    return next(new Error('The auth provider manifest declares routes, but its server adapter returned no routeHandler.'))
+  }
+  return Promise.resolve(authProviderRouteHandler(req, res)).catch(next)
+})
+{=/ externalAuthProviderRoutes =}
 router.use('/{= operationsRouteInRootRouter =}', middleware, operations)
 {=# areThereAnyCrudRoutes =}
 router.use('/{= crudRouteInRootRouter =}', middleware, rootCrudRouter)

waspc/data/Generator/templates/types/app/sdk/register.ts

@@ -18,6 +18,9 @@ declare module "wasp/types" {
     {=# authProviderUserSignupFields.isDefined =}
     authProviderUserSignupFields: typeof {=& authProviderUserSignupFields.dynamicImportExpression =}
     {=/ authProviderUserSignupFields.isDefined =}
+    {=# authProviderSetupFn.isDefined =}
+    authProviderSetupFn: typeof {=& authProviderSetupFn.dynamicImportExpression =}
+    {=/ authProviderSetupFn.isDefined =}
     {=# serverEnvValidationSchema.isDefined =}
     serverEnvValidationSchema: typeof {=& serverEnvValidationSchema.dynamicImportExpression =}
     {=/ serverEnvValidationSchema.isDefined =}