GraphQL Authentication Directives

Common errors

• Error: Not authenticated!

  cause The `@isAuthenticated` directive was applied, but no valid JWT token was provided in the `Authorization: Bearer <token>` HTTP header, or the token was invalid/expired.
  fix Ensure a valid, unexpired JWT token is sent in the `Authorization` header. Verify `APP_SECRET` is correctly set and matches the key used to sign the token.

• Error: Unauthorized! User does not have the required role.

  cause The `@hasRole` directive was applied, but the `role` property in the authenticated user's JWT payload does not match the role specified in the directive argument.
  fix Check the `role` value in the JWT token (e.g., using jwt.io). Ensure it exactly matches the `role` argument provided to the `@hasRole` directive in your schema. If using a custom `checkRoleFunc`, debug its logic.

• TypeError: Cannot read properties of undefined (reading 'id')

  cause A resolver attempted to access `ctx.auth.user.id` or similar, but `ctx.auth` (or its `user` property) was `undefined` because authentication failed or a custom `authenticateFunc` did not return the expected structure.
  fix Add null/undefined checks before accessing properties of `ctx.auth` within resolvers (e.g., `if (ctx.auth?.user?.id) { ... }`). Review your custom `authenticateFunc` to ensure it always returns an object with the expected `user` property if authentication is successful.

Warnings

• breaking As of version 0.3.x, the library is still pre-1.0. Future major or minor versions may introduce breaking changes to the API, particularly to the signature of custom authentication or role-checking functions, or the structure of the `AuthDirective()` factory.
  Fix: Refer to the package's changelog or GitHub releases for specific upgrade instructions when updating across minor or major pre-1.0 versions. Thorough testing is recommended.
• gotcha The default `@isAuthenticated` and `@hasRole` directives rely on the `APP_SECRET` environment variable for JWT verification and expect the JWT token to contain a `role` property for role-based access control. Misconfiguration or missing these elements will lead to authentication failures.
  Fix: Ensure `process.env.APP_SECRET` is set to a strong, consistent secret key. For `@hasRole`, verify that the JWT token, when decoded, includes a `role` property matching the expected string. If custom logic is needed, implement `authenticateFunc` and `checkRoleFunc`.
• gotcha The authenticated user object is made available in the GraphQL `context` under `context.auth`. If you provide a custom `authenticateFunc`, ensure it returns an object with a consistent structure, as resolvers will depend on it. For example, if your custom function returns `{ user: { id: '...' } }`, your resolvers should access `ctx.auth.user.id`.
  Fix: Standardize the return structure of your custom `authenticateFunc`. Always check for the existence of `ctx.auth` and its properties within resolvers before accessing them, especially if authentication is optional or conditional for certain fields.

Install

• npm install graphql-directive-auth npm
• yarn add graphql-directive-auth yarn
• pnpm add graphql-directive-auth pnpm

Imports

• AuthDirective
  wrong:

  const AuthDirective = require('graphql-directive-auth');

  correct:

  import { AuthDirective } from 'graphql-directive-auth';

  While CommonJS `require` works, ESM `import` is preferred. The default export is a function factory.
• AuthDirective().isAuthenticated

  import { AuthDirective } from 'graphql-directive-auth';
  // ...
  auth: AuthDirective().isAuthenticated

  Access specific directives from the factory function's return. This allows aliasing, e.g., 'auth' instead of '@isAuthenticated'.
• AuthDirective().hasRole

  import { AuthDirective } from 'graphql-directive-auth';
  // ...
  role: AuthDirective().hasRole

  Access specific directives for role checking. Can be aliased for custom names in the schema.

Quickstart

This quickstart demonstrates setting up `graphql-directive-auth` with default authentication, protecting types and fields using `@isAuthenticated` and `@hasRole` directives, and accessing authenticated user data within resolvers. It includes type definitions, resolvers, and directive registration.

import { makeExecutableSchema } from 'graphql-tools';
import { AuthDirective } from 'graphql-directive-auth';

// Set APP_SECRET for default JWT verification.
// In a real application, use proper environment management (e.g., dotenv, Kubernetes secrets).
process.env.APP_SECRET = process.env.APP_SECRET ?? 'your_super_secret_key_for_dev';

const typeDefs = `
  directive @isAuthenticated on FIELD_DEFINITION | OBJECT
  directive @hasRole(role: String!) on FIELD_DEFINITION | OBJECT

  type User @isAuthenticated {
    id: ID!
    name: String!
    role: String! @hasRole(role: "admin")
  }

  type Query {
    me: User @isAuthenticated
    adminPanel: String @hasRole(role: "admin")
    publicGreeting: String
  }
`;

const resolvers = {
  Query: {
    me: (root, args, ctx) => {
      // ctx.auth will contain the decoded JWT payload or custom auth object
      if (!ctx.auth || !ctx.auth.user) throw new Error('Not authenticated');
      return { id: ctx.auth.user.id, name: ctx.auth.user.name, role: ctx.auth.user.role };
    },
    adminPanel: () => 'Welcome to the admin panel!',
    publicGreeting: () => 'Hello, world!'
  }
};

const schema = makeExecutableSchema({
  typeDefs,
  resolvers,
  schemaDirectives: {
    ...AuthDirective(), // Registers @isAuthenticated and @hasRole directives
    // Optionally, you can rename them:
    // auth: AuthDirective().isAuthenticated,
    // role: AuthDirective().hasRole
  }
});

// To use this schema, you would typically pass it to a GraphQL server (e.g., Apollo Server).
// For brevity, the server setup is omitted here.
// console.log(schema); // You can inspect the generated schema