feat(auth): add Envelop plugin and bump version to 2.4.1

Add createAuthPlugin() as a native Envelop/Yoga alternative to
graphql-middleware's applyMiddleware, which causes duplicate-type
errors with Simfinity schemas. Mark createAuthMiddleware and
createFieldMiddleware as deprecated.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Claudio Gonzalez

README.md

@@ -20,12 +20,13 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
   - [Adding Middlewares](#adding-middlewares)
   - [Middleware Parameters](#middleware-parameters)
   - [Common Use Cases](#common-use-cases)
-- [Authorization Middleware](#-authorization-middleware)
+- [Authorization](#-authorization)
   - [Quick Start](#quick-start-1)
   - [Permission Schema](#permission-schema)
   - [Rule Helpers](#rule-helpers)
   - [Policy Expressions (JSON AST)](#policy-expressions-json-ast)
-  - [Integration with graphql-middleware](#integration-with-graphql-middleware)
+  - [Integration with GraphQL Yoga / Envelop](#integration-with-graphql-yoga--envelop)
+  - [Legacy: Integration with graphql-middleware](#legacy-integration-with-graphql-middleware)
 - [Relationships](#-relationships)
   - [Defining Relationships](#defining-relationships)
   - [Auto-Generated Resolve Methods](#auto-generated-resolve-methods)
@@ -75,7 +76,7 @@ A powerful Node.js framework that automatically generates GraphQL schemas from y
 - **Lifecycle Hooks**: Controller methods for granular control over operations
 - **Custom Validation**: Field-level and type-level custom validations
 - **Relationship Management**: Support for embedded and referenced relationships
-- **Authorization Middleware**: Production-grade GraphQL authorization with RBAC/ABAC, function-based rules, and declarative policy expressions
+- **Authorization**: Production-grade GraphQL authorization with RBAC/ABAC, function-based rules, declarative policy expressions, and native Envelop/Yoga plugin support
 
 ## 📦 Installation
 
@@ -629,17 +630,17 @@ simfinity.use((params, next) => {
 5. **Performance consideration**: Middlewares run on every operation, keep them lightweight
 6. **Use context wisely**: Store request-specific data in the GraphQL context object
 
-## 🔐 Authorization Middleware
+## 🔐 Authorization
 
-Simfinity.js provides a production-grade centralized GraphQL authorization middleware supporting RBAC/ABAC, function-based rules, declarative policy expressions (JSON AST), wildcard permissions, and configurable default policies.
+Simfinity.js provides production-grade centralized GraphQL authorization supporting RBAC/ABAC, function-based rules, declarative policy expressions (JSON AST), wildcard permissions, and configurable default policies. It ships as a native Envelop plugin for GraphQL Yoga (recommended) and also supports the legacy graphql-middleware approach.
 
 ### Quick Start
 
 ```javascript
 const { auth } = require('@simtlix/simfinity-js');
-const { applyMiddleware } = require('graphql-middleware');
+const { createYoga } = require('graphql-yoga');
 
-const { createAuthMiddleware, requireAuth, requireRole } = auth;
+const { createAuthPlugin, requireAuth, requireRole } = auth;
 
 // Define your permission schema
 const permissions = {
@@ -665,9 +666,9 @@ const permissions = {
   },
 };
 
-// Create and apply the middleware
-const authMiddleware = createAuthMiddleware(permissions, { defaultPolicy: 'DENY' });
-const schemaWithAuth = applyMiddleware(schema, authMiddleware);
+// Create the Envelop auth plugin and pass it to your server
+const authPlugin = createAuthPlugin(permissions, { defaultPolicy: 'DENY' });
+const yoga = createYoga({ schema, plugins: [authPlugin] });
 ```
 
 ### Permission Schema
@@ -869,25 +870,24 @@ Use `{ ref: 'path' }` to reference values:
 - Unknown operators fail closed (deny)
 - No `eval()` or `Function()` - pure object traversal
 
-### Integration with graphql-middleware
+### Integration with GraphQL Yoga / Envelop
 
-The auth middleware integrates with the `graphql-middleware` package:
+The recommended way to use the auth system is via the Envelop plugin, which works natively with GraphQL Yoga and any Envelop-based server. The plugin wraps resolvers in-place without rebuilding the schema, avoiding compatibility issues.
 
 ```javascript
-const express = require('express');
-const { graphqlHTTP } = require('express-graphql');
-const { applyMiddleware } = require('graphql-middleware');
+const { createYoga } = require('graphql-yoga');
+const { createServer } = require('http');
 const simfinity = require('@simtlix/simfinity-js');
 
 const { auth } = simfinity;
-const { createAuthMiddleware, requireAuth, requireRole, requirePermission } = auth;
+const { createAuthPlugin, requireAuth, requireRole, requirePermission } = auth;
 
 // Define your types and connect them
 simfinity.connect(null, UserType, 'user', 'users');
 simfinity.connect(null, PostType, 'post', 'posts');
 
 // Create base schema
-const baseSchema = simfinity.createSchema();
+const schema = simfinity.createSchema();
 
 // Define permissions
 const permissions = {
@@ -921,36 +921,51 @@ const permissions = {
   },
 };
 
-// Create auth middleware
-const authMiddleware = createAuthMiddleware(permissions, {
-  defaultPolicy: 'DENY',  // Deny access when no rule matches
-  debug: false,           // Enable for debugging
+// Create auth plugin
+const authPlugin = createAuthPlugin(permissions, {
+  defaultPolicy: 'DENY',
+  debug: false,
 });
 
-// Apply middleware to schema
-const schema = applyMiddleware(baseSchema, authMiddleware);
-
-// Setup Express with context
-const app = express();
-
-app.use('/graphql', graphqlHTTP((req) => ({
+// Setup Yoga with the auth plugin
+const yoga = createYoga({
   schema,
-  graphiql: true,
-  context: {
-    user: req.user,  // Set by your authentication middleware
-  },
-  formatError: simfinity.buildErrorFormatter((err) => {
-    console.error(err);
+  plugins: [authPlugin],
+  context: (req) => ({
+    user: req.user,  // Set by your authentication layer
   }),
-})));
+});
 
-app.listen(4000);
+const server = createServer(yoga);
+server.listen(4000);
+```
+
+### Legacy: Integration with graphql-middleware
+
+> **Deprecated:** `applyMiddleware` from `graphql-middleware` rebuilds the schema via `mapSchema`,
+> which can cause `"Schema must contain uniquely named types"` errors with Simfinity schemas.
+> Use `createAuthPlugin` with GraphQL Yoga / Envelop instead.
+
+```javascript
+const { applyMiddleware } = require('graphql-middleware');
+const simfinity = require('@simtlix/simfinity-js');
+
+const { auth } = simfinity;
+const { createAuthMiddleware, requireAuth, requireRole } = auth;
+
+const baseSchema = simfinity.createSchema();
+
+const authMiddleware = createAuthMiddleware(permissions, {
+  defaultPolicy: 'DENY',
+});
+
+const schema = applyMiddleware(baseSchema, authMiddleware);
 ```
 
-### Middleware Options
+### Plugin / Middleware Options
 
 ```javascript
-const middleware = createAuthMiddleware(permissions, {
+const plugin = createAuthPlugin(permissions, {
   defaultPolicy: 'DENY',  // 'ALLOW' or 'DENY' (default: 'DENY')
   debug: false,           // Enable debug logging
 });

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simtlix/simfinity-js",
-  "version": "2.4.0",
+  "version": "2.4.1",
   "description": "",
   "main": "src/index.js",
   "type": "module",

src/auth/index.js

@@ -1,5 +1,5 @@
 /**
- * Simfinity GraphQL Authorization Middleware
+ * Simfinity GraphQL Authorization
  * 
  * Production-grade centralized GraphQL authorization supporting:
  * - RBAC / ABAC
@@ -10,9 +10,9 @@
  * 
  * @example
  * import { auth } from '@simtlix/simfinity-js';
- * import { applyMiddleware } from 'graphql-middleware';
+ * import { createYoga } from 'graphql-yoga';
  * 
- * const { createAuthMiddleware, requireAuth, requireRole } = auth;
+ * const { createAuthPlugin, requireAuth, requireRole } = auth;
  * 
  * const permissions = {
  *   Query: {
@@ -28,10 +28,11 @@
  *   }
  * };
  * 
- * const authMiddleware = createAuthMiddleware(permissions, { defaultPolicy: 'DENY' });
- * const schemaWithAuth = applyMiddleware(schema, authMiddleware);
+ * const authPlugin = createAuthPlugin(permissions, { defaultPolicy: 'DENY' });
+ * const yoga = createYoga({ schema, plugins: [authPlugin] });
  */
 
+import { GraphQLObjectType, defaultFieldResolver } from 'graphql';
 import { UnauthenticatedError, ForbiddenError, createAuthError } from './errors.js';
 import { isPolicyExpression, createRuleFromExpression, evaluateExpression } from './expressions.js';
 import {
@@ -169,33 +170,14 @@ const executeRule = async (rule, parent, args, ctx, info) => {
 };
 
 /**
- * Creates a graphql-middleware compatible authorization middleware
+ * Creates a graphql-middleware compatible authorization middleware.
+ * 
+ * @deprecated Use {@link createAuthPlugin} instead. `applyMiddleware` from graphql-middleware
+ * can cause duplicate-type errors when the schema contains custom introspection extensions.
  * 
  * @param {PermissionSchema} permissions - The permission schema object
  * @param {AuthMiddlewareOptions} [options={}] - Middleware options
  * @returns {Function} A graphql-middleware compatible middleware function
- * 
- * @example
- * const permissions = {
- *   Query: {
- *     users: requireAuth(),
- *     adminDashboard: requireRole('ADMIN')
- *   },
- *   User: {
- *     '*': requireAuth(),
- *     email: requireRole('ADMIN')
- *   },
- *   Post: {
- *     content: {
- *       anyOf: [
- *         { eq: [{ ref: 'parent.published' }, true] },
- *         { eq: [{ ref: 'parent.authorId' }, { ref: 'ctx.user.id' }] }
- *       ]
- *     }
- *   }
- * };
- * 
- * const middleware = createAuthMiddleware(permissions, { defaultPolicy: 'DENY' });
  */
 export const createAuthMiddleware = (permissions, options = {}) => {
   const {
@@ -250,8 +232,11 @@ export const createAuthMiddleware = (permissions, options = {}) => {
 };
 
 /**
- * Creates a field-level middleware object from a permission schema
- * This can be used with graphql-middleware's applyMiddleware
+ * Creates a field-level middleware object from a permission schema.
+ * This can be used with graphql-middleware's applyMiddleware.
+ * 
+ * @deprecated Use {@link createAuthPlugin} instead. `applyMiddleware` from graphql-middleware
+ * can cause duplicate-type errors when the schema contains custom introspection extensions.
  * 
  * @param {PermissionSchema} permissions - The permission schema
  * @param {AuthMiddlewareOptions} [options={}] - Middleware options
@@ -277,9 +262,103 @@ export const createFieldMiddleware = (permissions, options = {}) => {
   return fieldMiddleware;
 };
 
+/**
+ * Creates an Envelop-compatible authorization plugin that wraps schema resolvers in-place.
+ * 
+ * Unlike {@link createAuthMiddleware} (which requires graphql-middleware's `applyMiddleware`
+ * and rebuilds the schema), this plugin mutates resolvers directly on the existing schema,
+ * avoiding schema reconstruction and the duplicate-type errors it can cause.
+ * 
+ * @param {PermissionSchema} permissions - The permission schema object
+ * @param {AuthMiddlewareOptions} [options={}] - Plugin options
+ * @returns {Object} An Envelop plugin with an `onSchemaChange` hook
+ * 
+ * @example
+ * import { auth } from '@simtlix/simfinity-js';
+ * import { createYoga } from 'graphql-yoga';
+ * 
+ * const permissions = {
+ *   Query: {
+ *     users: requireAuth(),
+ *     adminDashboard: requireRole('ADMIN')
+ *   },
+ *   User: {
+ *     '*': requireAuth(),
+ *     email: requireRole('ADMIN')
+ *   }
+ * };
+ * 
+ * const authPlugin = auth.createAuthPlugin(permissions, { defaultPolicy: 'DENY' });
+ * const yoga = createYoga({ schema, plugins: [authPlugin] });
+ */
+export const createAuthPlugin = (permissions, options = {}) => {
+  const {
+    defaultPolicy = 'DENY',
+    debug = false,
+  } = options;
+
+  const log = debug ? console.log.bind(console, '[auth]') : () => {};
+  const processedSchemas = new WeakSet();
+
+  const wrapSchemaResolvers = (schema) => {
+    if (processedSchemas.has(schema)) return;
+
+    const typeMap = schema.getTypeMap();
+
+    for (const [typeName, type] of Object.entries(typeMap)) {
+      if (!(type instanceof GraphQLObjectType) || typeName.startsWith('__')) continue;
+
+      const fields = type.getFields();
+
+      for (const [fieldName, field] of Object.entries(fields)) {
+        const rules = getFieldRules(permissions, typeName, fieldName);
+        const originalResolve = field.resolve || defaultFieldResolver;
+
+        field.resolve = async (parent, args, ctx, info) => {
+          log(`Checking ${typeName}.${fieldName}`);
+
+          if (rules === null || rules.length === 0) {
+            log(`No rules for ${typeName}.${fieldName}, applying default policy: ${defaultPolicy}`);
+
+            if (defaultPolicy === 'DENY') {
+              throw new ForbiddenError(`Access denied to ${typeName}.${fieldName}`);
+            }
+
+            return originalResolve(parent, args, ctx, info);
+          }
+
+          for (const rule of rules) {
+            log(`Executing rule for ${typeName}.${fieldName}`);
+
+            const allowed = await executeRule(rule, parent, args, ctx, info);
+
+            if (!allowed) {
+              log(`Rule denied access to ${typeName}.${fieldName}`);
+              throw new ForbiddenError(`Access denied to ${typeName}.${fieldName}`);
+            }
+          }
+
+          log(`Access granted to ${typeName}.${fieldName}`);
+
+          return originalResolve(parent, args, ctx, info);
+        };
+      }
+    }
+
+    processedSchemas.add(schema);
+  };
+
+  return {
+    onSchemaChange({ schema }) {
+      wrapSchemaResolvers(schema);
+    },
+  };
+};
+
 // Default export with all auth utilities
 const auth = {
-  // Main factory
+  // Main factories
+  createAuthPlugin,
   createAuthMiddleware,
   createFieldMiddleware,
 

src/plugins.js

@@ -1,3 +1,7 @@
+import { createAuthPlugin } from './auth/index.js';
+
+export { createAuthPlugin } from './auth/index.js';
+
 /**
  * Apollo Server plugin to add count to GraphQL response extensions
  * @returns {Object} Apollo Server plugin
@@ -40,11 +44,10 @@ export const envelopCountPlugin = () => {
   };
 };
 
-// Export all plugins as an object for convenience
 const plugins = {
+  createAuthPlugin,
   apolloCountPlugin,
   envelopCountPlugin,
 };
 
 export default plugins;
-