@mondaydotcomorg/monday-authorization 3.3.0-feat-add-graph-api-routing-support-34aa710 → 3.3.0-feat-add-graph-api-routing-support-8a1a68f

package/src/index.ts

@@ -0,0 +1,62 @@
+import { MondayFetchOptions } from '@mondaydotcomorg/monday-fetch';
+import { setPrometheus } from './prometheus-service';
+import { setIgniteClient, setRedisClient, setRequestFetchOptions } from './authorization-service';
+import { initializeMetrics } from './metrics-service';
+import * as TestKit from './testKit';
+
+export interface InitOptions {
+  prometheus?: any;
+  mondayFetchOptions?: MondayFetchOptions;
+  redisClient?: any;
+  grantedFeatureRedisExpirationInSeconds?: number;
+  metrics?: {
+    serviceName?: string;
+    host?: string;
+    port?: number;
+    disabled?: boolean;
+  };
+}
+
+export async function init(options: InitOptions = {}) {
+  if (options.prometheus) {
+    setPrometheus(options.prometheus);
+  }
+
+  const resolvedDisabled =
+    options.metrics?.disabled ?? ['test', 'development'].includes((process.env.NODE_ENV ?? '').toLowerCase());
+  initializeMetrics({
+    serviceName: options.metrics?.serviceName ?? process.env.APP_NAME ?? 'authorization-sdk',
+    host: options.metrics?.host,
+    port: options.metrics?.port,
+    disabled: resolvedDisabled,
+  });
+
+  if (options.mondayFetchOptions) {
+    setRequestFetchOptions(options.mondayFetchOptions);
+  }
+  if (options.redisClient) {
+    setRedisClient(options.redisClient, options.grantedFeatureRedisExpirationInSeconds);
+  }
+
+  // add an ignite client for gradual release features
+  await setIgniteClient();
+}
+
+export {
+  authorizationCheckMiddleware,
+  getAuthorizationMiddleware,
+  skipAuthorizationMiddleware,
+} from './authorization-middleware';
+export { AuthorizationService, AuthorizeResponse } from './authorization-service';
+export { AuthorizationAttributesService } from './authorization-attributes-service';
+export { RolesService } from './roles-service';
+export { AuthorizationObject, Resource, BaseRequest, ResourceGetter, ContextGetter } from './types/general';
+export {
+  Translation,
+  ScopedAction,
+  ScopedActionResponseObject,
+  ScopedActionPermit,
+} from './types/scoped-actions-contracts';
+export { CustomRole, BasicRole, RoleType, RoleCreateRequest, RoleUpdateRequest, RolesResponse } from './types/roles';
+
+export { TestKit };

package/src/metrics-service.ts

@@ -0,0 +1,67 @@
+import { Metric } from '@mondaydotcomorg/monday-observability-kit';
+import { logger } from './authorization-internal-service';
+
+type ApiType = 'platform' | 'graph';
+
+interface InitializeMetricsOptions {
+  serviceName: string;
+  host?: string;
+  port?: number;
+  disabled?: boolean;
+}
+
+let initialized = false;
+
+export function initializeMetrics(options: InitializeMetricsOptions): void {
+  if (initialized) {
+    return;
+  }
+
+  const { serviceName } = options;
+  if (!serviceName) {
+    logger.warn({ tag: 'metrics-service' }, 'Metrics initialization skipped: serviceName is missing');
+    return;
+  }
+
+  const resolvedHost = options.host ?? process.env.DOGSTATSD_HOST ?? 'localhost';
+  const envPort = process.env.DOGSTATSD_PORT ? Number(process.env.DOGSTATSD_PORT) : undefined;
+  const resolvedPort = options.port ?? (Number.isFinite(envPort ?? NaN) ? envPort : undefined) ?? 8125;
+  const resolvedDisabled =
+    options.disabled ?? ['test', 'development'].includes((process.env.NODE_ENV ?? '').toLowerCase());
+
+  try {
+    Metric.initialize({
+      serviceName,
+      host: resolvedHost,
+      port: resolvedPort,
+      disabled: resolvedDisabled,
+    });
+    initialized = true;
+  } catch (error) {
+    logger.warn({ tag: 'metrics-service', error }, 'Failed to initialize metrics');
+  }
+}
+
+export function recordAuthorizationTiming(apiType: ApiType, duration: number): void {
+  if (!initialized) {
+    return;
+  }
+
+  try {
+    Metric.distribution(`authorization.authorizationCheck.${apiType}.duration`, duration);
+  } catch (error) {
+    logger.warn({ tag: 'metrics-service', error }, 'Failed to record authorization timing');
+  }
+}
+
+export function recordAuthorizationError(apiType: ApiType, statusCode: number): void {
+  if (!initialized) {
+    return;
+  }
+
+  try {
+    Metric.increment(`authorization.authorizationCheck.${apiType}.error.${statusCode}`);
+  } catch (error) {
+    logger.warn({ tag: 'metrics-service', error }, 'Failed to record authorization error');
+  }
+}

package/src/prometheus-service.ts

@@ -0,0 +1,48 @@
+import { Action } from './types/general';
+
+let prometheus: any = null;
+let authorizationCheckResponseTimeMetric: any = null;
+
+export const METRICS = {
+  AUTHORIZATION_CHECK: 'authorization_check',
+  AUTHORIZATION_CHECKS_PER_REQUEST: 'authorization_checks_per_request',
+  AUTHORIZATION_CHECK_RESPONSE_TIME: 'authorization_check_response_time',
+};
+
+const authorizationCheckResponseTimeMetricConfig = {
+  name: METRICS.AUTHORIZATION_CHECK_RESPONSE_TIME,
+  labels: ['resourceType', 'action', 'isAuthorized', 'responseStatus'],
+  description: 'Authorization check response time summary',
+};
+
+export function setPrometheus(customPrometheus) {
+  prometheus = customPrometheus;
+  const { METRICS_TYPES } = prometheus;
+
+  authorizationCheckResponseTimeMetric = getMetricsManager().addMetric(
+    METRICS_TYPES.SUMMARY,
+    authorizationCheckResponseTimeMetricConfig.name,
+    authorizationCheckResponseTimeMetricConfig.labels,
+    authorizationCheckResponseTimeMetricConfig.description
+  );
+}
+
+export function getMetricsManager() {
+  return prometheus?.metricsManager;
+}
+
+export function sendAuthorizationCheckResponseTimeMetric(
+  resourceType: string,
+  action: Action,
+  isAuthorized: boolean,
+  responseStatus: number,
+  time: number
+) {
+  try {
+    if (authorizationCheckResponseTimeMetric) {
+      authorizationCheckResponseTimeMetric.labels(resourceType, action, isAuthorized, responseStatus).observe(time);
+    }
+  } catch (e) {
+    // ignore
+  }
+}

package/src/roles-service.ts

@@ -0,0 +1,125 @@
+import { Api, FetcherConfig, HttpClient } from '@mondaydotcomorg/trident-backend-api';
+import { HttpFetcherError, RecursivePartial } from '@mondaydotcomorg/monday-fetch-api';
+import { RoleCreateRequest, RolesResponse, RoleUpdateRequest } from 'types/roles';
+import { getAttributionsFromApi } from 'attributions-service';
+import { APP_NAME, DEFAULT_FETCH_OPTIONS, ERROR_MESSAGES } from './constants';
+
+const API_PATH = '/roles/account/{accountId}';
+
+export class RolesService {
+  private httpClient: HttpClient;
+  private fetchOptions: RecursivePartial<FetcherConfig>;
+  private attributionHeaders: { [key: string]: string };
+
+  /**
+   * Public constructor to create the AuthorizationAttributesService instance.
+   * @param httpClient The HTTP client to use for API requests, if not provided, the default HTTP client from Api will be used.
+   * @param fetchOptions The fetch options to use for API requests, if not provided, the default fetch options will be used.
+   */
+  constructor(httpClient?: HttpClient, fetchOptions?: RecursivePartial<FetcherConfig>) {
+    if (!httpClient) {
+      httpClient = Api.getPart('httpClient');
+      if (!httpClient) {
+        throw new Error(ERROR_MESSAGES.HTTP_CLIENT_NOT_INITIALIZED);
+      }
+    }
+
+    if (!fetchOptions) {
+      fetchOptions = DEFAULT_FETCH_OPTIONS;
+    } else {
+      fetchOptions = {
+        ...DEFAULT_FETCH_OPTIONS,
+        ...fetchOptions,
+      };
+    }
+    this.httpClient = httpClient;
+    this.fetchOptions = fetchOptions;
+    this.attributionHeaders = getAttributionsFromApi();
+  }
+
+  /**
+   * Get all roles for an account
+   * @param accountId - The account ID
+   * @param style - The style of the roles to return, either 'A' or 'B', default is 'A'. 'B' is not deprecated and only available for backward compatibility.
+   * @returns - The roles for the account, both basic and custom roles. Note that basic role ids are returned in A style and not B style.
+   */
+  async getRoles(accountId: number, resourceTypes: string[], style: 'A' | 'B' = 'A'): Promise<RolesResponse> {
+    return await this.sendRoleRequest('GET', accountId, {}, { resourceTypes, style });
+  }
+
+  /**
+   * Create a custom role for an account
+   * @param accountId - The account ID
+   * @param roles - The roles to create
+   * @returns - The created roles
+   * Note that basic role ids should be provided in A style and not in B style.
+   */
+  async createCustomRole(accountId: number, roles: RoleCreateRequest[]): Promise<RolesResponse> {
+    if (roles.length === 0) {
+      throw new Error('Roles array cannot be empty');
+    }
+
+    return await this.sendRoleRequest('PUT', accountId, {
+      customRoles: roles,
+    });
+  }
+
+  /**
+   * Delete a custom role for an account
+   * @param accountId - The account ID
+   * @param roleIds - The ids of the roles to delete
+   * @returns - The deleted roles. Note that basic role ids should be provided in A style and not in B style.
+   */
+  async deleteCustomRole(accountId: number, roleIds: number[]): Promise<RolesResponse> {
+    return await this.sendRoleRequest('DELETE', accountId, {
+      ids: roleIds,
+    });
+  }
+
+  /**
+   * Update a custom role for an account
+   * @param accountId - The account ID
+   * @param updateRequests - The requests to update the roles
+   * @returns - The updated roles. Note that basic role ids should be provided in A style and not in B style.
+   */
+  async updateCustomRole(accountId: number, updateRequests: RoleUpdateRequest[]): Promise<RolesResponse> {
+    return await this.sendRoleRequest('PATCH', accountId, {
+      customRoles: updateRequests,
+    });
+  }
+
+  private async sendRoleRequest(
+    method: 'PUT' | 'GET' | 'DELETE' | 'PATCH',
+    accountId: number,
+    body: any,
+    additionalQueryParams: { [key: string]: any } = {},
+    style: 'A' | 'B' = 'A'
+  ): Promise<RolesResponse> {
+    try {
+      return await this.httpClient.fetch<RolesResponse>(
+        {
+          url: {
+            appName: APP_NAME,
+            path: API_PATH.replace('{accountId}', accountId.toString()),
+          },
+          query: {
+            style: style,
+            ...additionalQueryParams,
+          },
+          method,
+          headers: {
+            'Content-Type': 'application/json',
+            ...this.attributionHeaders,
+          },
+          body: method === 'GET' ? undefined : body,
+        },
+        this.fetchOptions
+      );
+    } catch (err) {
+      if (err instanceof HttpFetcherError) {
+        throw new Error(ERROR_MESSAGES.REQUEST_FAILED('sendRoleRequest', err.status, err.message));
+      }
+      throw err;
+    }
+  }
+}

package/src/testKit/index.ts

@@ -0,0 +1,69 @@
+import { Action, BaseRequest, BaseResponse, ContextGetter, Resource, ResourceGetter } from '../types/general';
+import { defaultContextGetter } from '../authorization-middleware';
+import { AuthorizationInternalService } from '../authorization-internal-service';
+import type { NextFunction } from 'express';
+
+export type TestPermittedAction = {
+  accountId: number;
+  userId: number;
+  resources: Resource[];
+  action: Action;
+};
+
+let testPermittedActions: TestPermittedAction[] = [];
+export const addTestPermittedAction = (accountId: number, userId: number, resources: Resource[], action: Action) => {
+  testPermittedActions.push({ accountId, userId, resources, action });
+};
+
+export const clearTestPermittedActions = () => {
+  testPermittedActions = [];
+};
+
+const isActionAuthorized = (accountId: number, userId: number, resources: Resource[], action: Action) => {
+  // If no resources to check, deny access
+  if (resources.length === 0) {
+    return { isAuthorized: false };
+  }
+
+  return {
+    isAuthorized: resources.every(resource => {
+      return testPermittedActions.some(combination => {
+        return (
+          combination.accountId === accountId &&
+          combination.userId === userId &&
+          combination.action === action &&
+          combination.resources.some(combinationResource => {
+            return (
+              combinationResource.id === resource.id &&
+              combinationResource.type === resource.type &&
+              JSON.stringify(combinationResource.wrapperData) === JSON.stringify(resource.wrapperData)
+            );
+          })
+        );
+      });
+    }),
+  };
+};
+
+export const getTestAuthorizationMiddleware = (
+  action: Action,
+  resourceGetter: ResourceGetter,
+  contextGetter?: ContextGetter
+) => {
+  return async function authorizationMiddleware(
+    request: BaseRequest,
+    response: BaseResponse,
+    next: NextFunction
+  ): Promise<void> {
+    contextGetter ||= defaultContextGetter;
+    const { userId, accountId } = contextGetter(request);
+    const resources = resourceGetter(request);
+    const { isAuthorized } = isActionAuthorized(accountId, userId, resources, action);
+    if (!isAuthorized) {
+      response.status(403).json({ message: 'Access denied' });
+      return;
+    }
+    AuthorizationInternalService.markAuthorized(request);
+    next();
+  };
+};

package/src/types/authorization-attributes-contracts.ts

@@ -0,0 +1,33 @@
+import { Resource } from './general';
+
+export interface ResourceAttributeAssignment {
+  resourceType: Resource['type'];
+  resourceId: Resource['id'];
+  key: string;
+  value: string;
+}
+
+export interface ResourceAttributeResponse {
+  attributes: ResourceAttributeAssignment[];
+}
+
+export interface ResourceAttributeDelete {
+  resourceType: Resource['type'];
+  resourceId: Resource['id'];
+  key: string;
+}
+
+export enum ResourceAttributeOperationEnum {
+  UPSERT = 'upsert',
+  DELETE = 'delete',
+}
+
+interface UpsertResourceAttributeOperation extends ResourceAttributeAssignment {
+  operationType: ResourceAttributeOperationEnum.UPSERT;
+}
+
+interface DeleteResourceAttributeOperation extends ResourceAttributeDelete {
+  operationType: ResourceAttributeOperationEnum.DELETE;
+}
+
+export type ResourceAttributesOperation = UpsertResourceAttributeOperation | DeleteResourceAttributeOperation;

package/src/types/express.ts

@@ -0,0 +1,8 @@
+// eslint-disable-next-line @typescript-eslint/no-namespace, @typescript-eslint/no-unused-vars
+declare namespace Express {
+  export interface Request {
+    payload: { accountId: number; userId: number };
+    authorizationCheckPerformed: boolean;
+    authorizationSkipPerformed: boolean;
+  }
+}

package/src/types/general.ts

@@ -0,0 +1,32 @@
+import type { Request, Response } from 'express';
+
+export interface Resource {
+  id?: number;
+  type: string;
+  wrapperData?: object;
+}
+export type Action = string;
+export interface Context {
+  accountId: number;
+  userId: number;
+}
+export interface AuthorizationObject {
+  resource_id?: Resource['id'];
+  resource_type: Resource['type'];
+  wrapper_data?: Resource['wrapperData'];
+  action: Action;
+}
+export interface AuthorizationParams {
+  authorizationObjects: AuthorizationObject[];
+}
+
+type BasicObject = { [key: string]: unknown };
+
+export type BaseParameters = BasicObject;
+export type BaseResponseBody = BasicObject;
+export type BaseBodyParameters = BasicObject;
+export type BaseQueryParameters = BasicObject;
+export type BaseRequest = Request<BaseParameters, BaseResponseBody, BaseBodyParameters, BaseQueryParameters>;
+export type BaseResponse = Response<BaseResponseBody>;
+export type ResourceGetter = (request: BaseRequest) => Resource[];
+export type ContextGetter = (request: BaseRequest) => Context;

package/src/types/graph-api.types.ts

@@ -0,0 +1,25 @@
+// Graph API related types and interfaces
+
+export type ResourceType = string;
+export type ResourceId = number;
+export type ActionName = string;
+
+export type GraphIsAllowedDto = Record<ResourceType, Record<ResourceId, ActionName[]>>;
+
+export interface GraphPermissionReason {
+  key: string;
+  additionalOptions?: Record<string, string>;
+  technicalReason?: number;
+}
+
+export interface GraphPermissionResult {
+  can: boolean;
+  reason?: GraphPermissionReason;
+}
+
+// Permission to its result
+export type GraphPermissionResults = Record<ActionName, GraphPermissionResult>;
+
+// Resource type to map of resource ids to their permissions results
+// Note: Resource IDs are string keys in the API response (JSON object keys are always strings)
+export type GraphIsAllowedResponse = Record<ResourceType, Record<string, GraphPermissionResults>>;

package/src/types/roles.ts

@@ -0,0 +1,42 @@
+export enum RoleType {
+  CUSTOM = 'custom_role',
+  BASIC = 'basic_role',
+}
+
+export interface CustomRole {
+  id?: number;
+  name: string;
+  resourceType: string;
+  resourceId: number;
+  basicRoleId: number;
+  basicRoleType: RoleType;
+}
+
+export interface BasicRole {
+  id: number;
+  resourceType: string;
+  roleType: string;
+  name: string;
+}
+
+export interface RolesResponse {
+  customRoles: CustomRole[];
+  basicRoles?: BasicRole[];
+}
+
+export interface RoleCreateRequest {
+  name: string;
+  resourceType: string;
+  resourceId: number;
+  sourceRole: {
+    id: number;
+    type: RoleType;
+  };
+}
+
+export interface RoleUpdateRequest {
+  id: number;
+  updateAttributes: {
+    name: string;
+  };
+}

package/src/types/scoped-actions-contracts.ts

@@ -0,0 +1,57 @@
+export interface WorkspaceScope {
+  workspaceId: number;
+}
+
+export interface BoardScope {
+  boardId: number;
+}
+
+export interface PulseScope {
+  pulseId: number;
+}
+
+export interface AccountProductScope {
+  accountProductId: number;
+}
+
+export interface AccountScope {
+  accountId: number;
+}
+
+export type ScopeOptions = WorkspaceScope | BoardScope | PulseScope | AccountProductScope | AccountScope;
+
+export interface Translation {
+  key: string;
+  [option: string]: string;
+}
+
+export enum PermitTechnicalReason {
+  NO_REASON = 0,
+  NOT_ELIGIBLE = 1,
+  BY_ROLE_IN_SCOPE = 2,
+  /**
+   * NOT_APPLICABLE indicates that the permit was requested as part of the `permissions` parameter to the `getPermits`
+   * method, but would not otherwise be returned. This is done so that a cache in the monolith can serve
+   * two purposes: to mean both that a permit was requested and that it was received; at least: in the
+   * case of where a `permissions` parameter is passed to the `getPermits` method.
+   */
+  NOT_APPLICABLE = 3,
+  BY_POLICY = 4,
+  BY_OVERRIDE = 5,
+}
+
+export interface ScopedActionPermit {
+  can: boolean;
+  reason: Translation;
+  technicalReason: PermitTechnicalReason;
+}
+
+export interface ScopedAction {
+  action: string;
+  scope: ScopeOptions;
+}
+
+export interface ScopedActionResponseObject {
+  scopedAction: ScopedAction;
+  permit: ScopedActionPermit;
+}

package/src/utils/authorization.utils.ts

@@ -0,0 +1,47 @@
+import snakeCase from 'lodash/snakeCase.js';
+import camelCase from 'lodash/camelCase.js';
+import mapKeys from 'lodash/mapKeys.js';
+import { ScopeOptions } from '../types/scoped-actions-contracts';
+import { ResourceType, ResourceId } from '../types/graph-api.types';
+
+export type CamelCase<S extends string> = S extends `${infer F}_${infer R}` ? `${F}${Capitalize<CamelCase<R>>}` : S;
+export type CamelCaseKeys<T> = T extends object
+  ? { [K in keyof T as K extends string ? CamelCase<K> : K]: CamelCaseKeys<T[K]> }
+  : T;
+
+/**
+ * Converts a scope object to resource type and resource ID
+ */
+export function scopeToResource(scope: ScopeOptions): { resourceType: ResourceType; resourceId: ResourceId } {
+  if ('workspaceId' in scope) {
+    return { resourceType: 'workspace', resourceId: scope.workspaceId };
+  }
+  if ('boardId' in scope) {
+    return { resourceType: 'board', resourceId: scope.boardId };
+  }
+  if ('pulseId' in scope) {
+    return { resourceType: 'pulse', resourceId: scope.pulseId };
+  }
+  if ('accountProductId' in scope) {
+    return { resourceType: 'account_product', resourceId: scope.accountProductId };
+  }
+  if ('accountId' in scope) {
+    return { resourceType: 'account', resourceId: scope.accountId };
+  }
+
+  throw new Error('Unsupported scope provided');
+}
+
+/**
+ * Converts object keys from snake_case to camelCase
+ */
+export function toCamelCase<T extends object>(obj: T): CamelCaseKeys<T> {
+  return mapKeys(obj, (_, key) => camelCase(key)) as CamelCaseKeys<T>;
+}
+
+/**
+ * Converts object keys from camelCase to snake_case
+ */
+export function toSnakeCase<T extends object>(obj: T): Record<string, any> {
+  return mapKeys(obj, (_, key) => snakeCase(key));
+}