@mondaydotcomorg/monday-authorization 3.3.0-feature-bashanye-navigate-can-action-in-scope-to-graph-2d70b30 → 3.3.1-feature-bashanye-add-membership-create-delete-api-d00c165

package/src/index.ts

@@ -0,0 +1,63 @@
+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 { MembershipsService } from './memberships';
+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/memberships.ts

@@ -0,0 +1,111 @@
+import { Api, FetcherConfig, HttpClient } from '@mondaydotcomorg/trident-backend-api';
+import { RecursivePartial } from '@mondaydotcomorg/monday-fetch-api';
+import { getAttributionsFromApi } from './attributions-service';
+
+import { APP_NAME, DEFAULT_FETCH_OPTIONS, ERROR_MESSAGES } from './constants';
+import {
+  MembershipCreateResponse,
+  MembershipDeleteResponse,
+  MembershipForCreate,
+  MembershipForDelete,
+} from 'types/memberships';
+import { handleApiError } from 'utils/api-error-handler';
+
+export class MembershipsService {
+  private static API_PATHS = {
+    UPSERT_RESOURCE_ATTRIBUTES: '/memberships/{accountId}',
+    DELETE_RESOURCE_ATTRIBUTES: '/memberships/{accountId}',
+  } as const;
+  private httpClient: HttpClient;
+  private fetchOptions: RecursivePartial<FetcherConfig>;
+
+  /**
+   * 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;
+  }
+
+  /**
+   * Upsert memberships synchronously, performing http call to the authorization MS to assign the given memberships.
+   * @param accountId
+   * @param memberships - Array of memberships to upsert
+   * @returns MembershipCreateResponse - The affected (created and updated) memberships.
+   */
+  async upsertMemberships(accountId: number, memberships: MembershipForCreate[]): Promise<MembershipCreateResponse> {
+    const attributionHeaders = getAttributionsFromApi();
+    try {
+      return await this.httpClient.fetch<MembershipCreateResponse>(
+        {
+          url: {
+            appName: APP_NAME,
+            path: MembershipsService.API_PATHS.UPSERT_RESOURCE_ATTRIBUTES.replace('{accountId}', accountId.toString()),
+          },
+          method: 'PUT',
+          query: {
+            useAStyleRoleId: 'true',
+          },
+          headers: {
+            'Content-Type': 'application/json',
+            ...attributionHeaders,
+          },
+          body: JSON.stringify({ memberships }),
+        },
+        this.fetchOptions
+      );
+    } catch (err) {
+      return handleApiError(err, 'authorization', 'upsertMemberships');
+    }
+  }
+
+  /**
+   * Delete memberships synchronously, performing http call to the authorization MS to delete the given memberships.
+   * @param accountId
+   * @param resource - The resource (resourceType, resourceId) to delete the attributes for.
+   * @param attributeKeys - Array of attribute keys to delete for the resource.
+   * @returns ResourceAttributeResponse - The affected (deleted) resource attributes assignments in the `attributes` field.
+   */
+  async deleteMemberships(accountId: number, memberships: MembershipForDelete[]): Promise<MembershipDeleteResponse> {
+    const attributionHeaders = getAttributionsFromApi();
+    try {
+      return await this.httpClient.fetch<MembershipDeleteResponse>(
+        {
+          url: {
+            appName: APP_NAME,
+            path: MembershipsService.API_PATHS.DELETE_RESOURCE_ATTRIBUTES.replace('{accountId}', accountId.toString()),
+          },
+          method: 'DELETE',
+          query: {
+            useAStyleRoleId: 'true',
+          },
+          headers: {
+            'Content-Type': 'application/json',
+            ...attributionHeaders,
+          },
+          body: JSON.stringify({ memberships }),
+        },
+        this.fetchOptions
+      );
+    } catch (err) {
+      return handleApiError(err, 'authorization', 'deleteMemberships');
+    }
+  }
+}

package/src/metrics-service.ts

@@ -0,0 +1,71 @@
+import { Metric } from '@mondaydotcomorg/monday-observability-kit';
+import { logger } from './authorization-internal-service';
+
+type ApiType = 'platform' | 'graph' | 'authorization';
+
+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, placement: string): void {
+  if (!initialized) {
+    return;
+  }
+
+  try {
+    Metric.distribution(`authorization.authorizationCheck.${apiType}.${placement}.duration`, duration);
+  } catch {
+    // ignore metric emission failures
+  }
+}
+
+export function recordAuthorizationError(apiType: ApiType, statusCode: number, placement: string): void {
+  if (!initialized) {
+    return;
+  }
+
+  try {
+    Metric.increment(
+      `authorization.authorizationCheck.${apiType}.${placement}.error`,
+      { statusCode: String(statusCode) },
+      1
+    );
+  } catch {
+    // ignore metric emission failures
+  }
+}

package/src/prometheus-service.ts

@@ -0,0 +1,51 @@
+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;
+  if (!prometheus) {
+    return;
+  }
+  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/memberships.ts

@@ -0,0 +1,47 @@
+export interface MembershipCreateRequest {
+  memberships: MembershipForCreate[];
+}
+
+export interface MembershipDeleteRequest {
+  memberships: MembershipForDelete[];
+}
+
+export interface MembershipForCreate {
+  entityId: number; // Which entity has the role?
+  entityType: string; // What type of entity is this?
+  resourceId: number; // What resource is this membership for?
+  resourceType: string; // What type of resource is this membership for?
+  roleId: number; // What role is this membership for?
+  roleType?: string; // What type of role is this membership for? (basic/custom)
+  addedById: number; // Who added this membership? for logging purposes
+}
+
+export interface MembershipForDelete {
+  entityId?: number; // Which entity has the role?
+  entityType: string; // What type of entity is this?
+  resourceId?: number; // What resource is this membership for?
+  resourceType: string; // What type of resource is this membership for?
+}
+
+export interface MembershipCreateResponse {
+  memberships: Membership[];
+}
+
+export interface MembershipDeleteResponse {
+  memberships: Membership[];
+}
+
+export interface Membership {
+  id: number;
+  entityId: number;
+  entityType: string;
+  resourceId: number;
+  resourceType: string;
+  roleId: number;
+  roleType: string;
+  addedById: null | number | undefined;
+  hops: number;
+  isNewRecord: boolean;
+  previousValues: Partial<Membership>;
+  walVersion: number | null | undefined;
+}

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;
+  };
+}