@kravc/dos 1.12.5 → 2.0.0-alpha.0

package/src/Operation/security/LambdaAuthorization.ts

@@ -0,0 +1,103 @@
+import { get } from 'lodash';
+import Context from '../../Context';
+import AccessDeniedError from '../errors/AccessDeniedError';
+import type { Requirement, VerificationResult } from '../../Service/authorize';
+
+const NAME = 'System';
+const DESCRIPTION = 'This security definition and a header for system' +
+  ' operations should be ignored. The verification method of system' +
+  ' operations relies on a gateway that adds headers for all' +
+  ' external requests. Request without headers considered to be' +
+  ' internal.';
+
+const MESSAGE_ACCESS_DENIED = 'Access denied, operation is available only for internal requests';
+
+const DEFAULT_HEADER_NAME = 'authorization';
+
+type AccessVerificationMethod = (context: Context) => Promise<[ true ] | [ false, string ]>;
+
+type RequirementOptions = {
+  name?: string;
+  description?: string;
+  requirementName?: string;
+  accessVerificationMethod?: AccessVerificationMethod;
+}
+
+/** Ensures no headers are set by the gateway. */
+const verifyAccess = async (context: Context): Promise<[ true ] | [ false, string ]> => {
+  const { headers } = context;
+
+  const isExternalRequest = Object.keys(headers).length > 0;
+
+  if (isExternalRequest) {
+    return [ false, MESSAGE_ACCESS_DENIED ];
+  }
+
+  return [ true ];
+};
+
+/** Lambda Authorization */
+class LambdaAuthorization {
+  private _verifyAccess: AccessVerificationMethod;
+
+  /** Creates an instance of System authorization security. */
+  constructor({
+    accessVerificationMethod = verifyAccess,
+  }: {
+    accessVerificationMethod?: AccessVerificationMethod;
+  }) {
+    this._verifyAccess = accessVerificationMethod;
+  }
+
+  /** Creates an instance of system authorization security. */
+  static createRequirement(options: RequirementOptions = {}): Record<string, Requirement> {
+    const name = get(options, 'name', DEFAULT_HEADER_NAME);
+    const description = get(options, 'description', DESCRIPTION);
+    const requirementName = get(options, 'requirementName', NAME);
+
+    return {
+      [requirementName]: {
+        definition: {
+          in: 'header',
+          type: 'apiKey',
+          name,
+          description,
+        },
+        errors: LambdaAuthorization.errors,
+        /** Verifies context via JWT authorization requirement. */
+        verify: (context: Context) => {
+          const security = new LambdaAuthorization({ ...options });
+          return security.verify(context);
+        }
+      }
+    };
+  }
+
+  /** Returns security related errors. */
+  static get errors() {
+    return {
+      AccessDeniedError: {
+        statusCode: 403,
+        description: MESSAGE_ACCESS_DENIED
+      }
+    };
+  }
+
+  /** Verifies System authorization. */
+  async verify(context: Context): Promise<VerificationResult> {
+    const [ isAccessOk, accessErrorMessage ] = await this._verifyAccess(context);
+
+    if (!isAccessOk) {
+      const error = new AccessDeniedError(accessErrorMessage);
+      return { isAuthorized: false, error };
+    }
+
+    const claims = {
+      isSystem: true,
+    };
+
+    return { isAuthorized: true, claims };
+  }
+}
+
+export default LambdaAuthorization;

package/src/Operation/security/__tests__/JwtAuthorization.test.ts

@@ -0,0 +1,230 @@
+import { LambdaRequest } from '../../../Context';
+import { createContext } from '../../../Context/__tests__/__helpers';
+import { stringifyCookie } from 'cookie';
+import { service, handler } from '../../../../example';
+import { JwtAuthorization, createAccessToken, TEST_PUBLIC_KEY as publicKey } from '../../../';
+
+describe('JwtAuthorization', () => {
+  const CreateProfile = service.get('CreateProfile');
+
+  describe('JwtAuthorization.createRequirement(options)', () => {
+    it('extends operation with Authorization security requirements', () => {
+      expect(CreateProfile.security[0].Authorization).toBeDefined();
+    });
+
+    it('supports default access verification method without permissions map', async () => {
+      const Authorization = createAccessToken({}, { permissions: [] });
+
+      const request = {
+        headers: { authorization: Authorization },
+        operationId: 'CreateProfile'
+      } as LambdaRequest;
+
+      const context = createContext({ request });
+
+      const requirement = JwtAuthorization.createRequirement({ publicKey });
+      const verify = requirement.Authorization.verify;
+
+      const result = await verify(context);
+
+      expect(result.isAuthorized).toBe(true);
+    });
+
+    it('supports default access verification method with permissions map', async () => {
+      const Authorization = createAccessToken({}, { permissions: [ 'profiles-read' ] });
+
+      const request = {
+        headers: { authorization: Authorization },
+        operationId: 'CreateProfile'
+      } as LambdaRequest;
+
+      const context = createContext({ request });
+
+      const requirement = JwtAuthorization.createRequirement({
+        publicKey,
+        permissions: { 'profiles-write': [ 'CreateProfile' ] }
+      });
+
+      const verify = requirement.Authorization.verify;
+
+      const result = await verify(context);
+
+      expect(result.isAuthorized).toBe(false);
+    });
+  });
+
+  describe('JwtAuthorization.errors', () => {
+    it('includes authorization related errors', () => {
+      const errorCodes = Object.keys(CreateProfile.errors);
+      expect(errorCodes).toContain('UnauthorizedError');
+      expect(errorCodes).toContain('AccessDeniedError');
+    });
+  });
+
+  describe('.verify(context)', () => {
+    it('returns UnauthorizedError if no authorization header provided', async () => {
+      const request = {
+        operationId: 'CreateProfile',
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(401);
+
+      const body = JSON.parse(json!);
+
+      expect(body).toEqual({
+        error: {
+          code: 'UnauthorizedError',
+          message: 'Header "authorization" is missing',
+          statusCode: 401,
+        }
+      });
+    });
+
+    it('returns UnauthorizedError if invalid authorization header provided', async () => {
+      const request = {
+        operationId: 'CreateProfile',
+        headers: {
+          Authorization: 'INVALID_AUTHORIZATION_TOKEN',
+        }
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(401);
+
+      const body = JSON.parse(json!);
+
+      expect(body).toEqual({
+        error: {
+          code: 'UnauthorizedError',
+          message: 'Invalid "authorization" token',
+          statusCode: 401,
+        }
+      });
+    });
+
+    it('returns UnauthorizedError if token is not verified as expired', async () => {
+      const exp = Math.floor((new Date('2026-01-01T00:00:00Z').getTime()) / 1000);
+      const Authorization = createAccessToken({}, { exp });
+
+      const request = {
+        operationId: 'CreateProfile',
+        headers: {
+          Authorization,
+        }
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(401);
+
+      const body = JSON.parse(json!);
+
+      expect(body).toEqual({
+        error: {
+          code: 'UnauthorizedError',
+          message: '"authorization" token verification failed: jwt expired',
+          statusCode: 401,
+        }
+      });
+    });
+
+    it('returns UnauthorizedError if invalid token issuer', async () => {
+      const issuer = 'http://example.com';
+      const Authorization = createAccessToken({ issuer }, {});
+
+      const request = {
+        operationId: 'CreateProfile',
+        headers: {
+          Authorization,
+        }
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(401);
+
+      const body = JSON.parse(json!);
+
+      expect(body).toEqual({
+        error: {
+          code: 'UnauthorizedError',
+          message: 'Invalid issuer of "authorization" token',
+          statusCode: 401,
+        }
+      });
+    });
+
+    it('returns AccessDeniedError if access verification failed', async () => {
+      const Authorization = createAccessToken({}, { permissions: [] });
+
+      const request = {
+        operationId: 'CreateProfile',
+        headers: {
+          Authorization,
+        }
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(403);
+
+      const body = JSON.parse(json!);
+
+      expect(body).toEqual({
+        error: {
+          code: 'AccessDeniedError',
+          message: 'Access denied',
+          statusCode: 403,
+        }
+      });
+    });
+
+    it('returns success for a valid authorization header', async () => {
+      const Authorization = createAccessToken({}, { permissions: [ 'profiles-write' ] });
+
+      const request = {
+        operationId: 'CreateProfile',
+        headers: {
+          Authorization,
+        },
+        body: {
+          name: 'John Doe',
+        },
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(201);
+
+      const body = JSON.parse(json!);
+
+      expect(body.data.name).toEqual('John Doe');
+    });
+
+    it('returns success for a valid authorization cookie', async () => {
+      const Authorization = createAccessToken({}, { permissions: [ 'profiles-write' ] });
+      const cookie = stringifyCookie({ Authorization });
+
+      const request = {
+        operationId: 'CreateProfile',
+        headers: {
+          cookie,
+        },
+        body: {
+          name: 'John Doe',
+        },
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(201);
+
+      const body = JSON.parse(json!);
+
+      expect(body.data.name).toEqual('John Doe');
+    });
+  });
+});

package/src/Operation/security/__tests__/LambdaAuthorization.test.ts

@@ -0,0 +1,63 @@
+import { Profile } from '../../../../example/documents';
+import { LambdaRequest } from '../../../Context';
+import { createContext } from '../../../Context/__tests__/__helpers';
+import { service, handler } from '../../../../example';
+
+describe('LambdaAuthorization', () => {
+  const operationId = 'ReadProfileSystem';
+  const ReadProfileSystem = service.get(operationId);
+
+  describe('LambdaAuthorization.createRequirement(options)', () => {
+    it('extends operation with System security requirements', () => {
+      expect(ReadProfileSystem.security[0].System).toBeDefined();
+    });
+  });
+
+  describe('LambdaAuthorization.errors', () => {
+    it('includes authorization related errors', () => {
+      const errorCodes = Object.keys(ReadProfileSystem.errors);
+      expect(errorCodes).toContain('AccessDeniedError');
+    });
+  });
+
+  describe('.verify(context)', () => {
+    it('returns AccessDeniedError if headers are set by the gateway for external request', async () => {
+      const request = {
+        operationId,
+        headers: { Host: 'http://localhost:3000/' },
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(403);
+
+      const body = JSON.parse(json!);
+
+      expect(body).toEqual({
+        error: {
+          code: 'AccessDeniedError',
+          message: 'Access denied, operation is available only for internal requests',
+          statusCode: 403,
+        }
+      });
+    });
+
+    it('returns success if no headers are set by the gateway for internal request', async () => {
+      const context = createContext();
+      const { id } = await Profile.create(context, { name: 'John Doe' });
+
+      const request = {
+        operationId,
+        queryStringParameters: { id },
+      } as LambdaRequest;
+
+      const { statusCode, body: json } = await handler(request);
+
+      expect(statusCode).toEqual(200);
+
+      const body = JSON.parse(json!);
+
+      expect(body.data.name).toEqual('John Doe');
+    });
+  });
+});

package/src/Operation/security/__tests__/userAuthorization.test.ts

@@ -0,0 +1,42 @@
+import { Profile } from '../../../Document/__tests__/__helpers';
+import userAuthorization from '../userAuthorization';
+import { Create, Update } from '../../';
+import { TEST_ISSUER as issuer, TEST_PRIVATE_KEY as publicKey } from '../../../Service';
+
+describe('userAuthorization(props)', () => {
+  describe('OperationClass.permissions', () => {
+    const permissions = {
+      'profile-write': [
+        'CreateProfile',
+      ],
+    };
+
+    it('returns null if permissions are not defined', () => {
+      const asUser = userAuthorization({ issuer, publicKey });
+
+      /** Operation class to test no permissions case. */
+      class CreateProfile extends asUser(Create(Profile)) {}
+
+      expect(CreateProfile.permissions).toBeNull();
+    });
+
+    it('returns permissions from the permissions map', () => {
+      const asUser = userAuthorization({ issuer, publicKey, permissions });
+
+      /** Operation class to test no permissions case. */
+      class CreateProfile extends asUser(Create(Profile)) {}
+
+      expect(CreateProfile.permissions).toEqual([ 'profile-write' ]);
+    });
+
+    it('throws exception if operation permissions is not defined', () => {
+      const asUser = userAuthorization({ issuer, publicKey, permissions });
+
+      /** Operation class to test no permissions case. */
+      class UpdateProfile extends asUser(Update(Profile)) {}
+
+      expect(() => UpdateProfile.permissions)
+        .toThrow('Permissions not defined for operation "UpdateProfile"');
+    });
+  });
+});

package/src/Operation/security/index.ts

@@ -0,0 +1,15 @@
+import verifyToken from './verifyToken';
+import JwtAuthorization from './JwtAuthorization';
+import userAuthorization from './userAuthorization';
+import systemAuthorization from './systemAuthorization';
+import LambdaAuthorization from './LambdaAuthorization';
+
+export {
+  verifyToken,
+  JwtAuthorization,
+  userAuthorization,
+  systemAuthorization,
+  LambdaAuthorization,
+};
+
+export type * from './JwtAuthorization';

package/src/Operation/security/systemAuthorization.ts

@@ -0,0 +1,23 @@
+import Operation from '../Operation';
+import LambdaAuthorization from './LambdaAuthorization';
+
+const authorizationRequirement = LambdaAuthorization.createRequirement();
+
+/** Returns helper to extend operation class with system authorization requirements. */
+const systemAuthorization = () => {
+  return (OperationClass: typeof Operation): typeof Operation =>
+    /** Extended operation class. */
+    class extends OperationClass {
+      /** Returns operation security requirements. */
+      static get security() {
+        return [ authorizationRequirement ];
+      }
+
+      /** Returns a list of permissions to access operation. */
+      static get permissions() {
+        return [ 'System' ];
+      }
+    };
+};
+
+export default systemAuthorization;

package/src/Operation/security/userAuthorization.ts

@@ -0,0 +1,47 @@
+import Operation from '../Operation';
+import JwtAuthorization, { type Permissions } from './JwtAuthorization';
+
+type Props = {
+  issuer: string;
+  publicKey: string;
+  permissions?: Permissions;
+}
+
+/** Returns helper to extend operation class with user authorization requirement. */
+const userAuthorization = (props: Props) => {
+  const authorizationRequirement = JwtAuthorization.createRequirement(props);
+
+  return (OperationClass: typeof Operation): typeof Operation =>
+    /** Extended operation class. */
+    class extends OperationClass {
+      /** Returns operation security requirements. */
+      static get security() {
+        return [ authorizationRequirement ];
+      }
+
+      /** Returns a list of permissions to access operation. */
+      static get permissions() {
+        const permissionsMap = props.permissions;
+
+        if (!permissionsMap) {
+          return null;
+        }
+
+        const { id: operationId } = this;
+
+        const operationPermissions = Object.entries(permissionsMap)
+          .filter(([, operationIds]) => operationIds.includes(operationId))
+          .map(([permission]) => permission);
+
+        const hasPermissionsDefined = operationPermissions.length > 0;
+
+        if (!hasPermissionsDefined) {
+          throw new Error(`Permissions not defined for operation "${operationId}"`);
+        }
+
+        return operationPermissions;
+      }
+    };
+};
+
+export default userAuthorization;

package/src/Operation/security/verifyToken.ts

@@ -0,0 +1,22 @@
+import Context from '../../Context';
+import { verify, type Algorithm } from 'jsonwebtoken';
+
+/** Verifies JWT via public key and an algorithm. */
+const verifyToken = async (
+  _context: Context,
+  token: string,
+  publicKey: string,
+  algorithm: Algorithm
+): Promise<[ true ] | [ false, string ]> => {
+  try {
+    verify(token, publicKey, { algorithms: [ algorithm ] });
+
+  } catch (verificationError) {
+    return [ false, (verificationError as Error).message ];
+
+  }
+
+  return [ true ];
+};
+
+export default verifyToken;