Using oauth-server-kit for auth

Author: Rajat

AGENTS.md

@@ -11,3 +11,9 @@
 ## Branch management
 
 - Never push on your own. Leave it to the human.
+
+## Testing Tips
+
+- From browser based smoke testing, boot up the API and Web app using `pnpm dev:api` and `pnpm dev:web` respectively.
+- The following docker containers need to be running: `postgres`, `redis`, `mailpit` for full integration testing.
+- Prefer Chrome DevTools MCP for browser-based debugging, in the headful mode.

apps/api/docs/bounces-and-complaints.md

@@ -1036,6 +1036,7 @@ feedback_invalid_credentials
 feedback_test_failed
 feedback_connection_retiring
 esp_not_found
+esp_not_active
 recipient_suppressed
 suppression_not_releasable
 suppression_not_found

apps/api/docs/organizations.md

@@ -2160,31 +2160,32 @@ content, or unredacted webhook credentials.
 
 ## Failure semantics
 
-| Status | Code                                | Meaning                                              |
-| ------ | ----------------------------------- | ---------------------------------------------------- |
-| 400    | `invalid_delivery_source`           | Malformed/conflicting selection                      |
-| 401    | `invalid_organization_key`          | Missing, invalid, expired, or revoked key            |
-| 403    | `organization_scope_required`       | Key lacks required scope                             |
-| 403    | `not_an_organization_member`        | User has no membership                               |
-| 403    | `team_esp_disabled`                 | Organization policy forbids team ESP mutation/use    |
-| 403    | `organization_delivery_disabled`    | Team lacks an active organization grant              |
-| 403    | `team_sending_suspended`            | Team cannot dispatch                                 |
-| 404    | `organization_not_found`            | Missing/inaccessible organization                    |
-| 404    | `esp_not_found`                     | Missing/foreign ESP in the relevant owner scope      |
-| 409    | `provisioning_conflict`             | External ID exists with conflicting immutable fields |
-| 409    | `delivery_source_in_use`            | Unsafe source disable/delete                         |
-| 409    | `invalid_lifecycle_transition`      | ESP/grant transition is not permitted                |
-| 409    | `last_organization_owner`           | Operation would leave no owner                       |
-| 422    | `delivery_source_required`          | No unambiguous default                               |
-| 422    | `delivery_source_unavailable`       | Team has no active shared or team-owned source       |
-| 422    | `organization_esp_unavailable`      | Grant/ESP cannot currently send                      |
-| 422    | `esp_verification_required`         | ESP changed or has not passed its latest test        |
-| 422    | `provider_capability_required`      | Provider lacks a required organization capability    |
-| 422    | `team_esp_not_configured`           | Team source selected without ESP                     |
-| 422    | `sender_unverified`                 | Selected sender is not usable                        |
-| 429    | `organization_team_quota_exhausted` | Grant quota exhausted                                |
-| 429    | `organization_quota_exhausted`      | Aggregate organization quota exhausted               |
-| 503    | `user_onboarding_pending`           | Default organization bootstrap has not completed     |
+| Status | Code                                | Meaning                                                        |
+| ------ | ----------------------------------- | -------------------------------------------------------------- |
+| 400    | `invalid_delivery_source`           | Malformed/conflicting selection                                |
+| 401    | `invalid_organization_key`          | Missing, invalid, expired, or revoked key                      |
+| 403    | `organization_scope_required`       | Key lacks required scope                                       |
+| 403    | `not_an_organization_member`        | User has no membership                                         |
+| 403    | `team_esp_disabled`                 | Organization policy forbids team ESP mutation/use              |
+| 403    | `organization_delivery_disabled`    | Team lacks an active organization grant                        |
+| 403    | `team_sending_suspended`            | Team cannot dispatch                                           |
+| 404    | `organization_not_found`            | Missing/inaccessible organization                              |
+| 404    | `esp_not_found`                     | Missing/foreign ESP in the relevant owner scope                |
+| 409    | `provisioning_conflict`             | External ID exists with conflicting immutable fields           |
+| 409    | `delivery_source_in_use`            | Unsafe source disable/delete                                   |
+| 409    | `invalid_lifecycle_transition`      | ESP/grant transition is not permitted                          |
+| 409    | `last_organization_owner`           | Operation would leave no owner                                 |
+| 422    | `delivery_source_required`          | No unambiguous default                                         |
+| 422    | `delivery_source_unavailable`       | Team has no active shared or team-owned source                 |
+| 422    | `organization_esp_unavailable`      | Grant/ESP cannot currently send                                |
+| 422    | `esp_verification_required`         | ESP changed or has not passed its latest test                  |
+| 422    | `esp_not_active`                    | Team ESP exists but must be activated before default selection |
+| 422    | `provider_capability_required`      | Provider lacks a required organization capability              |
+| 422    | `team_esp_not_configured`           | Team source selected without ESP                               |
+| 422    | `sender_unverified`                 | Selected sender is not usable                                  |
+| 429    | `organization_team_quota_exhausted` | Grant quota exhausted                                          |
+| 429    | `organization_quota_exhausted`      | Aggregate organization quota exhausted                         |
+| 503    | `user_onboarding_pending`           | Default organization bootstrap has not completed               |
 
 ## REST, OpenAPI, MCP, and web requirements
 

apps/api/docs/replace-oauth-server-with-better-auth.md

@@ -3,6 +3,21 @@
 **Objective**
 Replace SendLit’s custom OAuth2/auth implementation with Better Auth to support secure first-party web login, MCP OAuth, REST API authentication, and social login with Google plus Email OTP.
 
+**Implementation status**
+
+Better Auth remains SendLit's product-local authorization server and owns its
+users, sessions, OAuth clients, consent, signing keys, and database adapter.
+The shared `@codelitdev/oauth-server-kit` now owns the reusable protocol layer:
+safe OAuth-provider defaults, hosted login/consent pages, session and bearer
+authentication results, and MCP/OAuth discovery metadata. SendLit continues to
+own organization keys, team keys, organization provisioning, team membership,
+multi-team OAuth selection, and authorization after authentication.
+
+MCP Dynamic Client Registration (DCR) is intentionally enabled. Clients may
+register public OAuth clients without prior credentials, but registration is
+limited to SendLit's declared OAuth scopes; public clients must use PKCE.
+Unauthenticated registration is rate-limited to 20 requests per IP per minute.
+
 **Background**
 SendLit currently has a custom OAuth2 implementation in `apps/api/src/oauth/*` and a BFF session/token flow in `apps/web/app/api/auth/*` and `apps/web/app/api/proxy/[...path]/route.ts`.
 
@@ -248,14 +263,20 @@ type AuthResult =
 
 Resolution order:
 
-1. API key if `x-sendlit-apikey` is present.
-2. OAuth bearer token if `Authorization: Bearer` is present.
-3. Better Auth session if cookies are present.
-4. Missing/unauthorized.
+1. An explicit organization key when `Authorization: Bearer sl_org_live_...`
+   is present.
+2. An OAuth bearer token for every other explicit `Authorization: Bearer`
+   credential.
+3. A team API key from `x-sendlit-apikey` or the legacy request body field.
+4. A Better Auth session if cookies are present.
+5. Missing/unauthorized.
 
 Important:
 
 - Invalid bearer token must not fall back to API key.
+- An organization key is SendLit product authentication, not an OAuth token;
+  it is accepted only for its explicit `sl_org_live_...` prefix and is then
+  authorized by its own SendLit scopes.
 - API key must remain team-scoped.
 - Session/OAuth account auth must still pass through team membership checks.
 
@@ -266,8 +287,10 @@ Important:
 - Dashboard must not store bearer tokens in localStorage.
 - OAuth public clients must use PKCE.
 - Dynamic client registration must be intentionally configured:
-    - unrestricted only if MCP requires it;
-    - otherwise require authenticated/admin registration.
+    - SendLit permits unauthenticated public-client registration for MCP;
+    - registration is limited to the declared OAuth scopes;
+    - public clients must use PKCE and registration is limited to 20 requests
+      per IP per minute.
 - Access tokens must have clear audience/resource validation.
 - OAuth scopes must map to SendLit permissions.
 - Login and consent pages must set anti-clickjacking headers:

apps/api/package.json

@@ -20,6 +20,7 @@
     },
     "dependencies": {
         "@better-auth/oauth-provider": "^1.6.23",
+        "@codelitdev/oauth-server-kit": "0.1.0-alpha.0",
         "@modelcontextprotocol/sdk": "^1.29.0",
         "@sendlit/api-contract": "workspace:*",
         "@sendlit/email-blocks": "workspace:*",

apps/api/src/auth/better-auth.ts

@@ -4,17 +4,22 @@ import { emailOTP } from "better-auth/plugins/email-otp";
 import { jwt } from "better-auth/plugins/jwt";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { oauthProviderResourceClient } from "@better-auth/oauth-provider/resource-client";
+import { createOAuthProviderOptions } from "@codelitdev/oauth-server-kit/better-auth";
+import type { HostedLoginMethod } from "@codelitdev/oauth-server-kit/express";
 import { createTransport } from "nodemailer";
 import { db } from "../db/client";
 import * as schema from "../db/schema";
 import logger from "../services/log";
 import { ensureDefaultOrganization } from "../organization/queries";
-import { getOAuthTeamSelection, listTeamsForUser } from "../team/queries";
+import {
+    createSendLitOAuthTeamSelectionHooks,
+    oauthTeamSelectionAdapter,
+} from "./oauth-team-selection";
 
 export const webClientUrl = process.env.WEB_CLIENT || "http://localhost:3000";
 const apiUrl = process.env.API_PUBLIC_URL || process.env.BETTER_AUTH_URL;
 const authBaseUrl = apiUrl || "http://localhost:5000";
-const authBasePath = "/api/auth";
+export const authBasePath = "/api/auth";
 
 /** Parent domain shared by `apps/web` and `apps/api` in production (e.g.
  * `sendlit.example.com`, covering both `app.sendlit.example.com` and
@@ -93,28 +98,20 @@ async function sendOtpEmail(email: string, otp: string) {
     });
 }
 
-/** The internal team id an OAuth end-user picked on `/oauth/select-team`
- * (`null` for a single-team user, which never sees that screen — see
- * `oauthPostLoginTeamSelections` in `db/schema.ts`). Shared by
- * `postLogin.shouldRedirect` and `postLogin.consentReferenceId` below so both
- * always agree on the same account/selection lookup. */
-async function resolveOAuthTeamSelection(
-    userId: string,
-    sessionId: string,
-): Promise<{ requiresSelection: boolean; selectedTeamId: string | null }> {
-    const teams = await listTeamsForUser(userId);
-    if (teams.length <= 1) {
-        return { requiresSelection: false, selectedTeamId: null };
-    }
+export { oauthTeamSelectionAdapter };
 
-    const selectedTeamId = await getOAuthTeamSelection(sessionId);
-    const stillValid =
-        selectedTeamId != null && teams.some((t) => t.id === selectedTeamId);
-    return {
-        requiresSelection: !stillValid,
-        selectedTeamId: stillValid ? selectedTeamId : null,
-    };
-}
+export const hostedLoginMethods: HostedLoginMethod[] = [
+    { type: "email-otp" },
+    ...(googleClientId && googleClientSecret
+        ? [
+              {
+                  type: "social" as const,
+                  providerId: "google",
+                  label: "Continue with Google",
+              },
+          ]
+        : []),
+];
 
 export const auth = betterAuth({
     appName: "SendLit",
@@ -180,57 +177,47 @@ export const auth = betterAuth({
         }),
         jwt(),
         oauthProvider({
-            // Self-hosted by this API (see ./oauth-pages.ts), not the web
-            // dashboard — so a new MCP/OAuth client can complete its first
-            // authorization even where the web app isn't deployed at all.
-            loginPage: `${authBaseUrl}/oauth/login`,
-            consentPage: `${authBaseUrl}/oauth/consent`,
-            allowDynamicClientRegistration: true,
-            allowUnauthenticatedClientRegistration: true,
-            scopes: [
-                "openid",
-                "profile",
-                "email",
-                "offline_access",
-                "contacts:read",
-                "contacts:write",
-                "templates:read",
-                "templates:write",
-                "media:read",
-                "media:write",
-                "broadcasts:write",
-                "sequences:read",
-                "sequences:write",
-            ],
-            validAudiences: validOAuthAudiences,
-            // Interposed between login and consent for a multi-team account
-            // (self-hosted at ./oauth-pages.ts, mirroring Notion's "select a
-            // workspace" step) — an OAuth/MCP client has no standard way to
-            // tell SendLit which team to scope its access to, so this is the
-            // only point in the flow where that can be resolved.
-            postLogin: {
+            ...createOAuthProviderOptions({
+                loginPage: `${authBaseUrl}/oauth/login`,
+                consentPage: `${authBaseUrl}/oauth/consent`,
+                // MCP clients may register their own public OAuth client.
+                // Registration is constrained to SendLit's supported scopes.
+                allowDynamicClientRegistration: true,
+                allowUnauthenticatedDynamicClientRegistration: true,
+                scopes: [
+                    "openid",
+                    "profile",
+                    "email",
+                    "offline_access",
+                    "contacts:read",
+                    "contacts:write",
+                    "templates:read",
+                    "templates:write",
+                    "media:read",
+                    "media:write",
+                    "broadcasts:write",
+                    "sequences:read",
+                    "sequences:write",
+                ],
+                validAudiences: validOAuthAudiences,
+                clientRegistrationDefaultScopes: ["openid", "profile", "email"],
+                clientRegistrationAllowedScopes: [
+                    "offline_access",
+                    "contacts:read",
+                    "contacts:write",
+                    "templates:read",
+                    "templates:write",
+                    "media:read",
+                    "media:write",
+                    "broadcasts:write",
+                    "sequences:read",
+                    "sequences:write",
+                ],
+            }),
+            ...createSendLitOAuthTeamSelectionHooks({
                 page: `${authBaseUrl}/oauth/select-team`,
-                shouldRedirect: async ({ user, session }) => {
-                    const { requiresSelection } =
-                        await resolveOAuthTeamSelection(user.id, session.id);
-                    return requiresSelection;
-                },
-                consentReferenceId: async ({ user, session }) => {
-                    const { selectedTeamId } = await resolveOAuthTeamSelection(
-                        user.id,
-                        session.id,
-                    );
-                    return selectedTeamId ?? undefined;
-                },
-            },
-            // Carries the picked team (the `referenceId` above) onto the
-            // minted access token so `resolve-auth.ts` can scope a request
-            // without relying on `X-Sendlit-Team-Id`, which generic OAuth
-            // clients never send. Single-team accounts have no referenceId
-            // and fall back to `require-team.ts`'s existing auto-select.
-            customAccessTokenClaims: async ({ referenceId }) => {
-                return referenceId ? { team_id: referenceId } : {};
-            },
+                adapter: oauthTeamSelectionAdapter,
+            }),
         }),
     ],
 });

apps/api/src/auth/middleware.ts

@@ -1,13 +1,13 @@
-import { NextFunction, Response } from "express";
-import { AuthResult, resolveAuth, sendAuthError } from "./resolve-auth";
+import type { NextFunction, Request, Response } from "express";
+import {
+    type AuthInput,
+    type AuthResult,
+    resolveAuth,
+    sendAuthError,
+} from "./resolve-auth";
 import { mcpProtectedResourceMetadataUrl } from "./better-auth";
 
-type AuthResolver = (input: {
-    authorization?: unknown;
-    apiKeyHeader?: unknown;
-    bodyApiKey?: unknown;
-    headers?: Record<string, string | string[] | undefined>;
-}) => Promise<AuthResult>;
+type AuthResolver = (input: AuthInput) => Promise<AuthResult>;
 
 type AuthMiddlewareMode = "rest" | "mcp";
 
@@ -53,22 +53,29 @@ export function createAuthMiddleware(
     resourceMetadataUrl?: string,
 ) {
     return async function authMiddleware(
-        req: any,
+        req: Request,
         res: Response,
         next: NextFunction,
     ): Promise<void> {
-        const auth = await authResolver({
-            authorization: req.headers.authorization,
-            apiKeyHeader: req.headers["x-sendlit-apikey"],
-            bodyApiKey: req.body?.apikey,
-            headers: req.headers,
-        });
+        try {
+            const auth = await authResolver({
+                authorization: req.headers.authorization,
+                apiKeyHeader: req.headers["x-sendlit-apikey"],
+                bodyApiKey: req.body?.apikey,
+                headers: req.headers,
+            });
 
-        if (sendAuthError(res, auth, resourceMetadataUrl)) return;
-        if (auth.status !== "authenticated") return;
+            if (sendAuthError(res, auth, resourceMetadataUrl)) return;
+            if (auth.status !== "authenticated") return;
 
-        applyAuthToRequest(req, auth, mode);
-        next();
+            applyAuthToRequest(req, auth, mode);
+            if (auth.kind === "oauth" || auth.kind === "session") {
+                req.auth = auth.identity;
+            }
+            next();
+        } catch (error) {
+            next(error);
+        }
     };
 }