{"library":"mercurius-auth","title":"Mercurius Auth Plugin","description":"Mercurius Auth is a Fastify plugin designed to add configurable authentication and authorization support to GraphQL APIs built with Mercurius. It is currently at stable version 6.0.0, with major updates often aligning with new Fastify or Mercurius versions. The plugin allows defining auth directives directly within the GraphQL schema to apply custom policies against protected fields, supporting both normal and gateway modes. Alternatively, it can operate in an 'External Policy' mode, offering programmatic control over authorization. Key differentiators include its tight integration with the Fastify and Mercurius ecosystems, its ability to build an auth context, and its GraphQL spec compliance, including features like schema filtering and replacement. Development appears active, with regular updates and dependency bumps.","language":"javascript","status":"active","last_verified":"Wed Apr 22","install":{"commands":["npm install mercurius-auth"],"cli":null},"imports":["import mercuriusAuth from 'mercurius-auth'","import Fastify from 'fastify'","import mercurius from 'mercurius'"],"auth":{"required":false,"env_vars":[]},"quickstart":{"code":"import Fastify from 'fastify';\nimport mercurius from 'mercurius';\nimport mercuriusAuth from 'mercurius-auth';\n\nconst app = Fastify();\n\nconst schema = `\n  directive @auth(\n    requires: Role = ADMIN,\n  ) on OBJECT | FIELD_DEFINITION\n\n  enum Role {\n    ADMIN\n    REVIEWER\n    USER\n    UNKNOWN\n  }\n\n  type Query {\n    add(x: Int, y: Int): Int @auth(requires: USER)\n    adminData: String @auth(requires: ADMIN)\n  }\n`;\n\nconst resolvers = {\n  Query: {\n    add: async (_, { x, y }) => x + y,\n    adminData: async () => 'Secret admin information'\n  }\n};\n\napp.register(mercurius, {\n  schema,\n  resolvers\n});\n\napp.register(mercuriusAuth, {\n  authContext (context) {\n    // Simulate loading user identity from request headers\n    const identity = context.reply.request.headers['x-user'] || 'UNKNOWN';\n    return {\n      identity: identity.toUpperCase() // Ensure consistency\n    };\n  },\n  async applyPolicy (authDirectiveAST, parent, args, context, info) {\n    const requiredRole = authDirectiveAST.requires;\n    const userRole = context.auth.identity; // Assuming identity is the role for simplicity\n\n    if (requiredRole === 'ADMIN' && userRole !== 'ADMIN') {\n      return false;\n    }\n    if (requiredRole === 'USER' && (userRole !== 'ADMIN' && userRole !== 'USER')) {\n        return false;\n    }\n    return true; // Policy passes\n  },\n  authDirective: 'auth'\n});\n\napp.listen({ port: 3000 }, (err) => {\n  if (err) {\n    app.log.error(err);\n    process.exit(1);\n  }\n  app.log.info(`Server listening on port 3000`);\n});\n\n// Example usage (e.g., with curl):\n// curl -H \"x-user: user\" http://localhost:3000/graphql -X POST -H \"Content-Type: application/json\" -d '{\"query\":\"query { add(x: 5, y: 3) }\"}'\n// curl -H \"x-user: admin\" http://localhost:3000/graphql -X POST -H \"Content-Type: application/json\" -d '{\"query\":\"query { adminData }\"}'\n// curl -H \"x-user: user\" http://localhost:3000/graphql -X POST -H \"Content-Type: application/json\" -d '{\"query\":\"query { adminData }\"}' // Should fail","lang":"typescript","description":"This quickstart demonstrates `mercurius-auth` in 'Directive mode' using Fastify and Mercurius. It defines a custom `@auth` directive with role-based authorization, extracting the user role from request headers in `authContext` and enforcing policies in `applyPolicy`.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}