npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@ambler/graphql-shield

v2.2.7-ambler.0

Published

GraphQL Server permissions as another layer of abstraction!

Downloads

254

Readme

graphql-shield

CircleCI npm version Backers on Open Collective Sponsors on Open Collective

GraphQL Server permissions as another layer of abstraction!

Overview

GraphQL Shield helps you create a permission layer for your application. Using an intuitive rule-API, you'll gain the power of the shield engine on every request and reduce the load time of every request with smart caching. This way you can make sure your application will remain quick, and no internal data will be exposed.

Sponsored By GraphCMS

Try building a groceries shop to better understand the benefits of GraphQL Shield! Banana &Co. 🍏🍌🍓.

Features

  • ✂️ Flexible: Based on GraphQL Middleware.
  • 😌 Easy to use: Just add permissions to your Yoga middlewares set, and you are ready to go!
  • 🤝 Compatible: Works with all GraphQL Servers.
  • 🚀 Smart: Intelligent V8 Shield engine caches all your request to prevent any unnecessary load.
  • 🎯 Per-Type: Write permissions for your schema, types or specific fields (check the example below).
  • 💯 Tested: Very well tested functionalities!

Install

yarn add graphql-shield

Example

GraphQL Yoga

import { GraphQLServer } from 'graphql-yoga'
import { rule, shield, and, or, not } from 'graphql-shield'

const typeDefs = `
  type Query {
    frontPage: [Fruit!]!
    fruits: [Fruit!]!
    customers: [Customer!]!
  }

  type Mutation {
    addFruitToBasket: Boolean!
  }

  type Fruit {
    name: String!
    count: Int!
  }

  type Customer {
    id: ID!
    basket: [Fruit!]!
  }
`

const resolvers = {
  Query: {
    frontPage: () => [{name: "orange", count: 10}, {name: "apple", count: 1}]
  }
}

// Auth

const users = {
  mathew: {
    id: 1,
    name: "Mathew",
    role: "admin"
  },
  george: {
    id: 2,
    name: "George",
    role: "editor"
  },
  johnny: {
    id: 3,
    name: "Johnny",
    role: "customer"
  }
}

function getUser(req) {
  const auth = req.get('Authorization')
  if (users[auth]) {
    return users[auth]
  } else {
    return null
  }
}

// Rules

const isAuthenticated = rule()(async (parent, args, ctx, info) => {
  return ctx.user !== null
})

const isAdmin = rule()(async (parent, args, ctx, info) => {
  return ctx.user.role === 'admin'
})

const isEditor = rule()(async (parent, args, ctx, info) => {
  return ctx.user.role === 'editor'
})


// Permissions

const permissions = shield({
  Query: {
    frontPage: not(isAuthenticated),
    fruits: and(isAuthenticated, or(isAdmin, isEditor)),
    customers: and(isAuthenticated, isAdmin)
  },
  Mutation: {
    addFruitToBasket: isAuthenticated,
  },
  Fruit: isAuthenticated,
  Customer: isAdmin
})

const server = GraphQLServer({
  typeDefs,
  resolvers,
  middlewares: [permissions],
  context: req => ({
    ...req,
    user: getUser(req)
  })
})

server.start(() => console.log('Server is running on http://localhost:4000'))

Others

// Permissions...

// Apply permissions middleware with applyMiddleware
// Giving any schema (instance of GraphQLSchema)

import { applyMiddleware } from 'graphql-middleware';
// schema definition...
schema = applyMiddleware(schema, permissions);

API

Types

// Rule
function rule(name?: string, options?: IRuleOptions)(func: IRuleFunction): Rule

type IRuleFunction = (
  parent: any,
  args: any,
  context: any,
  info: GraphQLResolveInfo,
) => Promise<boolean>

export type ICache = 'strict' | 'contextual' | 'no_cache'

export interface IRuleOptions {
  cache?: ICache
}

// Logic
function and(...rules: IRule[]): LogicRule
function or(...rules: IRule[]): LogicRule
function not(rule: IRule): LogicRule

// Predefined rules
const allow: Rule
const deny: Rule

type IRule = Rule | LogicRule

interface IRuleFieldMap {
  [key: string]: IRule
}

interface IRuleTypeMap {
  [key: string]: IRule | IRuleFieldMap
}

type IRules = IRule | IRuleTypeMap

function shield(rules?: IRules, options?: IOptions): IMiddleware

export interface IOptions {
  debug?: boolean
  allowExternalErrors?: boolean
}

shield(rules?, options?)

Generates GraphQL Middleware layer from your rules.

rules

A rule map must match your schema definition. All rules must be created using the rule function to ensure caches are made correctly. You can apply your rule accross entire schema, Type scoped, or field specific.

Limitations
  • All rules must have a distinct name. Usually, you won't have to care about this as all names are by default automatically generated to prevent such problems. In case your function needs additional variables from other parts of the code and is defined as a function, you'll set a specific name to your rule to avoid name generation.
// Normal
const admin = rule({ cache: 'contextual' })(async (parent, args, ctx, info) => true)

// With external data
const admin = bool =>
  rule(`name`, { cache: 'contextual' })(async (parent, args, ctx, info) => bool)
  • Cache is enabled by default accross all rules. To prevent cache generation, set { cache: 'no_cache' } when generating a rule.
  • By default, no rule is executed more than once in complete query execution. This accounts for significantly better load times and quick responses.
Cache

You can choose from three different cache options.

  1. no_cache - prevents rules from being cached.
  2. contextual - use when rule only relies on ctx parameter.
  3. strict - use when rule relies on parent or args parameter as well.
// Contextual
const admin = rule({ cache: 'contextual' })(async (parent, args, ctx, info) => {
  return ctx.user.isAdmin
})

// Strict
const admin = rule({ cache: 'strict' })(async (parent, args, ctx, info) => {
  return ctx.user.isAdmin || args.code === 'secret' || parent.id === 'theone'
})

Backward compatiblity: { cache: false } converts to no_cache, and { cache: true } converts to strict.

options

| Property | Required | Default | Description | | ------------------- | -------- | ------- | ------------------------------------------- | | allowExternalErrors | false | false | Toggles catching internal resolvers errors. |

By default shield ensures no internal data is exposed to client if it was not meant to be. Therefore, all thrown errors during execution resolve in Not Authenticated! error message if not otherwise specified using CustomError. This can be turned off by setting allowExternalErrors option to true.

allow, deny

GraphQL Shield predefined rules.

allow and deny rules do exactly what their names describe.

and, or, not

and, or and not allow you to nest rules in logic operations.

  • Nested rules fail by default if error is thrown.

And Rule

And rule allows access only if all sub rules used return true.

Or Rule

Or rule allows access if at least one sub rule returns true and no rule throws an error.

Not

Not works as usual not in code works.

import { shield, rule, and, or } from 'graphql-shield'

const isAdmin = rule()(async (parent, args, ctx, info) => {
  return ctx.user.role === 'admin'
})

const isEditor = rule()(async (parent, args, ctx, info) => {
  return ctx.user.role === 'editor'
})

const isOwner = rule()(async (parent, args, ctx, info) => {
  return ctx.user.items.some(id => id === parent.id)
})

const permissions = shield({
  Query: {
    users: or(isAdmin, isEditor)
  },
  Mutation: {
    createBlogPost: or(isAdmin, and(isOwner, isEditor))
  },
  User: {
    secret: isOwner
  },
})

Custom Errors

Shield, by default, catches all errors thrown during resolver execution. This way we can be 100% sure none of your internal logic will be exposed to the client if it was not meant to be.

Nevertheless, you can use CustomError error types to report your custom error messages to your users.

import { CustomError } from 'graphql-shield'

const typeDefs = `
  type Query {
    customError: String!
  }
`

const resolvers = {
  Query: {
    customError: () => {
      throw new CustomError('customErrorResolver')
    },
  }
}

const permissions = shield()

const server = GraphQLServer({
  typeDefs,
  resolvers,
  middlewares: [permissions]
})

Contributors

This project exists thanks to all the people who contribute. [Contribute].

Backers

Thank you to all our backers! 🙏 [Become a backer]

Sponsors

Support this project by becoming a sponsor. Your logo will show up here with a link to your website. [Become a sponsor]

Contributing

We are always looking for people to help us grow graphql-shield! If you have an issue, feature request, or pull request, let us know!

License

MIT @ Matic Zavadlal