@axinom/mosaic-id-guard 0.18.0-rc.9 → 0.18.0

package/src/graphql/ax-guard-plugin.ts

@@ -0,0 +1,29 @@
+import { makePluginByCombiningPlugins } from 'graphile-utils';
+import { QueryMutationGuardPlugin } from './query-mutation-guard-plugin';
+import { SubscriptionGuardPlugin } from './subscription-guard-plugin';
+
+/**
+ * AxGuard plugin is created by combining two plugins - `QueryMutationGuardPlugin`
+ * and `SubscriptionGuardPlugin`.
+ *
+ * This plugin handles authorization for GraphQL resources exposed by the APIs.
+ * For Queries and Mutations an error is thrown if the authorization fails.
+ *
+ * For subscriptions, if the JWT token expires while subscription events are emitted,
+ * the websocket connection is closed with `4403` code, allowing the client to automatically
+ * re-establish the connection.
+ * For authorization errors, the websocket is closed with `4401` code.
+ *
+ * **!!!!!!!!!! IMPORTANT !!!!!!!!!!**
+ *
+ * When using this plugin with subscriptions, it's mandatory to send the reference to
+ * the websocket through Extended GraphQL Context with the key name `websocket`.
+ * `getWebsocketFromRequest` from `@axinom/mosaic-service-common` can be used to extract the
+ * websocket from request.
+ *
+ * @returns
+ */
+export const AxGuardPlugin = makePluginByCombiningPlugins(
+  QueryMutationGuardPlugin,
+  SubscriptionGuardPlugin,
+);

package/src/graphql/enforce-strict-permissions.plugin.ts

@@ -4,7 +4,7 @@ import {
   PermissionDefinition,
 } from '@axinom/mosaic-id-utils';
 import { Logger } from '@axinom/mosaic-service-common';
-import { Plugin } from 'graphile-build';
+import { Plugin } from 'postgraphile';
 import { removeProperties } from '../common/helpers';
 
 interface PluginContext {

package/src/graphql/index.ts

@@ -1,3 +1,4 @@
+export * from './ax-guard-plugin';
 export * from './enforce-strict-permissions.plugin';
 export * from './guard-context';
 export {
@@ -8,5 +9,5 @@ export {
   throwEndUserAuthError,
   throwManagementAuthError,
 } from './guard-middleware';
-export * from './guard-plugin';
-export * from './subscription-authorization-hook-factory';
+export * from './query-mutation-guard-plugin';
+export * from './subscription-guard-plugin';

package/src/graphql/{guard-plugin.spec.ts → query-mutation-guard-plugin.spec.ts}

@@ -11,7 +11,7 @@ import { gql, makeExtendSchemaPlugin } from 'graphile-utils';
 import { graphql, GraphQLSchema, parse, subscribe } from 'graphql';
 import { PubSub } from 'graphql-subscriptions';
 import { IdGuardErrors, SubjectType } from '../common';
-import { AxGuardPlugin } from './guard-plugin';
+import { QueryMutationGuardPlugin } from './query-mutation-guard-plugin';
 
 const pubSub = new PubSub();
 
@@ -63,7 +63,7 @@ const makeSchemaWithSpyAndPlugins = async (
           },
         },
       })),
-      AxGuardPlugin,
+      QueryMutationGuardPlugin,
     ],
     {
       optionKey: 'optionValue',
@@ -77,7 +77,7 @@ const makeEchoSpy = () =>
     return args.message;
   });
 
-describe('AxGuardPlugin', () => {
+describe('QueryMutationGuardPlugin', () => {
   it('When neither a PermissionDefinition object nor EndUserAuthorizationConfig object is present in Postgraphile build options, an error is raised', async () => {
     // Arrange
     const spy = makeEchoSpy();

package/src/graphql/{guard-plugin.ts → query-mutation-guard-plugin.ts}

@@ -1,6 +1,5 @@
 import { makeWrapResolversPlugin } from 'graphile-utils';
 import {
-  assertGenericAuthenticatedSubject,
   EndUserAuthenticationContext,
   ManagementAuthenticationContext,
 } from '../common';
@@ -8,8 +7,7 @@ import {
   AxGuardOptions,
   validatePostgraphileBuildOptions,
 } from '../common/guard-utils';
-import { handleEndUserAuthorization } from '../common/handle-end-user-authorization';
-import { handleManagementUserAuthorization } from '../common/handle-management-user-authorization';
+import { handleAuthorization } from '../common/helpers/guard-authorization';
 
 /**
  * Postgraphile plugin that wraps resolver execution into an authentication check, making sure that that JwtToken subject is authorized to access a GraphQL resource.
@@ -20,7 +18,7 @@ import { handleManagementUserAuthorization } from '../common/handle-management-u
  * @param additionalGraphQLContextFromRequest should be of type `Record<string, any> & { subject: AuthenticatedSubject, authErrorInfo: AxGuardErrorInfo }`
  * @param graphileBuildOptions should be of type `Partial<Options> & { permissionDefinition: PermissionDefinition, serviceId: string, ensureOnlyAuthentication: boolean }`
  */
-export const AxGuardPlugin = makeWrapResolversPlugin(
+export const QueryMutationGuardPlugin = makeWrapResolversPlugin(
   (
     { scope },
     _build,
@@ -66,37 +64,15 @@ export const AxGuardPlugin = makeWrapResolversPlugin(
       // Validate if the Postgraphile build options related to authorization are correctly set.
       validatePostgraphileBuildOptions(options);
 
-      // If the permissionDefinition is not undefined, it is assumed that the subject is a AuthenticatedManagementSubject
-      if (options.authorizationOptions.permissionDefinition !== undefined) {
-        if (subject !== undefined && subject !== null) {
-          assertGenericAuthenticatedSubject(subject);
-        }
-
-        handleManagementUserAuthorization(
-          options.authorizationOptions,
-          options.ensureOnlyAuthentication,
-          subject,
-          authErrorInfo,
-        );
-        return resolver(source, args, context, resolveInfo);
-      } else {
-        /**
-         * This block handles end-user operations.
-         * If the if condition (options.authorizationOptions.permissionDefinition !== undefined) falls through to this else branch,
-         * it is assumed that the request is a end-user call.
-         */
-
-        if (subject !== undefined && subject !== null) {
-          assertGenericAuthenticatedSubject(subject);
-        }
-
-        handleEndUserAuthorization(
-          options.authorizationOptions,
-          options.ensureOnlyAuthentication,
-          subject,
-          authErrorInfo,
-        );
-        return resolver(source, args, context, resolveInfo);
-      }
+      return handleAuthorization(
+        subject,
+        authErrorInfo,
+        options,
+        resolver,
+        source,
+        args,
+        context,
+        resolveInfo,
+      );
     },
 );

package/src/graphql/subscription-guard-plugin.spec.ts

@@ -0,0 +1,257 @@
+import {
+  buildSchema,
+  QueryPlugin,
+  StandardTypesPlugin,
+  SubscriptionPlugin,
+} from 'graphile-build';
+import { gql, makeExtendSchemaPlugin } from 'graphile-utils';
+import { GraphQLSchema, parse, subscribe } from 'graphql';
+import { PubSub } from 'graphql-subscriptions';
+import { CloseCode } from 'graphql-ws';
+import { IdGuardErrors, SubjectType } from '../common';
+import { SubscriptionGuardPlugin } from './subscription-guard-plugin';
+
+const pubSub = new PubSub();
+
+const makeSchemaWithSpyAndPlugins = async (
+  spy: any,
+  options = {},
+): Promise<GraphQLSchema> =>
+  buildSchema(
+    [
+      StandardTypesPlugin,
+      QueryPlugin,
+      SubscriptionPlugin,
+      makeExtendSchemaPlugin(() => ({
+        typeDefs: gql`
+          extend type Query {
+            echo(message: String!): String
+          }
+          extend type Subscription {
+            echoSubscription: String
+          }
+        `,
+        resolvers: {
+          Query: {
+            echo: spy,
+          },
+          Subscription: {
+            echoSubscription: {
+              subscribe: () => pubSub.asyncIterator('echoSubscription'),
+              resolve: () => {
+                return 'Hello Subscription';
+              },
+            },
+          },
+        },
+      })),
+      SubscriptionGuardPlugin,
+    ],
+    {
+      optionKey: 'optionValue',
+      serviceId: 'test-service',
+      ...options,
+    },
+  );
+
+const makeEchoSpy = () =>
+  jest.fn((parent, args) => {
+    return args.message;
+  });
+
+describe('SubscriptionGuardPlugin', () => {
+  it('When a websocket reference is not present in the GraphQL Context, a WebSocketNotFound error is thrown', async () => {
+    // Arrange
+    const spy = makeEchoSpy();
+
+    const schema = await makeSchemaWithSpyAndPlugins(spy);
+
+    const document = parse('subscription { echoSubscription }');
+
+    // Act
+    // Create subscription
+    const subscription: any = await subscribe({
+      schema,
+      document,
+      rootValue: null,
+      contextValue: {},
+    });
+
+    // Assert
+    expect(subscription.errors).toBeDefined();
+    expect(subscription.errors[0].message).toBe(
+      IdGuardErrors.WebSocketNotFound.message,
+    );
+  });
+
+  it('When a the token is expired, the websocket is closed with code Forbidden (4403)', async () => {
+    // Arrange
+    const spy = makeEchoSpy();
+
+    const schema = await makeSchemaWithSpyAndPlugins(spy, {
+      serviceId: 'test-service',
+      permissionDefinition: {
+        gqlOptions: {
+          anonymousGqlOperations: [],
+          ignoredGqlOperations: [],
+        },
+        permissions: [
+          {
+            key: 'EDITOR',
+            title: 'EDITOR',
+            gqlOperations: ['otherEndpoint', 'echoSubscription'],
+          },
+        ],
+      },
+    });
+
+    const document = parse('subscription { echoSubscription }');
+
+    const websocketCloseSpy = jest.fn();
+
+    // Act
+    // Create subscription
+    const subscription: any = await subscribe({
+      schema,
+      document,
+      rootValue: null,
+      contextValue: {
+        websocket: {
+          close: websocketCloseSpy,
+        },
+        subject: {
+          sub: 'test-user',
+          permissions: { 'test-service': ['EDITOR'] },
+          exp: new Date().getTime() / 1000 - 20, // set expiry time of the token to currentTime - 20 seconds
+          subjectType: SubjectType.UserAccount,
+        },
+      },
+    });
+
+    // Assert
+    expect(subscription.errors).toBeDefined();
+    expect(subscription.errors[0].message).toBe(
+      IdGuardErrors.AccessTokenExpired.message,
+    );
+    expect(websocketCloseSpy).toHaveBeenCalledWith(
+      CloseCode.Forbidden,
+      IdGuardErrors.AccessTokenExpired.code,
+    );
+  });
+
+  it('When a the user is not authorized to invoke the subscription, the websocket is closed with code Unauthorized (4401)', async () => {
+    // Arrange
+    const spy = makeEchoSpy();
+
+    const schema = await makeSchemaWithSpyAndPlugins(spy, {
+      serviceId: 'test-service',
+      permissionDefinition: {
+        gqlOptions: {
+          anonymousGqlOperations: [],
+          ignoredGqlOperations: [],
+        },
+        permissions: [
+          {
+            key: 'EDITOR',
+            title: 'EDITOR',
+            gqlOperations: ['otherEndpoint', 'echoSubscription'],
+          },
+        ],
+      },
+    });
+
+    const document = parse('subscription { echoSubscription }');
+
+    const websocketCloseSpy = jest.fn();
+
+    // Act
+    // Create subscription
+    const subscription: any = await subscribe({
+      schema,
+      document,
+      rootValue: null,
+      contextValue: {
+        websocket: {
+          close: websocketCloseSpy,
+        },
+        subject: {
+          sub: 'test-user',
+          permissions: { 'test-service': ['READER'] },
+          exp: new Date().getTime() / 1000 + 20, // set expiry time of the token to currentTime + 20 seconds
+          subjectType: SubjectType.UserAccount,
+        },
+      },
+    });
+
+    // Assert
+    expect(subscription.errors).toBeDefined();
+    expect(subscription.errors[0].message).toBe(
+      IdGuardErrors.UserNotAuthorized.message,
+    );
+    expect(websocketCloseSpy).toHaveBeenCalledWith(
+      CloseCode.Unauthorized,
+      IdGuardErrors.UserNotAuthorized.message,
+    );
+  });
+
+  it('When the user is authorized to invoke the subscription with non-expired token, the subscription event payload is returned', async () => {
+    // Arrange
+    const spy = makeEchoSpy();
+
+    const schema = await makeSchemaWithSpyAndPlugins(spy, {
+      serviceId: 'test-service',
+      permissionDefinition: {
+        gqlOptions: {
+          anonymousGqlOperations: [],
+          ignoredGqlOperations: [],
+        },
+        permissions: [
+          {
+            key: 'EDITOR',
+            title: 'EDITOR',
+            gqlOperations: ['otherEndpoint', 'echoSubscription'],
+          },
+        ],
+      },
+    });
+
+    const document = parse('subscription { echoSubscription }');
+
+    const websocketCloseSpy = jest.fn();
+
+    // Act
+    // Create subscription
+    const subscription: any = await subscribe({
+      schema,
+      document,
+      rootValue: null,
+      contextValue: {
+        websocket: {
+          close: websocketCloseSpy,
+        },
+        subject: {
+          sub: 'test-user',
+          permissions: { 'test-service': ['EDITOR'] },
+          exp: new Date().getTime() / 1000 + 20, // set expiry time of the token to currentTime + 20 seconds
+          subjectType: SubjectType.UserAccount,
+        },
+      },
+    });
+
+    const resolveSubscription = subscription.next();
+
+    // Publish trigger to invoke subscription resolver
+    pubSub.publish('echoSubscription', 'message');
+
+    // Await for the subscription resolver to respond
+    const result = await resolveSubscription;
+
+    // Assert
+    expect(subscription.errors).toBeUndefined();
+    expect(websocketCloseSpy).not.toHaveBeenCalled();
+    expect(result.value.data.echoSubscription).toBe('Hello Subscription');
+
+    // Close subscription
+    await subscription.return();
+  });
+});

package/src/graphql/subscription-guard-plugin.ts

@@ -0,0 +1,112 @@
+import { MosaicError } from '@axinom/mosaic-service-common';
+import { CloseCode } from 'graphql-ws';
+import { Plugin } from 'postgraphile';
+import {
+  assertIdGuardError,
+  EndUserAuthenticationContext,
+  IdGuardErrors,
+  ManagementAuthenticationContext,
+} from '../common';
+import {
+  AxGuardOptions,
+  validatePostgraphileBuildOptions,
+} from '../common/guard-utils';
+import { handleAuthorization } from '../common/helpers/guard-authorization';
+
+/**
+ * This plugin wraps around the `subscribe` method for subscriptions
+ * and performs authorization, making sure that that JwtToken subject is authorized to access a GraphQL resource.
+ *
+ * The websocket is closed with error code 4403 if the access token has expired, allowing the client
+ * to re-establish the connection.
+ * If any other error is thrown, the websocket is closed with error code 4401.
+ *
+ * **!!!!!!!!!! IMPORTANT !!!!!!!!!!**
+ *
+ * When using this plugin, it's mandatory to send the reference to the websocket through
+ * Extended GraphQL Context with the key name `websocket`.
+ * `getWebsocketFromRequest` from `@axinom/mosaic-service-common` can be used to extract the
+ * websocket from request.
+ *
+ * @param builder
+ */
+export const SubscriptionGuardPlugin: Plugin = (builder) => {
+  builder.hook(
+    'GraphQLObjectType:fields:field',
+    (field, build, _context) => {
+      if (field.subscribe) {
+        const oldSubscribe = field.subscribe;
+        field.subscribe = async function (
+          parent: unknown,
+          args,
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          context: any,
+          info,
+        ) {
+          if (!context.websocket) {
+            throw new MosaicError(IdGuardErrors.WebSocketNotFound);
+          }
+
+          const options: AxGuardOptions = {
+            authorizationOptions: {
+              endUserAuthorizationConfig:
+                build.options.endUserAuthorizationConfig,
+              operation: info.fieldName,
+              permissionDefinition: build.options.permissionDefinition,
+              serviceId: build.options.serviceId,
+            },
+            ensureOnlyAuthentication:
+              build.options.ensureOnlyAuthentication ?? false,
+          };
+
+          const { authErrorInfo, subject } = context as
+            | ManagementAuthenticationContext
+            | EndUserAuthenticationContext; // The context could be either a Management or an End-User context.
+
+          try {
+            // Validate if the Postgraphile build options related to authorization are correctly set.
+            validatePostgraphileBuildOptions(options);
+
+            return handleAuthorization(
+              subject,
+              authErrorInfo,
+              options,
+              oldSubscribe,
+              parent,
+              args,
+              context,
+              info,
+            );
+          } catch (error) {
+            assertIdGuardError(error);
+            /**
+             * If the token has expired, we close the connection with CloseCode.Forbidden, and allow the client to automatically re-establish
+             * the connection with a new token.
+             */
+            if (error.code === IdGuardErrors.AccessTokenExpired.code) {
+              /**
+               * `CloseCode.Forbidden` is used so that the client will automatically start retry process with a newer token.
+               * Any other CloseCode will result in a client exception and the client will not automatically retry.
+               */
+              context.websocket.close(
+                CloseCode.Forbidden,
+                IdGuardErrors.AccessTokenExpired.code,
+              );
+            } else {
+              // Close the websocket connection.
+              context.websocket.close(CloseCode.Unauthorized, error.message);
+            }
+            throw error;
+          }
+        };
+      }
+      return field;
+    },
+    [],
+    [],
+    // Add the `subscribe` method to the graphql fields, wrapping around the GQL resolver.
+    // It looks for the `@pgSubscription` directive, and adds the `subscribe` method.
+    // https://github.com/graphile/graphile-engine/blob/1bc8cfefdab7a61fd7ad287bcdff66298352e308/packages/pg-pubsub/src/PgSubscriptionResolverPlugin.ts
+    ['PgSubscriptionResolver'],
+  );
+};

package/dist/graphql/guard-plugin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"guard-plugin.d.ts","sourceRoot":"","sources":["../../src/graphql/guard-plugin.ts"],"names":[],"mappings":"AAaA;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,iCA+EzB,CAAC"}

package/dist/graphql/guard-plugin.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"guard-plugin.js","sourceRoot":"","sources":["../../src/graphql/guard-plugin.ts"],"names":[],"mappings":";;;AAAA,mDAAyD;AACzD,sCAImB;AACnB,uDAG+B;AAC/B,2FAAqF;AACrF,yGAAmG;AAEnG;;;;;;;;GAQG;AACU,QAAA,aAAa,GAAG,IAAA,wCAAuB,EAClD,CACE,EAAE,KAAK,EAAE,EACT,MAAM,EACN,OAAO,EACP,EACE,wBAAwB,EACxB,SAAS,EACT,oBAAoB,EACpB,0BAA0B,GAC3B,EACD,EAAE;IACF,MAAM,uBAAuB,GAC3B,KAAK,CAAC,SAAS,KAAK,OAAO;QAC3B,CAAC,KAAK,CAAC,WAAW;YAChB,KAAK,CAAC,cAAc;YACpB,KAAK,CAAC,wBAAwB;YAC9B,KAAK,CAAC,yBAAyB;YAC/B,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAE9B,IAAI,uBAAuB,EAAE;QAC3B,OAAO;YACL,wBAAwB,EAAE,wBAAwB,aAAxB,wBAAwB,cAAxB,wBAAwB,GAAI,KAAK;YAC3D,oBAAoB,EAAE;gBACpB,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,SAAS;gBACT,oBAAoB;gBACpB,0BAA0B;aAC3B;SACF,CAAC;KACH;IAED,OAAO,IAAI,CAAC;AACd,CAAC,EACD,CAAC,OAAuB,EAAE,EAAE,CAC1B,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,EAAE;IACrD,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,OAEH,CAAC,CAAC,mEAAmE;IAErG,sIAAsI;IACtI,OAAO,CAAC,oBAAoB,CAAC,SAAS,GAAG,WAAW,CAAC,SAAS,CAAC;IAE/D,yFAAyF;IACzF,IAAA,8CAAgC,EAAC,OAAO,CAAC,CAAC;IAE1C,mHAAmH;IACnH,IAAI,OAAO,CAAC,oBAAoB,CAAC,oBAAoB,KAAK,SAAS,EAAE;QACnE,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE;YAC7C,IAAA,0CAAiC,EAAC,OAAO,CAAC,CAAC;SAC5C;QAED,IAAA,wEAAiC,EAC/B,OAAO,CAAC,oBAAoB,EAC5B,OAAO,CAAC,wBAAwB,EAChC,OAAO,EACP,aAAa,CACd,CAAC;QACF,OAAO,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;KACrD;SAAM;QACL;;;;WAIG;QAEH,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,IAAI,EAAE;YAC7C,IAAA,0CAAiC,EAAC,OAAO,CAAC,CAAC;SAC5C;QAED,IAAA,0DAA0B,EACxB,OAAO,CAAC,oBAAoB,EAC5B,OAAO,CAAC,wBAAwB,EAChC,OAAO,EACP,aAAa,CACd,CAAC;QACF,OAAO,QAAQ,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC;KACrD;AACH,CAAC,CACJ,CAAC"}

package/dist/graphql/subscription-authorization-hook-factory.d.ts

@@ -1,13 +0,0 @@
-import { Request, Response } from 'express';
-import { PostGraphileOptions, PostGraphilePlugin } from 'postgraphile';
-/**
- * This is a hook plugin generator function that will use the PermissionDefinition object in PostGraphileOptions
- * to authorize the Subscription operation done over a web socket.
- * It checks if the authenticated user which initiates the subscription has required permissions.
- * The actual plugin is built using this function when the build() function is called in PostgraphileOptionsBuilder.
- * This function reference can be passed into addHookPluginGenerator() to activate authorization of subscriptions.
- * @param PostGraphileOptions object containing permissions.
- * @returns PostGraphilePlugin
- */
-export declare const subscriptionAuthorizationHookFactory: (buildOptions: PostGraphileOptions<Request, Response> | undefined) => PostGraphilePlugin;
-//# sourceMappingURL=subscription-authorization-hook-factory.d.ts.map

package/dist/graphql/subscription-authorization-hook-factory.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"subscription-authorization-hook-factory.d.ts","sourceRoot":"","sources":["../../src/graphql/subscription-authorization-hook-factory.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAU5C,OAAO,EAEL,mBAAmB,EACnB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAgBtB;;;;;;;;GAQG;AACH,eAAO,MAAM,oCAAoC,iBACjC,oBAAoB,OAAO,EAAE,QAAQ,CAAC,GAAG,SAAS,KAC/D,kBA4MF,CAAC"}