Future Roadmap: Mutations

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/generated/parser.ts
• src/descriptionToRoles.ts
• src/index.ts
• src/makeFieldConstraintMiddleware.ts
• package.json

The @joindeed/prisma-auth library currently focuses on securing read operations within GraphQL and Prisma environments. The roadmap for mutations involves extending the declarative authorization layer to support create, update, and delete operations, which are presently handled manually via custom input types.

Sources: README.md:104-108, src/index.ts:36-40

Mutation Support Status

The project architecture provides the necessary infrastructure to parse mutation-related metadata, although the middleware implementation is currently limited to read access.

Parser Capabilities

The PEG.js-generated parser already recognizes mutation keywords within the @Auth annotation. This allows the system to identify which roles are associated with specific write operations in the Prisma schema.

Operation Keyword	Parser Support	Current Middleware Implementation
read	Fully Supported	Active via makeAuthorizationMiddlewares
create	Supported in Grammar	Pending Implementation
update	Supported in Grammar	Pending Implementation
delete	Supported in Grammar	Pending Implementation

Sources: src/generated/parser.ts:466-478, src/descriptionToRoles.ts:24-30, src/index.ts:36-40

Grammar Specification

The current grammar defines OperationName to include mutation types. When the parser encounters these keywords in a Prisma comment, it generates an object mapping these operations to their respective role arrays.

// Example of how the parser handles operation names
function peg$parseOperationName(): any {
  // ... checks for "read", "create", "update", "delete" ...
}

Sources: src/generated/parser.ts:466-490

Architecture for Mutations

Implementing mutations requires extending the existing middleware pattern. The current architecture uses a combination of matcher functions for record-level validation and queryConstraint objects for Prisma where clause generation.

Metadata Extraction

The descriptionToRoles function extracts roles for all four operations. While currently utilized primarily for read, the return type includes keys for create, update, and delete.

export const descriptionToRoles = (
  description?: string | null
): Record<'create' | 'read' | 'update' | 'delete', RoleDescription[]> | null => {
  if (!description || !description.includes('@Auth')) {
    return null
  }
  return parse(description)
}

Sources: src/descriptionToRoles.ts:20-30

Proposed Middleware Flow

The following diagram illustrates how future mutation middleware would integrate with the existing lifecycle:

The diagram shows the logical extension of the descriptionToRoles utility into mutation-specific validation.

Sources: src/makeFieldConstraintMiddleware.ts:25-50, src/makeTypeConstraintMiddleware.ts:40-65

Implementation Requirements

To fully support mutations, several components within the core library require updates:

1. Middleware Factory: The makeAuthorizationMiddlewares function must include new middlewares specifically for write operations.
2. Role Matcher Arguments: Mutation matchers may require access to the incoming args (input data) rather than just the existing record to validate if the new data complies with security policies.
3. Result Patching: The patchResponse utility, which currently handles null or empty lists for read operations, must be adapted to handle mutation return types or throw specific authorization errors.

Sources: src/index.ts:36-40, src/makeFieldConstraintMiddleware.ts:50-53, src/descriptionToRoles.ts:28-30

Conclusion

The roadmap for mutations leverages the existing PEG.js parser and role-based configuration. By expanding the middleware suite to intercept create, update, and delete operations, the library will provide a unified declarative security layer for both data retrieval and modification.

Sources: README.md:104-108, src/descriptionToRoles.ts:28-30