feat(api): schools config (#53)

Author: akdasa

docs/adr/002 School Configurations.md

@@ -0,0 +1,51 @@
+# ADR: School Configurations
+
+We need a method to store and manage school-specific configurations, such as student roles and default student role settings. The configuration should be easily retrievable and updatable through API endpoints while maintaining simplicity in the implementation given our current requirements.
+
+## Decision
+We will implement school configurations using the following approach:
+
+1. **Configuration Structure**: 
+   - Configurations will be stored as JSON objects
+   - Example format: `{ studentRoles: [1,2,3], defaultStudentRole: 1 }`
+   - This allows flexible key-value pairs to accommodate current needs (student roles) and potential future configuration parameters
+
+2. **API Endpoints**:
+   - `GET /edu/schools/:guid/config`: Retrieve the complete configuration for a specific school
+   - `PATCH /edu/schools/:guid/config`: Update specific configuration values for a school
+   - Using RESTful conventions with school GUID as the identifier
+
+3. **Storage**:
+   - Configurations will be stored in the existing `Schools` table as a JSON column
+   - This leverages existing infrastructure and maintains data locality with school records
+
+## Consequences
+- **Positive**
+  - Simple implementation using existing database infrastructure
+  - Single table access for school data and configuration
+  - Flexible JSON structure allows for future configuration additions
+  - Standard RESTful API endpoints for easy integration
+  - Atomic updates possible through PATCH operations
+  - Payload of `PATCH /edu/schools/:guid/config` can be validated by NestJS framework
+
+- **Negative**
+  - Potential size limitations with JSON column in database
+  - Less granular control compared to separate configuration tables
+  - Schema validation must be handled in application layer
+
+## Rejected Alternatives
+
+1. **Separate SchoolConfig Table**
+   - Description: Create a dedicated table for configurations with foreign key to Schools
+   - Rejected because:
+     - Adds unnecessary complexity for current simple configuration needs
+     - Requires additional joins for data retrieval
+     - More schema maintenance overhead
+
+2. **External Storage (Redis)**
+   - Description: Store configurations in a separate key-value store like Redis
+   - Rejected because:
+     - Introduces additional infrastructure component to maintain
+     - Increases operational complexity
+     - Overkill for current configuration volume and access patterns
+     - Adds deployment and monitoring overhead

modules/libs/entities/school.ts

@@ -1,4 +1,17 @@
-import { Entity, Column, PrimaryGeneratedColumn, ManyToOne, JoinColumn } from 'typeorm';
+import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';
+
+export type SchoolConfig = {
+  /**
+   * The default role for students in this school.
+   * This role will be assigned to students when they are joined.
+   */
+  defaultStudentRoleId: string;
+  
+  /**
+   * List of student roles that are available in this school.
+   */
+  studentRoleIds: string[];
+};
 
 @Entity({ name: 'schools' })
 export class School {
@@ -7,4 +20,7 @@ export class School {
 
   @Column({ nullable: false })
   name: string;
+
+  @Column({ nullable: false, type: 'json', default: {} })
+  config: SchoolConfig;
 }

modules/libs/protocol/routes.ts

@@ -30,9 +30,18 @@ export const Routes = (baseUrl: string = '') => ({
         all: () => `${baseUrl}/edu/users/${userId}/roles`,
         create: () => `${baseUrl}/edu/users/${userId}/roles`,
         delete: (roleId: string) => `${baseUrl}/edu/users/${userId}/roles/${roleId}`,
+      },
+      schools: {
+        all: () => `${baseUrl}/edu/users/${userId}/schools`,
+        create: () => `${baseUrl}/edu/users/${userId}/schools`,
+        delete: (roleId: string) => `${baseUrl}/edu/users/${userId}/schools/${roleId}`,
       }
     }),
     schools: {
+      configs: {
+        getAll: (schoolId: string) => `${baseUrl}/edu/schools/${schoolId}/configs`,
+        update: (schoolId: string) => `${baseUrl}/edu/schools/${schoolId}/configs`,
+      },
       find: () => `${baseUrl}/edu/schools`,
       get: (id: string) => `${baseUrl}/edu/schools/${id}`,
       create: () => `${baseUrl}/edu/schools`,

modules/services/api/src/edu/controllers/roles/roles.controller.ts

@@ -1,6 +1,7 @@
 import { Mapper } from '@automapper/core';
 import { InjectMapper } from '@automapper/nestjs';
 import {
+  BadRequestException,
   Body,
   Controller,
   ForbiddenException,
@@ -172,6 +173,10 @@ export class RolesController {
       throw new ForbiddenException('User does not have permission');
     }
 
+    if (role && role.permissions.includes('*')) {
+      throw new BadRequestException('Cannot delete Owner role');
+    }
+
     // Delete role
     await this.rolesService.deleteOneBy({ id });
 

modules/services/api/src/edu/controllers/roles/specs/context.ts

@@ -8,11 +8,11 @@ export type Context = {
   one: {
     school: School;
     roles: {
-      admin: Role;
+      owner: Role;
       readonly: Role;
     };
     tokens: {
-      admin: string;
+      owner: string;
       readOnly: string;
       oneAndTwoAdmin: string;
     };
@@ -67,10 +67,10 @@ export const createContext = async (
   /*                                    Roles                                   */
   /* -------------------------------------------------------------------------- */
 
-  const oneAdminRole = await rolesService.create({
-    name: 'One :: Admin',
-    description: 'Admin role for school one',
-    permissions: ['roles:create', 'roles:read', 'roles:update', 'roles:delete'],
+  const oneOwnerRole = await rolesService.create({
+    name: 'One :: Owner',
+    description: 'Owner role for school one',
+    permissions: ['*'],
     schoolId: schoolOne.id,
   });
 
@@ -92,8 +92,8 @@ export const createContext = async (
   /*                                   Tokens                                   */
   /* -------------------------------------------------------------------------- */
 
-  const oneTokenAdmin = await authService.generateTokens(faker.string.uuid(), [
-    { sid: schoolOne.id, p: oneAdminRole.permissions },
+  const oneOwnerAdmin = await authService.generateTokens(faker.string.uuid(), [
+    { sid: schoolOne.id, p: oneOwnerRole.permissions },
   ]);
 
   const oneTokenReadonly = await authService.generateTokens(
@@ -113,7 +113,7 @@ export const createContext = async (
   );
 
   const oneAndTwoAdmin = await authService.generateTokens(faker.string.uuid(), [
-    { sid: schoolOne.id, p: oneAdminRole.permissions },
+    { sid: schoolOne.id, p: oneOwnerRole.permissions },
     { sid: schoolTwo.id, p: twoAdminRole.permissions },
   ]);
 
@@ -130,11 +130,11 @@ export const createContext = async (
     one: {
       school: schoolOne,
       roles: {
-        admin: oneAdminRole,
+        owner: oneOwnerRole,
         readonly: oneReadonlyRole,
       },
       tokens: {
-        admin: oneTokenAdmin.accessToken,
+        owner: oneOwnerAdmin.accessToken,
         readOnly: oneTokenReadonly.accessToken,
         oneAndTwoAdmin: oneAndTwoAdmin.accessToken,
       },

modules/services/api/src/edu/controllers/roles/specs/roles.controller.e2e.create.spec.ts

@@ -133,12 +133,37 @@ describe('/edu/roles', () => {
 
     request(app.getHttpServer())
       .post(protocol.Routes().edu.roles.create())
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
       .send(payload)
       .expect(201)
       .expect((res) => {
         expect(res.body).toHaveProperty('id');
         expect(res.body.id).toBeDefined();
       });
   });
+
+  /* -------------------------------------------------------------------------- */
+  /*                               Negative Cases                               */
+  /* -------------------------------------------------------------------------- */
+
+  it(`POST /edu/roles returns 400 if permissions contain *`, async () => {
+    const payload: protocol.CreateRoleRequest = {
+      name: 'New Role',
+      description: 'Role description',
+      permissions: ['*'],
+      schoolId: ctx.one.school.id,
+    };
+
+    return request(app.getHttpServer())
+      .post(protocol.Routes().edu.roles.create())
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
+      .send(payload)
+      .expect(400)
+      .expect((res) => {
+        expect(res.body).toHaveProperty('message');
+        expect(res.body.message).toStrictEqual([
+          'permissions cannot contain *',
+        ]);
+      });
+  });
 });

modules/services/api/src/edu/controllers/roles/specs/roles.controller.e2e.delete.spec.ts

@@ -30,7 +30,7 @@ describe('/edu/roles', () => {
   it(`DELETE /edu/roles/:id 400 if id is invalid format`, async () => {
     return request(app.getHttpServer())
       .delete(Routes().edu.roles.delete('invalid-uuid'))
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
       .expect(400)
       .expect((res) => {
         expect(res.body).toHaveProperty('message');
@@ -44,7 +44,7 @@ describe('/edu/roles', () => {
 
   it(`DELETE /edu/roles/:id returns 401 for unauthorized user`, async () => {
     return request(app.getHttpServer())
-      .delete(Routes().edu.roles.delete(ctx.one.roles.admin.id))
+      .delete(Routes().edu.roles.delete(ctx.one.roles.owner.id))
       .expect(401);
   });
 
@@ -55,7 +55,7 @@ describe('/edu/roles', () => {
   it('DELETE /edu/roles/:id returns 403 for unauthorized user', async () => {
     return request(app.getHttpServer())
       .delete(Routes().edu.roles.delete(ctx.two.roles.admin.id))
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
       .expect(403)
       .expect((res) => {
         expect(res.body).toHaveProperty('message');
@@ -69,8 +69,8 @@ describe('/edu/roles', () => {
 
   it(`DELETE /edu/roles/:id deletes an existing role`, async () => {
     return request(app.getHttpServer())
-      .delete(Routes().edu.roles.delete(ctx.one.roles.admin.id))
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .delete(Routes().edu.roles.delete(ctx.two.roles.admin.id))
+      .set('Authorization', `Bearer ${ctx.two.tokens.admin}`)
       .expect(200)
       .expect((res) => {
         expect(res.body).toHaveProperty('success');
@@ -82,11 +82,23 @@ describe('/edu/roles', () => {
   /*                               Negative Cases                               */
   /* -------------------------------------------------------------------------- */
 
+  it(`DELETE /edu/roles/:id deletes an existing role`, async () => {
+    return request(app.getHttpServer())
+      .delete(Routes().edu.roles.delete(ctx.one.roles.owner.id))
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
+      .expect(400)
+      .expect({
+        message: 'Cannot delete Owner role',
+        error: 'Bad Request',
+        statusCode: 400,
+      });
+  });
+
   it(`DELETE /edu/roles/:id returns 404 for non-existent role`, async () => {
     const nonExistentId = faker.string.uuid();
     return request(app.getHttpServer())
       .delete(Routes().edu.roles.delete(nonExistentId))
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
       .expect(404)
       .expect((res) => {
         expect(res.body).toHaveProperty('message');

modules/services/api/src/edu/controllers/roles/specs/roles.controller.e2e.get.spec.ts

@@ -46,12 +46,12 @@ describe('/edu/roles', () => {
   it(`GET /edu/roles returns only permitted roles`, async () => {
     return request(app.getHttpServer())
       .get(Routes().edu.roles.find())
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
       .expect(200)
       .expect({
         items: instanceToPlain(
           mapper.mapArray(
-            [ctx.one.roles.admin, ctx.one.roles.readonly],
+            [ctx.one.roles.owner, ctx.one.roles.readonly],
             entities.Role,
             dto.RoleSummary,
           ),
@@ -67,7 +67,7 @@ describe('/edu/roles', () => {
       .expect({
         items: instanceToPlain(
           mapper.mapArray(
-            [ctx.one.roles.admin, ctx.one.roles.readonly, ctx.two.roles.admin],
+            [ctx.one.roles.owner, ctx.one.roles.readonly, ctx.two.roles.admin],
             entities.Role,
             dto.RoleSummary,
           ),

modules/services/api/src/edu/controllers/roles/specs/roles.controller.e2e.update.spec.ts

@@ -41,7 +41,7 @@ describe('/edu/roles', () => {
 
   it(`PATCH /edu/roles/:id returns 401 for unauthorized user`, async () => {
     return request(app.getHttpServer())
-      .patch(Routes().edu.roles.update(ctx.one.roles.admin.id))
+      .patch(Routes().edu.roles.update(ctx.one.roles.owner.id))
       .expect(401);
   });
 
@@ -53,7 +53,7 @@ describe('/edu/roles', () => {
     const updatedRole = { name: 'Updated Role' };
 
     return request(app.getHttpServer())
-      .patch(Routes().edu.roles.update(ctx.one.roles.admin.id))
+      .patch(Routes().edu.roles.update(ctx.one.roles.owner.id))
       .set('Authorization', `Bearer ${ctx.one.tokens.readOnly}`)
       .send(updatedRole)
       .expect(403)
@@ -88,6 +88,10 @@ describe('/edu/roles', () => {
       payload: { description: faker.lorem.paragraphs(5) },
       errors: ['description must be shorter than or equal to 256 characters'],
     },
+    {
+      payload: { permissions: ['*'] },
+      errors: ['permissions cannot contain *'],
+    },
     // Permissions
     {
       payload: { permissions: ['invalid'] },
@@ -100,8 +104,8 @@ describe('/edu/roles', () => {
     `PATCH /edu/roles/:id 400 if payload is invalid`,
     async ({ payload, errors }) => {
       return request(app.getHttpServer())
-        .patch(Routes().edu.roles.update(ctx.one.roles.admin.id))
-        .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+        .patch(Routes().edu.roles.update(ctx.one.roles.owner.id))
+        .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
         .send(payload)
         .expect(400)
         .expect((res) => {
@@ -121,8 +125,8 @@ describe('/edu/roles', () => {
     { name: '#$#$#$%$#%^' },
   ])(`PATCH /edu/roles/:id updates an existing role`, async (payload) => {
     return request(app.getHttpServer())
-      .patch(Routes().edu.roles.update(ctx.one.roles.admin.id))
-      .set('Authorization', `Bearer ${ctx.one.tokens.admin}`)
+      .patch(Routes().edu.roles.update(ctx.one.roles.owner.id))
+      .set('Authorization', `Bearer ${ctx.one.tokens.owner}`)
       .send(payload)
       .expect(200)
       .expect((res) => {