feat: OAuth client scopes

apps/api/v2/src/modules/auth/guards/permissions/permissions.guard.spec.ts

@@ -1,15 +1,19 @@
-import { OAuthClientRepository } from "@/modules/oauth-clients/oauth-client.repository";
-import { OAuthClientsOutputService } from "@/modules/oauth-clients/services/oauth-clients/oauth-clients-output.service";
-import { TokensRepository } from "@/modules/tokens/tokens.repository";
-import { TokensService } from "@/modules/tokens/tokens.service";
+import {
+  APPS_WRITE,
+  BOOKING_READ,
+  BOOKING_WRITE,
+  SCHEDULE_READ,
+  SCHEDULE_WRITE,
+} from "@calcom/platform-constants";
 import { createMock } from "@golevelup/ts-jest";
 import { ExecutionContext } from "@nestjs/common";
 import { ConfigService } from "@nestjs/config";
 import { Reflector } from "@nestjs/core";
-
-import { APPS_WRITE, SCHEDULE_READ, SCHEDULE_WRITE } from "@calcom/platform-constants";
-
 import { PermissionsGuard } from "./permissions.guard";
+import { OAuthClientRepository } from "@/modules/oauth-clients/oauth-client.repository";
+import { OAuthClientsOutputService } from "@/modules/oauth-clients/services/oauth-clients/oauth-clients-output.service";
+import { TokensRepository } from "@/modules/tokens/tokens.repository";
+import { TokensService } from "@/modules/tokens/tokens.service";
 
 describe("PermissionsGuard", () => {
   let guard: PermissionsGuard;
@@ -76,6 +80,7 @@ describe("PermissionsGuard", () => {
     it("should return true for valid permissions", async () => {
       const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
       jest.spyOn(reflector, "get").mockReturnValue([SCHEDULE_WRITE]);
+      jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue(null);
 
       let oAuthClientPermissions = 0;
       oAuthClientPermissions |= SCHEDULE_WRITE;
@@ -88,6 +93,7 @@ describe("PermissionsGuard", () => {
     it("should return true for multiple valid permissions", async () => {
       const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
       jest.spyOn(reflector, "get").mockReturnValue([SCHEDULE_WRITE, SCHEDULE_READ]);
+      jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue(null);
 
       let oAuthClientPermissions = 0;
       oAuthClientPermissions |= SCHEDULE_WRITE;
@@ -143,15 +149,60 @@ describe("PermissionsGuard", () => {
       );
     });
 
-    it("should return true for 3rd party access token", async () => {
+    it("should return true for 3rd party access token with legacy/unknown scopes (backward compat)", async () => {
+      const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
+      jest.spyOn(reflector, "get").mockReturnValue([SCHEDULE_WRITE]);
+      jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue({
+        scope: ["READ_BOOKING"],
+        token_type: "Bearer",
+      });
+
+      await expect(guard.canActivate(mockContext)).resolves.toBe(true);
+    });
+
+    it("should return true for 3rd party access token with empty scopes (backward compat)", async () => {
+      const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
+      jest.spyOn(reflector, "get").mockReturnValue([SCHEDULE_WRITE]);
+      jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue({
+        scope: [],
+        token_type: "Bearer",
+      });
+
+      await expect(guard.canActivate(mockContext)).resolves.toBe(true);
+    });
+
+    it("should return true for 3rd party access token with matching new scopes", async () => {
       const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
+      jest.spyOn(reflector, "get").mockReturnValue([BOOKING_READ]);
       jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue({
-        scope: ["scope"],
+        scope: ["BOOKING_READ", "BOOKING_WRITE"],
         token_type: "Bearer",
       });
 
       await expect(guard.canActivate(mockContext)).resolves.toBe(true);
     });
+
+    it("should throw for 3rd party access token with insufficient new scopes", async () => {
+      const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
+      jest.spyOn(reflector, "get").mockReturnValue([BOOKING_WRITE]);
+      jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue({
+        scope: ["BOOKING_READ"],
+        token_type: "Bearer",
+      });
+
+      await expect(guard.canActivate(mockContext)).rejects.toThrow("insufficient_scope");
+    });
+
+    it("should throw for 3rd party token when endpoint requires permission without scope mapping", async () => {
+      const mockContext = createMockExecutionContext({ Authorization: "Bearer token" });
+      jest.spyOn(reflector, "get").mockReturnValue([APPS_WRITE]);
+      jest.spyOn(guard, "getDecodedThirdPartyAccessToken").mockReturnValue({
+        scope: ["BOOKING_READ"],
+        token_type: "Bearer",
+      });
+
+      await expect(guard.canActivate(mockContext)).rejects.toThrow("insufficient_scope");
+    });
   });
 
   describe("when OAuth id is provided", () => {

apps/api/v2/src/modules/auth/guards/permissions/permissions.guard.ts

@@ -1,17 +1,35 @@
+import {
+  BOOKING_READ,
+  BOOKING_WRITE,
+  EVENT_TYPE_READ,
+  EVENT_TYPE_WRITE,
+  PROFILE_READ,
+  SCHEDULE_READ,
+  SCHEDULE_WRITE,
+  X_CAL_CLIENT_ID,
+} from "@calcom/platform-constants";
+import { hasPermissions } from "@calcom/platform-utils";
+import type { PlatformOAuthClient } from "@calcom/prisma/client";
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { Reflector } from "@nestjs/core";
+import { getToken } from "next-auth/jwt";
 import { isApiKey } from "@/lib/api-key";
 import { Permissions } from "@/modules/auth/decorators/permissions/permissions.decorator";
 import { OAuthClientRepository } from "@/modules/oauth-clients/oauth-client.repository";
 import { OAuthClientsOutputService } from "@/modules/oauth-clients/services/oauth-clients/oauth-clients-output.service";
 import { TokensRepository } from "@/modules/tokens/tokens.repository";
 import { TokensService } from "@/modules/tokens/tokens.service";
-import { Injectable, CanActivate, ExecutionContext, ForbiddenException } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
-import { Reflector } from "@nestjs/core";
-import { getToken } from "next-auth/jwt";
 
-import { X_CAL_CLIENT_ID } from "@calcom/platform-constants";
-import { hasPermissions } from "@calcom/platform-utils";
-import type { PlatformOAuthClient } from "@calcom/prisma/client";
+const SCOPE_TO_PERMISSION: Record<string, number> = {
+  EVENT_TYPE_READ: EVENT_TYPE_READ,
+  EVENT_TYPE_WRITE: EVENT_TYPE_WRITE,
+  BOOKING_READ: BOOKING_READ,
+  BOOKING_WRITE: BOOKING_WRITE,
+  SCHEDULE_READ: SCHEDULE_READ,
+  SCHEDULE_WRITE: SCHEDULE_WRITE,
+  PROFILE_READ: PROFILE_READ,
+};
 
 @Injectable()
 export class PermissionsGuard implements CanActivate {
@@ -37,13 +55,17 @@ export class PermissionsGuard implements CanActivate {
     const nextAuthToken = await getToken({ req: request, secret: nextAuthSecret });
     const oAuthClientId = request.params?.clientId || request.get(X_CAL_CLIENT_ID);
     const apiKey = bearerToken && isApiKey(bearerToken, this.config.get("api.apiKeyPrefix") ?? "cal_");
-    const isThirdPartyBearerToken = bearerToken && this.getDecodedThirdPartyAccessToken(bearerToken);
+    const decodedThirdPartyToken = bearerToken ? this.getDecodedThirdPartyAccessToken(bearerToken) : null;
 
-    // only check permissions for accessTokens attached to platform oAuth Client or platform oAuth credentials, not for next token or api key or third party oauth client
-    if (nextAuthToken || apiKey || isThirdPartyBearerToken) {
+    // NextAuth sessions and API keys have full access
+    if (nextAuthToken || apiKey) {
       return true;
     }
 
+    if (decodedThirdPartyToken) {
+      return this.checkThirdPartyTokenPermissions(decodedThirdPartyToken, requiredPermissions);
+    }
+
     if (!bearerToken && !oAuthClientId) {
       throw new ForbiddenException(
         "PermissionsGuard - no authentication provided. Provide either authorization bearer token containing managed user access token or oAuth client id in 'x-cal-client-id' header."
@@ -91,6 +113,48 @@ export class PermissionsGuard implements CanActivate {
     return oAuthClient;
   }
 
+  checkThirdPartyTokenPermissions(
+    decodedToken: { scope?: string[] },
+    requiredPermissions: number[]
+  ): boolean {
+    const tokenScopes: string[] = decodedToken.scope ?? [];
+
+    if (tokenScopes.length === 0) {
+      return true;
+    }
+
+    const tokenPermissions = this.resolveTokenPermissions(tokenScopes);
+
+    // note(Lauris): legacy access tokens either did not have scopes defined or had legacy scopes defined,
+    // if so give full access just like we have been doing up until now.
+    if (tokenPermissions.size === 0) {
+      return true;
+    }
+
+    const missing = requiredPermissions.filter((permission) => !tokenPermissions.has(permission));
+    if (missing.length > 0) {
+      const missingNames = missing
+        .map((permission) => Object.entries(SCOPE_TO_PERMISSION).find(([, value]) => value === permission)?.[0] ?? `UNKNOWN(${permission})`)
+        .filter(Boolean);
+      throw new ForbiddenException(
+        `insufficient_scope: token does not have the required scopes. Required: ${missingNames.join(", ")}. Token has: ${tokenScopes.join(", ")}`
+      );
+    }
+
+    return true;
+  }
+
+  private resolveTokenPermissions(scopes: string[]): Set<number> {
+    const permissions = new Set<number>();
+    for (const scope of scopes) {
+      const permission = SCOPE_TO_PERMISSION[scope];
+      if (permission !== undefined) {
+        permissions.add(permission);
+      }
+    }
+    return permissions;
+  }
+
   getDecodedThirdPartyAccessToken(bearerToken: string) {
     return this.tokensService.getDecodedThirdPartyAccessToken(bearerToken);
   }

apps/web/app/api/auth/oauth/refreshToken/route.ts

@@ -1,12 +1,12 @@
-import { defaultResponderForAppDir } from "app/api/defaultResponderForAppDir";
-import { parseUrlFormData } from "app/api/parseRequestData";
-import { NextResponse } from "next/server";
-import type { NextRequest } from "next/server";
-
+import process from "node:process";
 import { getOAuthService } from "@calcom/features/oauth/di/OAuthService.container";
 import { OAUTH_ERROR_REASONS } from "@calcom/features/oauth/services/OAuthService";
 import { ErrorWithCode } from "@calcom/lib/errors";
 import { getHttpStatusCode } from "@calcom/lib/server/getServerErrorFromUnknown";
+import { defaultResponderForAppDir } from "app/api/defaultResponderForAppDir";
+import { parseUrlFormData } from "app/api/parseRequestData";
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
 
 async function handler(req: NextRequest) {
   const { client_id, client_secret, grant_type, refresh_token } = await parseUrlFormData(req);
@@ -33,6 +33,7 @@ async function handler(req: NextRequest) {
         token_type: "bearer",
         refresh_token: tokens.refreshToken,
         expires_in: tokens.expiresIn,
+        scope: tokens.scope,
       },
       {
         status: 200,

apps/web/app/api/auth/oauth/token/route.ts

@@ -1,17 +1,16 @@
-import { defaultResponderForAppDir } from "app/api/defaultResponderForAppDir";
-import { parseUrlFormData } from "app/api/parseRequestData";
-import { NextResponse } from "next/server";
-import type { NextRequest } from "next/server";
-
+import process from "node:process";
 import { getOAuthService } from "@calcom/features/oauth/di/OAuthService.container";
 import { OAUTH_ERROR_REASONS } from "@calcom/features/oauth/services/OAuthService";
 import { ErrorWithCode } from "@calcom/lib/errors";
 import { getHttpStatusCode } from "@calcom/lib/server/getServerErrorFromUnknown";
+import { defaultResponderForAppDir } from "app/api/defaultResponderForAppDir";
+import { parseUrlFormData } from "app/api/parseRequestData";
+import type { NextRequest } from "next/server";
+import { NextResponse } from "next/server";
 
 async function handler(req: NextRequest) {
-  const { code, client_id, client_secret, grant_type, redirect_uri, code_verifier } = await parseUrlFormData(
-    req
-  );
+  const { code, client_id, client_secret, grant_type, redirect_uri, code_verifier } =
+    await parseUrlFormData(req);
 
   if (!process.env.CALENDSO_ENCRYPTION_KEY) {
     return NextResponse.json({ message: OAUTH_ERROR_REASONS["encryption_key_missing"] }, { status: 500 });
@@ -41,6 +40,7 @@ async function handler(req: NextRequest) {
         token_type: "bearer",
         refresh_token: tokens.refreshToken,
         expires_in: tokens.expiresIn,
+        scope: tokens.scope,
       },
       {
         status: 200,