code review comments fixes

Author: Rajat

apps/api/README.md

@@ -315,6 +315,8 @@ CIMD, while existing clients can use Dynamic Client Registration (DCR); static
 pre-registered clients are also supported. OAuth tool access is
 default-deny using the scope map in `src/mcp/policy.ts`. Team API keys have full
 tool access to their fixed team, while browser session cookies are rejected.
+OAuth authorization requests must include an explicit, non-empty `scope` so a
+missing value cannot expand to the client's complete capability set.
 
 MCP tools live in `src/mcp/tools/*` and cover contacts, templates, sequences,
 ESP settings (both the default-ESP singleton tools and the multi-ESP

apps/api/docs/mcp-2026-07-28-migration.md

@@ -178,6 +178,11 @@ OAuth calls must contain the tool's required scope. Team API keys currently
 have full access to their fixed team because scoped team keys are not yet a
 SendLit API-key product feature.
 
+Dynamic registration and discovery use identity-only default scopes. All MCP
+scopes remain requestable capabilities, but `/oauth2/authorize` rejects a
+missing or empty `scope` rather than allowing Better Auth to substitute the
+client's complete capability set.
+
 The supported scope families are contacts, templates, media, sequences,
 emails, settings, ESP configuration, teams, API keys, feedback, delivery
 events, and suppressions, with read/write or read/send separation as

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

@@ -19,16 +19,58 @@ vi.mock("../organization/queries", () => ({
 
 describe("Better Auth MCP authorization metadata", () => {
     let auth: (typeof import("./better-auth.js"))["auth"];
+    let defaultScopes: (typeof import("./better-auth.js"))["OAUTH_CLIENT_DEFAULT_SCOPES"];
+    let requestableScopes: (typeof import("./better-auth.js"))["OAUTH_CLIENT_REQUESTABLE_SCOPES"];
 
     beforeAll(async () => {
         vi.stubEnv(
             "BETTER_AUTH_SECRET",
             "test-only-secret-with-at-least-thirty-two-characters",
         );
         vi.stubEnv("API_PUBLIC_URL", "https://sendlit.test");
-        ({ auth } = await import("./better-auth.js"));
+        const betterAuthModule = await import("./better-auth.js");
+        auth = betterAuthModule.auth;
+        defaultScopes = betterAuthModule.OAUTH_CLIENT_DEFAULT_SCOPES;
+        requestableScopes = betterAuthModule.OAUTH_CLIENT_REQUESTABLE_SCOPES;
     });
 
+    it("keeps registration defaults identity-only while allowing MCP scopes", () => {
+        expect(defaultScopes).toEqual(["openid", "profile", "email"]);
+        expect(requestableScopes).toEqual(
+            expect.arrayContaining(["offline_access", ...MCP_SCOPES_SUPPORTED]),
+        );
+        expect(defaultScopes).not.toEqual(
+            expect.arrayContaining([...MCP_SCOPES_SUPPORTED]),
+        );
+    });
+
+    it.each(["", "   "])(
+        "rejects authorization without an explicit scope (%j)",
+        async (scope) => {
+            const query = new URLSearchParams({
+                response_type: "code",
+                client_id: "test-client",
+                redirect_uri: "https://client.example/callback",
+                code_challenge: "test-code-challenge",
+                code_challenge_method: "S256",
+            });
+            if (scope.length > 0) query.set("scope", scope);
+
+            const response = await auth.handler(
+                new Request(
+                    `https://sendlit.test/api/auth/oauth2/authorize?${query}`,
+                ),
+            );
+
+            expect(response.status).toBe(400);
+            await expect(response.json()).resolves.toMatchObject({
+                error: "invalid_scope",
+                error_description:
+                    "OAuth authorization requests must include an explicit scope.",
+            });
+        },
+    );
+
     it("advertises CIMD, DCR, issuer protection, and all enforced MCP scopes", async () => {
         const response = await auth.handler(
             new Request(

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

@@ -1,4 +1,5 @@
 import { betterAuth } from "better-auth";
+import { APIError, createAuthMiddleware } from "better-auth/api";
 import { drizzleAdapter } from "better-auth/adapters/drizzle";
 import { emailOTP } from "better-auth/plugins/email-otp";
 import { jwt } from "better-auth/plugins/jwt";
@@ -52,13 +53,19 @@ export const mcpResourceUrl = `${authBaseUrl}/mcp`;
  * single source of truth shared between `oauthProvider({ validAudiences })`
  * below and `resolve-auth.ts`'s bearer verification. */
 export const validOAuthAudiences = [authBaseUrl, mcpResourceUrl];
-const supportedOAuthScopes = [
+export const OAUTH_CLIENT_DEFAULT_SCOPES = [
     "openid",
     "profile",
     "email",
+] as const;
+export const OAUTH_CLIENT_REQUESTABLE_SCOPES = [
     "offline_access",
     ...MCP_SCOPES_SUPPORTED,
 ] as const;
+const supportedOAuthScopes = [
+    ...OAUTH_CLIENT_DEFAULT_SCOPES,
+    ...OAUTH_CLIENT_REQUESTABLE_SCOPES,
+] as const;
 
 /** Where an MCP client should discover `mcpResourceUrl`'s protected-resource
  * metadata (RFC 9728: `<origin>/.well-known/oauth-protected-resource<path>`).
@@ -172,6 +179,25 @@ export const auth = betterAuth({
             },
         },
     },
+    hooks: {
+        before: createAuthMiddleware(async (context) => {
+            if (context.path !== "/oauth2/authorize") return;
+
+            const scope = context.query?.scope;
+            if (typeof scope === "string" && scope.trim().length > 0) return;
+
+            // Better Auth persists the union of registration defaults and
+            // allowed scopes as the client's capability set, then treats that
+            // complete set as requested when `scope` is omitted. Require an
+            // explicit choice so a scope-less request can never become a
+            // full-access MCP grant.
+            throw new APIError("BAD_REQUEST", {
+                error: "invalid_scope",
+                error_description:
+                    "OAuth authorization requests must include an explicit scope.",
+            });
+        }),
+    },
     plugins: [
         emailOTP({
             async sendVerificationOTP({ email, otp }) {
@@ -199,12 +225,12 @@ export const auth = betterAuth({
                 allowUnauthenticatedDynamicClientRegistration: true,
                 scopes: supportedOAuthScopes,
                 validAudiences: validOAuthAudiences,
-                // CIMD documents such as VS Code's describe redirect URIs and
-                // grant types but do not predeclare SendLit-specific scopes.
-                // Allow the client to request the scopes it presents to the
-                // user at authorization time; per-tool enforcement remains
-                // default-deny in the MCP policy registry.
-                clientRegistrationDefaultScopes: supportedOAuthScopes,
+                // Registration establishes capabilities, not grants. Keep the
+                // default set identity-only and allow clients to explicitly
+                // request the narrower MCP scope set they present at consent.
+                clientRegistrationDefaultScopes: OAUTH_CLIENT_DEFAULT_SCOPES,
+                clientRegistrationAllowedScopes:
+                    OAUTH_CLIENT_REQUESTABLE_SCOPES,
             }),
             // The authorization request's RFC 8707 `resource` value must
             // resolve to a persisted provider resource. Seed the sole current

apps/docs/content/docs/developers/authentication.mdx

@@ -26,6 +26,8 @@ HTTPS metadata-document URL. Modern clients should prefer CIMD; DCR remains
 available for existing clients. Clients must use Authorization Code
 with S256 PKCE and request only the MCP scopes they need; the complete scope
 list and tool groups are documented on the [MCP server page](/developers/mcp).
+Authorization requests must include an explicit `scope`; SendLit rejects an
+omitted or empty value instead of granting the client's complete capability set.
 Unauthenticated DCR is rate-limited to 20 requests per IP per minute.
 For a multi-team account, SendLit asks the user to choose the team during the
 OAuth flow; the resulting token is restricted to that chosen team.

apps/docs/content/docs/developers/mcp.mdx

@@ -42,7 +42,7 @@ GET /.well-known/openid-configuration
 
 OAuth authorization, consent, token, introspection, revocation, and userinfo endpoints are provided under `/api/auth/oauth2/*`. SendLit supports pre-registered clients, Client ID Metadata Documents (CIMD), and Dynamic Client Registration (DCR). For CIMD, the OAuth `client_id` is the HTTPS URL of the client's metadata document. Modern clients should prefer CIMD; DCR remains available for existing clients such as MCP Inspector.
 
-Use Authorization Code with S256 PKCE, request only the scopes your client needs, and keep any refresh token in the client's secure credential store. Every authorization requires a SendLit user to sign in, select a team when necessary, and approve consent.
+Use Authorization Code with S256 PKCE, request only the scopes your client needs, and keep any refresh token in the client's secure credential store. The authorization request must include an explicit, non-empty `scope`; SendLit does not turn a missing value into a full-access grant. Every authorization requires a SendLit user to sign in, select a team when necessary, and approve consent.
 
 API keys always select one fixed team and currently grant the complete MCP tool set for that team. Dashboard session cookies and `X-Sendlit-Team-Id` are not accepted as MCP authentication.