@makerx/graphql-core 3.0.0-beta.1 → 3.0.0-beta.3

package/README.md

@@ -91,21 +91,21 @@ const graphqlServer = createServer({
 
 `context.requestInfo` is built for every request — both HTTP and websocket subscription connects — so downstream code can distinguish sources, rebuild URLs, pass through correlation headers, etc.
 
-| Field           | Description                                                                                                                                                                   |
-| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `requestId`     | `x-request-id` header if present, otherwise a freshly generated UUID.                                                                                                         |
-| `source`        | `'http'` for regular requests, `'subscription'` for websocket connects.                                                                                                       |
-| `protocol`      | `'http'` / `'https'` for HTTP, `'ws'` / `'wss'` for subscriptions (resolved via `x-forwarded-proto` or TLS socket encryption).                                                |
-| `host`          | Hostname only (no port). Prefers `x-forwarded-host`, falls back to the `Host` header, then `req.hostname` (Express only).                                                     |
-| `port`          | Port parsed from `x-forwarded-host` / `Host` header when present; `undefined` otherwise.                                                                                      |
+| Field           | Description                                                                                                                                                                    |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `requestId`     | `x-request-id` header if present, otherwise a freshly generated UUID.                                                                                                          |
+| `source`        | `'http'` for regular requests, `'subscription'` for websocket connects.                                                                                                        |
+| `protocol`      | `'http'` / `'https'` for HTTP, `'ws'` / `'wss'` for subscriptions (resolved via `x-forwarded-proto` or TLS socket encryption).                                                 |
+| `host`          | Hostname only (no port). Prefers `x-forwarded-host`, falls back to the `Host` header, then `req.hostname` (Express only).                                                      |
+| `port`          | Port parsed from `x-forwarded-host` / `Host` header when present; `undefined` otherwise.                                                                                       |
 | `baseUrl`       | Fully-qualified origin (`scheme://host[:port]`) with default ports stripped. For subscriptions the scheme is normalised to `http(s)` so the value composes with relative URLs. |
-| `url`           | `req.originalUrl` for HTTP, `req.url` for subscription connects.                                                                                                              |
-| `origin`        | `Origin` header.                                                                                                                                                              |
-| `referer`       | `Referer` header.                                                                                                                                                             |
-| `correlationId` | `x-correlation-id` header.                                                                                                                                                    |
-| `arrLogId`      | `x-arr-log-id` header (Azure Front Door / ARR).                                                                                                                               |
-| `clientIp`      | First value from `x-forwarded-for`, falling back to `socket.remoteAddress`.                                                                                                   |
-| `userAgent`     | `User-Agent` header.                                                                                                                                                          |
+| `url`           | `req.originalUrl` for HTTP, `req.url` for subscription connects.                                                                                                               |
+| `origin`        | `Origin` header.                                                                                                                                                               |
+| `referer`       | `Referer` header.                                                                                                                                                              |
+| `correlationId` | `x-correlation-id` header.                                                                                                                                                     |
+| `arrLogId`      | `x-arr-log-id` header (Azure Front Door / ARR).                                                                                                                                |
+| `clientIp`      | First value from `x-forwarded-for`, falling back to `socket.remoteAddress`.                                                                                                    |
+| `userAgent`     | `User-Agent` header.                                                                                                                                                           |
 
 You can add more via `augmentRequestInfo(input)`. Lambda deployments also get `functionName` and `awsRequestId` when a `LambdaContext` is supplied.
 
@@ -163,6 +163,112 @@ const graphqlServer = createServer({
 })
 ```
 
+## Shield (authorization)
+
+The `shield` module provides typed helpers around [graphql-shield](https://the-guild.dev/graphql/shield) for defining authorization middleware against your generated `Resolvers` type.
+
+`graphql-shield` is an optional peer dependency — install it only if you use this module:
+
+```sh
+npm i graphql-shield
+```
+
+### createShieldSchema
+
+Builds a shield middleware with a schema typed against your resolver map, so field-level rule wiring is checked by the TypeScript compiler.
+
+```ts
+import { Resolvers } from '../generated/types'
+import { or } from 'graphql-shield'
+import { applyMiddleware } from 'graphql-middleware'
+import { createShieldSchema, hasRoleRule, unauthorisedError } from '@makerx/graphql-core'
+
+const isCoordinator = hasRoleRule('coordinator')
+const isSystemAdmin = hasRoleRule('system-admin')
+const isAuthorisedUser = or(isCoordinator, isSystemAdmin)
+
+const shieldSchema = createShieldSchema<Resolvers>(
+  {
+    Query: {
+      '*': isAuthorisedUser,
+      user: isCoordinator,
+    },
+    Mutation: {
+      '*': isCoordinator,
+      createUser: isSystemAdmin,
+    },
+  },
+  { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError() },
+)
+
+const schema = applyMiddleware(makeExecutableSchema({ ... }), shieldSchema)
+```
+
+The `'*'` key at each object level is a fallback rule applied to any field at that level without an explicit rule.
+
+The wrapper defaults `allowExternalErrors: true`; the full shield options object (second argument) is forwarded to `shield(...)` and can override it.
+
+#### v3 breaking change: no default fallback rule
+
+Prior to v3 this wrapper defaulted `fallbackRule` to `allow` — fields not covered by the schema were open by default. v3 removes that default and the wrapper no longer makes that choice for you. Without an explicit `fallbackRule`, graphql-shield's own default (`allow`) still applies, so behaviour is unchanged when no options are passed, but if you want a deny-by-default posture you should now pass an explicit `fallbackRule` (commonly your auth-check rule) along with a `fallbackError`.
+
+The second argument also changed from a bare `ShieldRule` to the full shield options object:
+
+```ts
+// v2
+createShieldSchema<Resolvers>(schema, isAuthorisedUser)
+
+// v3
+createShieldSchema<Resolvers>(schema, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError() })
+```
+
+### Role and scope rules
+
+Convenience builders that read `ctx.user.roles` / `ctx.user.scopes`. All use graphql-shield's `'contextual'` cache so the result is reused across fields within a request.
+
+| Helper                                   | Description                                                                   |
+| ---------------------------------------- | ----------------------------------------------------------------------------- |
+| `hasRoleRule(role, ruleName?)`           | Passes when `user.roles` includes `role`.                                     |
+| `hasAnyRoleRule(...roles)`               | Passes when `user.roles` includes at least one of `roles`.                    |
+| `hasAnyRoleRuleWithName(name, ...roles)` | Same, with an explicit rule name / cache key for large or dynamic role lists. |
+| `hasScopeRule(scope)`                    | Passes when `user.scopes` includes `scope`.                                   |
+| `hasAnyScopeRule(...scopes)`             | Passes when `user.scopes` includes at least one of `scopes`.                  |
+
+### createRule
+
+Typed wrapper around graphql-shield's `rule(...)` for ad-hoc rules. Unlike the underlying `rule`, `createRule` types `parent`, `args` and `ctx` to your generics.
+
+```ts
+const isOwner = createRule<GraphQLContext, Record, { ownerId: string }>((parent, _, ctx) => parent.ownerId === ctx.user?.id)
+```
+
+Defaults to `'strict'` cache; pass `'contextual'` as the second argument for rules whose result depends only on `ctx`.
+
+### combineRuleWithAll
+
+Composes a rule with every rule in an existing shield schema via a combinator (`and` | `or` | `chain` | `race`). Useful for post-hoc gating — e.g. bolting a "not blocked" check onto an existing schema without touching each field:
+
+```ts
+import { chain } from 'graphql-shield'
+
+const gated = combineRuleWithAll(shieldSchema, accountNotBlocked, chain)
+```
+
+### Authorization errors
+
+The `unauthorised` module provides shared helpers for producing forbidden errors used by the shield wrapper and by resolvers.
+
+| Helper                                     | Description                                                                                             |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `unauthorisedError(message?)`              | Builds a `GraphQLError` with Apollo's `FORBIDDEN` extension code and HTTP 403 status.                   |
+| `throwUnauthorised(message?)`              | Throws `unauthorisedError`; return type is `never` so TypeScript narrows control flow past the call.    |
+| `permissionInvariant(condition, message?)` | Assertion helper: throws `unauthorisedError` when `condition` is false, otherwise narrows it to `true`. |
+
+```ts
+permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')
+// past this line, TypeScript knows the condition held
+```
+
 ## Logging
 
 ### logGraphQLOperation
@@ -223,7 +329,6 @@ This library includes a `subscriptions` module to provide simple setup using the
 1. Create a subscriptions server, using the ws-server cleanup function in your server lifecycle.
 
    The `useSubscriptionsServer` function sets up:
-
    - Auth token validation as part of establishing (or rejecting) the connection (behaviour defined by `verifyToken` and `requireAuth` args)
    - GraphQL context creation
    - Logging from the server `onConnect`, `onDisconnect`, `onOperation`, `onNext` and `onError` callbacks

package/index.d.ts

@@ -3,5 +3,6 @@ export * from './logging';
 export * from './request-info';
 export * from './schema-util';
 export * from './type-utils';
+export * from './unauthorised';
 export * from './User';
 export * from './utils';

package/index.js

@@ -4,6 +4,7 @@ var context = require('./context.js');
 var logging = require('./logging.js');
 var requestInfo = require('./request-info.js');
 var schemaUtil = require('./schema-util.js');
+var unauthorised = require('./unauthorised.js');
 var User = require('./User.js');
 var utils = require('./utils.js');
 
@@ -18,6 +19,9 @@ exports.buildConnectRequestInfo = requestInfo.buildConnectRequestInfo;
 exports.connectRequestBaseUrl = requestInfo.connectRequestBaseUrl;
 exports.requestBaseUrl = requestInfo.requestBaseUrl;
 exports.requireExplicitResolversForScalars = schemaUtil.requireExplicitResolversForScalars;
+exports.permissionInvariant = unauthorised.permissionInvariant;
+exports.throwUnauthorised = unauthorised.throwUnauthorised;
+exports.unauthorisedError = unauthorised.unauthorisedError;
 exports.User = User.User;
 exports.isIntrospectionQuery = utils.isIntrospectionQuery;
 exports.isNil = utils.isNil;

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;"}
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;"}

package/index.mjs

@@ -2,6 +2,7 @@ export { createContextFactory, defaultCreateUser } from './context.mjs';
 export { logGraphQLOperation, logSubscriptionOperation } from './logging.mjs';
 export { buildBaseRequestInfo, buildConnectRequestInfo, connectRequestBaseUrl, requestBaseUrl } from './request-info.mjs';
 export { requireExplicitResolversForScalars } from './schema-util.mjs';
+export { permissionInvariant, throwUnauthorised, unauthorisedError } from './unauthorised.mjs';
 export { User } from './User.mjs';
 export { isIntrospectionQuery, isNil, isNotNil } from './utils.mjs';
 //# sourceMappingURL=index.mjs.map

package/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;"}
+{"version":3,"file":"index.mjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;"}

package/package.json

@@ -4,7 +4,7 @@
     "**"
   ],
   "name": "@makerx/graphql-core",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.3",
   "private": false,
   "description": "A set of core GraphQL utilities that MakerX uses to build GraphQL APIs",
   "author": "MakerX",
@@ -20,18 +20,19 @@
     "type": "git",
     "url": "git+https://github.com/MakerXStudio/graphql-core.git"
   },
-  "dependencies": {
-    "@makerx/node-common": "^1.5.0"
-  },
   "peerDependencies": {
+    "@makerx/node-common": ">=1",
     "es-toolkit": ">=1",
-    "express": "*",
-    "graphql": "*",
-    "graphql-shield": "*",
-    "graphql-ws": "*",
-    "ws": "*"
+    "express": ">=4",
+    "graphql": ">=16",
+    "graphql-shield": ">=7",
+    "graphql-ws": ">=5",
+    "ws": ">=8"
   },
   "peerDependenciesMeta": {
+    "graphql-shield": {
+      "optional": true
+    },
     "graphql-ws": {
       "optional": true
     },

package/shield.js

@@ -2,6 +2,25 @@
 
 var graphqlShield = require('graphql-shield');
 
+/**
+ * Thin typed wrapper around graphql-shield's `rule(...)` for building ad-hoc shield rules.
+ *
+ * Lets you pass a plain predicate (sync or async, or returning an `Error`) and get back a
+ * {@link ShieldRule} with the `parent`, `args`, and `ctx` arguments typed to your generics —
+ * graphql-shield's native `rule` types these as `any`.
+ *
+ * Defaults the rule's cache to `'strict'`; use `'contextual'` when the result depends only on
+ * `ctx` (e.g. the current user), so it can be reused across fields in the same request.
+ *
+ * @param logic Predicate returning `true` to allow, `false` to deny, or an `Error` to deny with a specific error.
+ * @param cache graphql-shield cache strategy. `'strict'` (default) keys on parent+args+ctx; `'contextual'` keys on ctx only.
+ *
+ * Usage:
+ *
+ * const isOwner = createRule<GraphQLContext, { ownerId: string }>(
+ *   (parent, _, ctx) => parent.ownerId === ctx.user?.id,
+ * )
+ */
 const createRule = (logic, cache = 'strict') => graphqlShield.rule({ cache })(async (parent, args, ctx) => logic(parent, args, ctx));
 /**
  * Combines a given rule with all existing defined rules using the provided combinator
@@ -24,30 +43,88 @@ function combineRuleWithAll(schema, rule, combinator) {
 /**
  * Creates graphql shield middleware making use of generics to type the definition of the rules.
  * @param schema A mapping of schema objects to the shield rules that define the access to that object
- * @param fallbackRule A fallback rule to apply to any object or property which doesn't have a defined rule.
+ * @param options Shield options forwarded to `shield`. Defaults `allowExternalErrors` to `true`.
  *
  * Usage:
  * import { Resolvers } from '../generated/types'
  *
+ * const isCoordinator = hasRoleRule(UserRoles.Coordinator)
+ * const isSystemAdmin = hasRoleRule(UserRoles.SystemAdmin)
+ * const isQualityAssurance = hasRoleRule(UserRoles.QualityAssurance)
+ *
+ * const isAuthorisedUser = or(isCoordinator, isSystemAdmin, isQualityAssurance)
+ * const isDataAuthor = or(isCoordinator, isSystemAdmin)
+ *
  * const shieldSchema = createShieldSchema<Resolvers>({
  *   Query: {
- *     getThings: allow,
- *     dontGetThings: deny,
- *   }
- * })
- *
- * let schema = makeExecutableSchema({...})
+ *     '*': isAuthorisedUser,
+ *     user: isCoordinator,
+ *     findUsers: isCoordinator,
+ *   },
+ *   Mutation: {
+ *     '*': isDataAuthor,
+ *     createUser: isCoordinator,
+ *   },
+ *   // specific rules for mutations, types, fields...
+ * }, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError()})
  *
- * schema = applyMiddleware(schema, shieldSchema)
+ * const unprotected = makeExecutableSchema({...})
+ * return applyMiddleware(unprotected, shieldSchema)
  */
-function createShieldSchema(schema, fallbackRule = graphqlShield.allow) {
+function createShieldSchema(schema, options) {
     return graphqlShield.shield(schema, {
         allowExternalErrors: true,
-        fallbackRule: fallbackRule,
+        ...options,
     });
 }
+/**
+ * Shield rule that passes when the current user has the given role.
+ * @param role The role the user must have on `ctx.user.roles`.
+ * @param ruleName Optional override for the rule's cache key. Defaults to `hasRole-${role}`.
+ */
+function hasRoleRule(role, ruleName) {
+    return graphqlShield.rule(ruleName ?? `hasRole-${role}`, { cache: 'contextual' })((_, __, { user }) => user?.roles.includes(role) === true);
+}
+/**
+ * Shield rule that passes when the current user has at least one of the given roles.
+ * Rule name is derived from the roles; use {@link hasAnyRoleRuleWithName} to supply your own.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+function hasAnyRoleRule(...roles) {
+    return hasAnyRoleRuleWithName(`hasAnyRole-${roles.join(',')}`, ...roles);
+}
+/**
+ * Shield rule that passes when the current user has at least one of the given roles, with an explicit rule name.
+ * Prefer this over {@link hasAnyRoleRule} when the role list is large or dynamic and you want a stable cache key.
+ * @param ruleName The name (and cache key) for the rule.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+function hasAnyRoleRuleWithName(ruleName, ...roles) {
+    return graphqlShield.rule(ruleName, { cache: 'contextual' })((_, __, { user }) => {
+        return user?.roles.some((role) => roles.includes(role)) === true;
+    });
+}
+/**
+ * Shield rule that passes when the current user has the given scope.
+ * @param scope The scope the user must have on `ctx.user.scopes`.
+ */
+function hasScopeRule(scope) {
+    return graphqlShield.rule(`hasScope-${scope}`, { cache: 'contextual' })((_, __, { user }) => user?.scopes.includes(scope) === true);
+}
+/**
+ * Shield rule that passes when the current user has at least one of the given scopes.
+ * @param scopes The set of scopes, any of which satisfies the rule.
+ */
+function hasAnyScopeRule(...scopes) {
+    return graphqlShield.rule(`hasAnyScope-${scopes.join(',')}`, { cache: 'contextual' })((_, __, { user }) => user?.scopes.some((scope) => scopes.includes(scope)) === true);
+}
 
 exports.combineRuleWithAll = combineRuleWithAll;
 exports.createRule = createRule;
 exports.createShieldSchema = createShieldSchema;
+exports.hasAnyRoleRule = hasAnyRoleRule;
+exports.hasAnyRoleRuleWithName = hasAnyRoleRuleWithName;
+exports.hasAnyScopeRule = hasAnyScopeRule;
+exports.hasRoleRule = hasRoleRule;
+exports.hasScopeRule = hasScopeRule;
 //# sourceMappingURL=shield.js.map

package/shield.js.map

@@ -1 +1 @@
-{"version":3,"file":"shield.js","sources":["../src/shield.ts"],"sourcesContent":["import type { and, chain, IRules, or, race } from 'graphql-shield'\nimport { allow, rule, shield } from 'graphql-shield'\nimport type { Primitive } from './type-utils'\n\ntype RuleCombinator = typeof chain | typeof race | typeof or | typeof and\n// For whatever reason, graphql-shield doesn't export this type, but we can extract if from\n// what it does export.\nexport type ShieldRule = ReturnType<(typeof allow)['getRules']>[number]\nexport const createRule = <TContext, TParent = unknown, TArgs = unknown>(\n  logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error,\n  cache: 'contextual' | 'strict' = 'strict',\n): ShieldRule => rule({ cache })(async (parent, args, ctx) => logic(parent, args, ctx))\n\n/**\n * Combines a given rule with all existing defined rules using the provided combinator\n * @param schema The existing shield schema with rules\n * @param rule The rule to be combined with existing rules\n * @param combinator The combinator to use. Eg. and | or | chain | race\n *\n * Usage:\n *\n * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)\n */\nexport function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T> {\n  return Object.fromEntries(\n    Object.entries(schema).map(([key, value]) => {\n      if (value.constructor.name !== 'Object') {\n        return [key, combinator(rule, value)]\n      }\n      return [key, combineRuleWithAll(value, rule, combinator)]\n    }),\n  ) as ShieldSchema<T>\n}\n\n/**\n * Creates graphql shield middleware making use of generics to type the definition of the rules.\n * @param schema A mapping of schema objects to the shield rules that define the access to that object\n * @param fallbackRule A fallback rule to apply to any object or property which doesn't have a defined rule.\n *\n * Usage:\n * import { Resolvers } from '../generated/types'\n *\n * const shieldSchema = createShieldSchema<Resolvers>({\n *   Query: {\n *     getThings: allow,\n *     dontGetThings: deny,\n *   }\n * })\n *\n * let schema = makeExecutableSchema({...})\n *\n * schema = applyMiddleware(schema, shieldSchema)\n */\nexport function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, fallbackRule: ShieldRule = allow) {\n  return shield(schema as IRules, {\n    allowExternalErrors: true,\n    fallbackRule: fallbackRule,\n  })\n}\n\nexport type ShieldSchema<TResolver> = TResolver extends Primitive\n  ? ShieldRule\n  : {\n      [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule\n    } & {\n      '*'?: ShieldRule\n    }\n"],"names":["rule","allow","shield"],"mappings":";;;;AAQO,MAAM,UAAU,GAAG,CACxB,KAA0F,EAC1F,KAAA,GAAiC,QAAQ,KAC1BA,kBAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC;AAEtF;;;;;;;;;AASG;SACa,kBAAkB,CAAI,MAAuB,EAAE,IAAgB,EAAE,UAA0B,EAAA;IACzG,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,KAAI;QAC1C,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ,EAAE;YACvC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC;AACA,QAAA,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAC3D,CAAC,CAAC,CACgB;AACtB;AAEA;;;;;;;;;;;;;;;;;;AAkBG;SACa,kBAAkB,CAAiB,MAAoC,EAAE,eAA2BC,mBAAK,EAAA;IACvH,OAAOC,oBAAM,CAAC,MAAgB,EAAE;AAC9B,QAAA,mBAAmB,EAAE,IAAI;AACzB,QAAA,YAAY,EAAE,YAAY;AAC3B,KAAA,CAAC;AACJ;;;;;;"}
+{"version":3,"file":"shield.js","sources":["../src/shield.ts"],"sourcesContent":["import type { allow, and, chain, IRules, or, race } from 'graphql-shield'\nimport { rule, shield } from 'graphql-shield'\nimport type { GraphQLContext } from './context'\nimport type { Primitive } from './type-utils'\n\nexport type ShieldOptions = NonNullable<Parameters<typeof shield>[1]>\n\ntype RuleCombinator = typeof chain | typeof race | typeof or | typeof and\n// For whatever reason, graphql-shield doesn't export this type, but we can extract if from\n// what it does export.\nexport type ShieldRule = ReturnType<(typeof allow)['getRules']>[number]\n\n/**\n * Thin typed wrapper around graphql-shield's `rule(...)` for building ad-hoc shield rules.\n *\n * Lets you pass a plain predicate (sync or async, or returning an `Error`) and get back a\n * {@link ShieldRule} with the `parent`, `args`, and `ctx` arguments typed to your generics —\n * graphql-shield's native `rule` types these as `any`.\n *\n * Defaults the rule's cache to `'strict'`; use `'contextual'` when the result depends only on\n * `ctx` (e.g. the current user), so it can be reused across fields in the same request.\n *\n * @param logic Predicate returning `true` to allow, `false` to deny, or an `Error` to deny with a specific error.\n * @param cache graphql-shield cache strategy. `'strict'` (default) keys on parent+args+ctx; `'contextual'` keys on ctx only.\n *\n * Usage:\n *\n * const isOwner = createRule<GraphQLContext, { ownerId: string }>(\n *   (parent, _, ctx) => parent.ownerId === ctx.user?.id,\n * )\n */\nexport const createRule = <TContext, TParent = unknown, TArgs = unknown>(\n  logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error,\n  cache: 'contextual' | 'strict' = 'strict',\n): ShieldRule => rule({ cache })(async (parent, args, ctx) => logic(parent, args, ctx))\n\n/**\n * Combines a given rule with all existing defined rules using the provided combinator\n * @param schema The existing shield schema with rules\n * @param rule The rule to be combined with existing rules\n * @param combinator The combinator to use. Eg. and | or | chain | race\n *\n * Usage:\n *\n * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)\n */\nexport function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T> {\n  return Object.fromEntries(\n    Object.entries(schema).map(([key, value]) => {\n      if (value.constructor.name !== 'Object') {\n        return [key, combinator(rule, value)]\n      }\n      return [key, combineRuleWithAll(value, rule, combinator)]\n    }),\n  ) as ShieldSchema<T>\n}\n\n/**\n * Creates graphql shield middleware making use of generics to type the definition of the rules.\n * @param schema A mapping of schema objects to the shield rules that define the access to that object\n * @param options Shield options forwarded to `shield`. Defaults `allowExternalErrors` to `true`.\n *\n * Usage:\n * import { Resolvers } from '../generated/types'\n *\n * const isCoordinator = hasRoleRule(UserRoles.Coordinator)\n * const isSystemAdmin = hasRoleRule(UserRoles.SystemAdmin)\n * const isQualityAssurance = hasRoleRule(UserRoles.QualityAssurance)\n *\n * const isAuthorisedUser = or(isCoordinator, isSystemAdmin, isQualityAssurance)\n * const isDataAuthor = or(isCoordinator, isSystemAdmin)\n *\n * const shieldSchema = createShieldSchema<Resolvers>({\n *   Query: {\n *     '*': isAuthorisedUser,\n *     user: isCoordinator,\n *     findUsers: isCoordinator,\n *   },\n *   Mutation: {\n *     '*': isDataAuthor,\n *     createUser: isCoordinator,\n *   },\n *   // specific rules for mutations, types, fields...\n * }, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError()})\n *\n * const unprotected = makeExecutableSchema({...})\n * return applyMiddleware(unprotected, shieldSchema)\n */\nexport function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, options?: ShieldOptions) {\n  return shield(schema as IRules, {\n    allowExternalErrors: true,\n    ...options,\n  })\n}\n\n/**\n * A shield rule tree typed against a resolver map (typically your generated `Resolvers` type).\n *\n * Mirrors the shape of `TResolver` so each type/field can be assigned a {@link ShieldRule}.\n * Object levels may also include a `'*'` key — a fallback rule applied to any field at that\n * level that doesn't have an explicit rule. Leaf (primitive) positions collapse to a single\n * {@link ShieldRule}.\n *\n * Usage:\n *\n * const schema: ShieldSchema<Resolvers> = {\n *   Query: {\n *     '*': isAuthorisedUser,\n *     publicThing: allow,\n *   },\n *   Mutation: { createUser: isCoordinator },\n * }\n */\nexport type ShieldSchema<TResolver> = TResolver extends Primitive\n  ? ShieldRule\n  : {\n      [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule\n    } & {\n      '*'?: ShieldRule\n    }\n\n/**\n * Shield rule that passes when the current user has the given role.\n * @param role The role the user must have on `ctx.user.roles`.\n * @param ruleName Optional override for the rule's cache key. Defaults to `hasRole-${role}`.\n */\nexport function hasRoleRule(role: string, ruleName?: string) {\n  return rule(ruleName ?? `hasRole-${role}`, { cache: 'contextual' })(\n    (_, __, { user }: GraphQLContext) => user?.roles.includes(role) === true,\n  )\n}\n\n/**\n * Shield rule that passes when the current user has at least one of the given roles.\n * Rule name is derived from the roles; use {@link hasAnyRoleRuleWithName} to supply your own.\n * @param roles The set of roles, any of which satisfies the rule.\n */\nexport function hasAnyRoleRule(...roles: string[]) {\n  return hasAnyRoleRuleWithName(`hasAnyRole-${roles.join(',')}`, ...roles)\n}\n\n/**\n * Shield rule that passes when the current user has at least one of the given roles, with an explicit rule name.\n * Prefer this over {@link hasAnyRoleRule} when the role list is large or dynamic and you want a stable cache key.\n * @param ruleName The name (and cache key) for the rule.\n * @param roles The set of roles, any of which satisfies the rule.\n */\nexport function hasAnyRoleRuleWithName(ruleName: string, ...roles: string[]) {\n  return rule(ruleName, { cache: 'contextual' })((_, __, { user }: GraphQLContext) => {\n    return user?.roles.some((role: string) => roles.includes(role)) === true\n  })\n}\n\n/**\n * Shield rule that passes when the current user has the given scope.\n * @param scope The scope the user must have on `ctx.user.scopes`.\n */\nexport function hasScopeRule(scope: string) {\n  return rule(`hasScope-${scope}`, { cache: 'contextual' })((_, __, { user }: GraphQLContext) => user?.scopes.includes(scope) === true)\n}\n\n/**\n * Shield rule that passes when the current user has at least one of the given scopes.\n * @param scopes The set of scopes, any of which satisfies the rule.\n */\nexport function hasAnyScopeRule(...scopes: string[]) {\n  return rule(`hasAnyScope-${scopes.join(',')}`, { cache: 'contextual' })(\n    (_, __, { user }: GraphQLContext) => user?.scopes.some((scope: string) => scopes.includes(scope)) === true,\n  )\n}\n"],"names":["rule","shield"],"mappings":"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"}

package/shield.mjs

@@ -1,5 +1,24 @@
-import { allow, rule, shield } from 'graphql-shield';
+import { rule, shield } from 'graphql-shield';
 
+/**
+ * Thin typed wrapper around graphql-shield's `rule(...)` for building ad-hoc shield rules.
+ *
+ * Lets you pass a plain predicate (sync or async, or returning an `Error`) and get back a
+ * {@link ShieldRule} with the `parent`, `args`, and `ctx` arguments typed to your generics —
+ * graphql-shield's native `rule` types these as `any`.
+ *
+ * Defaults the rule's cache to `'strict'`; use `'contextual'` when the result depends only on
+ * `ctx` (e.g. the current user), so it can be reused across fields in the same request.
+ *
+ * @param logic Predicate returning `true` to allow, `false` to deny, or an `Error` to deny with a specific error.
+ * @param cache graphql-shield cache strategy. `'strict'` (default) keys on parent+args+ctx; `'contextual'` keys on ctx only.
+ *
+ * Usage:
+ *
+ * const isOwner = createRule<GraphQLContext, { ownerId: string }>(
+ *   (parent, _, ctx) => parent.ownerId === ctx.user?.id,
+ * )
+ */
 const createRule = (logic, cache = 'strict') => rule({ cache })(async (parent, args, ctx) => logic(parent, args, ctx));
 /**
  * Combines a given rule with all existing defined rules using the provided combinator
@@ -22,28 +41,81 @@ function combineRuleWithAll(schema, rule, combinator) {
 /**
  * Creates graphql shield middleware making use of generics to type the definition of the rules.
  * @param schema A mapping of schema objects to the shield rules that define the access to that object
- * @param fallbackRule A fallback rule to apply to any object or property which doesn't have a defined rule.
+ * @param options Shield options forwarded to `shield`. Defaults `allowExternalErrors` to `true`.
  *
  * Usage:
  * import { Resolvers } from '../generated/types'
  *
+ * const isCoordinator = hasRoleRule(UserRoles.Coordinator)
+ * const isSystemAdmin = hasRoleRule(UserRoles.SystemAdmin)
+ * const isQualityAssurance = hasRoleRule(UserRoles.QualityAssurance)
+ *
+ * const isAuthorisedUser = or(isCoordinator, isSystemAdmin, isQualityAssurance)
+ * const isDataAuthor = or(isCoordinator, isSystemAdmin)
+ *
  * const shieldSchema = createShieldSchema<Resolvers>({
  *   Query: {
- *     getThings: allow,
- *     dontGetThings: deny,
- *   }
- * })
- *
- * let schema = makeExecutableSchema({...})
+ *     '*': isAuthorisedUser,
+ *     user: isCoordinator,
+ *     findUsers: isCoordinator,
+ *   },
+ *   Mutation: {
+ *     '*': isDataAuthor,
+ *     createUser: isCoordinator,
+ *   },
+ *   // specific rules for mutations, types, fields...
+ * }, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError()})
  *
- * schema = applyMiddleware(schema, shieldSchema)
+ * const unprotected = makeExecutableSchema({...})
+ * return applyMiddleware(unprotected, shieldSchema)
  */
-function createShieldSchema(schema, fallbackRule = allow) {
+function createShieldSchema(schema, options) {
     return shield(schema, {
         allowExternalErrors: true,
-        fallbackRule: fallbackRule,
+        ...options,
     });
 }
+/**
+ * Shield rule that passes when the current user has the given role.
+ * @param role The role the user must have on `ctx.user.roles`.
+ * @param ruleName Optional override for the rule's cache key. Defaults to `hasRole-${role}`.
+ */
+function hasRoleRule(role, ruleName) {
+    return rule(ruleName ?? `hasRole-${role}`, { cache: 'contextual' })((_, __, { user }) => user?.roles.includes(role) === true);
+}
+/**
+ * Shield rule that passes when the current user has at least one of the given roles.
+ * Rule name is derived from the roles; use {@link hasAnyRoleRuleWithName} to supply your own.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+function hasAnyRoleRule(...roles) {
+    return hasAnyRoleRuleWithName(`hasAnyRole-${roles.join(',')}`, ...roles);
+}
+/**
+ * Shield rule that passes when the current user has at least one of the given roles, with an explicit rule name.
+ * Prefer this over {@link hasAnyRoleRule} when the role list is large or dynamic and you want a stable cache key.
+ * @param ruleName The name (and cache key) for the rule.
+ * @param roles The set of roles, any of which satisfies the rule.
+ */
+function hasAnyRoleRuleWithName(ruleName, ...roles) {
+    return rule(ruleName, { cache: 'contextual' })((_, __, { user }) => {
+        return user?.roles.some((role) => roles.includes(role)) === true;
+    });
+}
+/**
+ * Shield rule that passes when the current user has the given scope.
+ * @param scope The scope the user must have on `ctx.user.scopes`.
+ */
+function hasScopeRule(scope) {
+    return rule(`hasScope-${scope}`, { cache: 'contextual' })((_, __, { user }) => user?.scopes.includes(scope) === true);
+}
+/**
+ * Shield rule that passes when the current user has at least one of the given scopes.
+ * @param scopes The set of scopes, any of which satisfies the rule.
+ */
+function hasAnyScopeRule(...scopes) {
+    return rule(`hasAnyScope-${scopes.join(',')}`, { cache: 'contextual' })((_, __, { user }) => user?.scopes.some((scope) => scopes.includes(scope)) === true);
+}
 
-export { combineRuleWithAll, createRule, createShieldSchema };
+export { combineRuleWithAll, createRule, createShieldSchema, hasAnyRoleRule, hasAnyRoleRuleWithName, hasAnyScopeRule, hasRoleRule, hasScopeRule };
 //# sourceMappingURL=shield.mjs.map

package/shield.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"shield.mjs","sources":["../src/shield.ts"],"sourcesContent":["import type { and, chain, IRules, or, race } from 'graphql-shield'\nimport { allow, rule, shield } from 'graphql-shield'\nimport type { Primitive } from './type-utils'\n\ntype RuleCombinator = typeof chain | typeof race | typeof or | typeof and\n// For whatever reason, graphql-shield doesn't export this type, but we can extract if from\n// what it does export.\nexport type ShieldRule = ReturnType<(typeof allow)['getRules']>[number]\nexport const createRule = <TContext, TParent = unknown, TArgs = unknown>(\n  logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error,\n  cache: 'contextual' | 'strict' = 'strict',\n): ShieldRule => rule({ cache })(async (parent, args, ctx) => logic(parent, args, ctx))\n\n/**\n * Combines a given rule with all existing defined rules using the provided combinator\n * @param schema The existing shield schema with rules\n * @param rule The rule to be combined with existing rules\n * @param combinator The combinator to use. Eg. and | or | chain | race\n *\n * Usage:\n *\n * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)\n */\nexport function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T> {\n  return Object.fromEntries(\n    Object.entries(schema).map(([key, value]) => {\n      if (value.constructor.name !== 'Object') {\n        return [key, combinator(rule, value)]\n      }\n      return [key, combineRuleWithAll(value, rule, combinator)]\n    }),\n  ) as ShieldSchema<T>\n}\n\n/**\n * Creates graphql shield middleware making use of generics to type the definition of the rules.\n * @param schema A mapping of schema objects to the shield rules that define the access to that object\n * @param fallbackRule A fallback rule to apply to any object or property which doesn't have a defined rule.\n *\n * Usage:\n * import { Resolvers } from '../generated/types'\n *\n * const shieldSchema = createShieldSchema<Resolvers>({\n *   Query: {\n *     getThings: allow,\n *     dontGetThings: deny,\n *   }\n * })\n *\n * let schema = makeExecutableSchema({...})\n *\n * schema = applyMiddleware(schema, shieldSchema)\n */\nexport function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, fallbackRule: ShieldRule = allow) {\n  return shield(schema as IRules, {\n    allowExternalErrors: true,\n    fallbackRule: fallbackRule,\n  })\n}\n\nexport type ShieldSchema<TResolver> = TResolver extends Primitive\n  ? ShieldRule\n  : {\n      [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule\n    } & {\n      '*'?: ShieldRule\n    }\n"],"names":[],"mappings":";;AAQO,MAAM,UAAU,GAAG,CACxB,KAA0F,EAC1F,KAAA,GAAiC,QAAQ,KAC1B,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,OAAO,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC;AAEtF;;;;;;;;;AASG;SACa,kBAAkB,CAAI,MAAuB,EAAE,IAAgB,EAAE,UAA0B,EAAA;IACzG,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,KAAI;QAC1C,IAAI,KAAK,CAAC,WAAW,CAAC,IAAI,KAAK,QAAQ,EAAE;YACvC,OAAO,CAAC,GAAG,EAAE,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACvC;AACA,QAAA,OAAO,CAAC,GAAG,EAAE,kBAAkB,CAAC,KAAK,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC;IAC3D,CAAC,CAAC,CACgB;AACtB;AAEA;;;;;;;;;;;;;;;;;;AAkBG;SACa,kBAAkB,CAAiB,MAAoC,EAAE,eAA2B,KAAK,EAAA;IACvH,OAAO,MAAM,CAAC,MAAgB,EAAE;AAC9B,QAAA,mBAAmB,EAAE,IAAI;AACzB,QAAA,YAAY,EAAE,YAAY;AAC3B,KAAA,CAAC;AACJ;;;;"}
+{"version":3,"file":"shield.mjs","sources":["../src/shield.ts"],"sourcesContent":["import type { allow, and, chain, IRules, or, race } from 'graphql-shield'\nimport { rule, shield } from 'graphql-shield'\nimport type { GraphQLContext } from './context'\nimport type { Primitive } from './type-utils'\n\nexport type ShieldOptions = NonNullable<Parameters<typeof shield>[1]>\n\ntype RuleCombinator = typeof chain | typeof race | typeof or | typeof and\n// For whatever reason, graphql-shield doesn't export this type, but we can extract if from\n// what it does export.\nexport type ShieldRule = ReturnType<(typeof allow)['getRules']>[number]\n\n/**\n * Thin typed wrapper around graphql-shield's `rule(...)` for building ad-hoc shield rules.\n *\n * Lets you pass a plain predicate (sync or async, or returning an `Error`) and get back a\n * {@link ShieldRule} with the `parent`, `args`, and `ctx` arguments typed to your generics —\n * graphql-shield's native `rule` types these as `any`.\n *\n * Defaults the rule's cache to `'strict'`; use `'contextual'` when the result depends only on\n * `ctx` (e.g. the current user), so it can be reused across fields in the same request.\n *\n * @param logic Predicate returning `true` to allow, `false` to deny, or an `Error` to deny with a specific error.\n * @param cache graphql-shield cache strategy. `'strict'` (default) keys on parent+args+ctx; `'contextual'` keys on ctx only.\n *\n * Usage:\n *\n * const isOwner = createRule<GraphQLContext, { ownerId: string }>(\n *   (parent, _, ctx) => parent.ownerId === ctx.user?.id,\n * )\n */\nexport const createRule = <TContext, TParent = unknown, TArgs = unknown>(\n  logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error,\n  cache: 'contextual' | 'strict' = 'strict',\n): ShieldRule => rule({ cache })(async (parent, args, ctx) => logic(parent, args, ctx))\n\n/**\n * Combines a given rule with all existing defined rules using the provided combinator\n * @param schema The existing shield schema with rules\n * @param rule The rule to be combined with existing rules\n * @param combinator The combinator to use. Eg. and | or | chain | race\n *\n * Usage:\n *\n * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)\n */\nexport function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T> {\n  return Object.fromEntries(\n    Object.entries(schema).map(([key, value]) => {\n      if (value.constructor.name !== 'Object') {\n        return [key, combinator(rule, value)]\n      }\n      return [key, combineRuleWithAll(value, rule, combinator)]\n    }),\n  ) as ShieldSchema<T>\n}\n\n/**\n * Creates graphql shield middleware making use of generics to type the definition of the rules.\n * @param schema A mapping of schema objects to the shield rules that define the access to that object\n * @param options Shield options forwarded to `shield`. Defaults `allowExternalErrors` to `true`.\n *\n * Usage:\n * import { Resolvers } from '../generated/types'\n *\n * const isCoordinator = hasRoleRule(UserRoles.Coordinator)\n * const isSystemAdmin = hasRoleRule(UserRoles.SystemAdmin)\n * const isQualityAssurance = hasRoleRule(UserRoles.QualityAssurance)\n *\n * const isAuthorisedUser = or(isCoordinator, isSystemAdmin, isQualityAssurance)\n * const isDataAuthor = or(isCoordinator, isSystemAdmin)\n *\n * const shieldSchema = createShieldSchema<Resolvers>({\n *   Query: {\n *     '*': isAuthorisedUser,\n *     user: isCoordinator,\n *     findUsers: isCoordinator,\n *   },\n *   Mutation: {\n *     '*': isDataAuthor,\n *     createUser: isCoordinator,\n *   },\n *   // specific rules for mutations, types, fields...\n * }, { fallbackRule: isAuthorisedUser, fallbackError: unauthorisedError()})\n *\n * const unprotected = makeExecutableSchema({...})\n * return applyMiddleware(unprotected, shieldSchema)\n */\nexport function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, options?: ShieldOptions) {\n  return shield(schema as IRules, {\n    allowExternalErrors: true,\n    ...options,\n  })\n}\n\n/**\n * A shield rule tree typed against a resolver map (typically your generated `Resolvers` type).\n *\n * Mirrors the shape of `TResolver` so each type/field can be assigned a {@link ShieldRule}.\n * Object levels may also include a `'*'` key — a fallback rule applied to any field at that\n * level that doesn't have an explicit rule. Leaf (primitive) positions collapse to a single\n * {@link ShieldRule}.\n *\n * Usage:\n *\n * const schema: ShieldSchema<Resolvers> = {\n *   Query: {\n *     '*': isAuthorisedUser,\n *     publicThing: allow,\n *   },\n *   Mutation: { createUser: isCoordinator },\n * }\n */\nexport type ShieldSchema<TResolver> = TResolver extends Primitive\n  ? ShieldRule\n  : {\n      [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule\n    } & {\n      '*'?: ShieldRule\n    }\n\n/**\n * Shield rule that passes when the current user has the given role.\n * @param role The role the user must have on `ctx.user.roles`.\n * @param ruleName Optional override for the rule's cache key. Defaults to `hasRole-${role}`.\n */\nexport function hasRoleRule(role: string, ruleName?: string) {\n  return rule(ruleName ?? `hasRole-${role}`, { cache: 'contextual' })(\n    (_, __, { user }: GraphQLContext) => user?.roles.includes(role) === true,\n  )\n}\n\n/**\n * Shield rule that passes when the current user has at least one of the given roles.\n * Rule name is derived from the roles; use {@link hasAnyRoleRuleWithName} to supply your own.\n * @param roles The set of roles, any of which satisfies the rule.\n */\nexport function hasAnyRoleRule(...roles: string[]) {\n  return hasAnyRoleRuleWithName(`hasAnyRole-${roles.join(',')}`, ...roles)\n}\n\n/**\n * Shield rule that passes when the current user has at least one of the given roles, with an explicit rule name.\n * Prefer this over {@link hasAnyRoleRule} when the role list is large or dynamic and you want a stable cache key.\n * @param ruleName The name (and cache key) for the rule.\n * @param roles The set of roles, any of which satisfies the rule.\n */\nexport function hasAnyRoleRuleWithName(ruleName: string, ...roles: string[]) {\n  return rule(ruleName, { cache: 'contextual' })((_, __, { user }: GraphQLContext) => {\n    return user?.roles.some((role: string) => roles.includes(role)) === true\n  })\n}\n\n/**\n * Shield rule that passes when the current user has the given scope.\n * @param scope The scope the user must have on `ctx.user.scopes`.\n */\nexport function hasScopeRule(scope: string) {\n  return rule(`hasScope-${scope}`, { cache: 'contextual' })((_, __, { user }: GraphQLContext) => user?.scopes.includes(scope) === true)\n}\n\n/**\n * Shield rule that passes when the current user has at least one of the given scopes.\n * @param scopes The set of scopes, any of which satisfies the rule.\n */\nexport function hasAnyScopeRule(...scopes: string[]) {\n  return rule(`hasAnyScope-${scopes.join(',')}`, { cache: 'contextual' })(\n    (_, __, { user }: GraphQLContext) => user?.scopes.some((scope: string) => scopes.includes(scope)) === true,\n  )\n}\n"],"names":[],"mappings":"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"}

package/unauthorised.d.ts

@@ -0,0 +1,30 @@
+import { GraphQLError } from 'graphql';
+/**
+ * Builds a `GraphQLError` representing an authorization failure.
+ *
+ * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and
+ * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.
+ *
+ * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.
+ */
+export declare const unauthorisedError: (message?: string) => GraphQLError;
+/**
+ * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.
+ * @param message Optional override for the error message.
+ */
+export declare function throwUnauthorised(message?: string): never;
+/**
+ * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.
+ *
+ * Use at the top of resolvers or services to fail fast on authorization checks while keeping
+ * the happy path unindented.
+ *
+ * @param hasPermission Boolean guard; the function returns normally only when this is `true`.
+ * @param message Optional override for the error message thrown on failure.
+ *
+ * Usage:
+ *
+ * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')
+ * // past this line, TypeScript knows the condition held
+ */
+export declare function permissionInvariant(hasPermission: boolean, message?: string): asserts hasPermission;

package/unauthorised.js

@@ -0,0 +1,45 @@
+'use strict';
+
+var graphql = require('graphql');
+
+/**
+ * Builds a `GraphQLError` representing an authorization failure.
+ *
+ * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and
+ * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.
+ *
+ * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.
+ */
+const unauthorisedError = (message = 'Not Authorized!') => new graphql.GraphQLError(message, {
+    extensions: { code: 'FORBIDDEN', http: { status: 403 } },
+});
+/**
+ * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.
+ * @param message Optional override for the error message.
+ */
+function throwUnauthorised(message) {
+    throw unauthorisedError(message);
+}
+/**
+ * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.
+ *
+ * Use at the top of resolvers or services to fail fast on authorization checks while keeping
+ * the happy path unindented.
+ *
+ * @param hasPermission Boolean guard; the function returns normally only when this is `true`.
+ * @param message Optional override for the error message thrown on failure.
+ *
+ * Usage:
+ *
+ * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')
+ * // past this line, TypeScript knows the condition held
+ */
+function permissionInvariant(hasPermission, message) {
+    if (!hasPermission)
+        throwUnauthorised(message);
+}
+
+exports.permissionInvariant = permissionInvariant;
+exports.throwUnauthorised = throwUnauthorised;
+exports.unauthorisedError = unauthorisedError;
+//# sourceMappingURL=unauthorised.js.map

package/unauthorised.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorised.js","sources":["../src/unauthorised.ts"],"sourcesContent":["import { GraphQLError } from 'graphql'\n\n/**\n * Builds a `GraphQLError` representing an authorization failure.\n *\n * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and\n * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.\n *\n * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.\n */\nexport const unauthorisedError = (message: string = 'Not Authorized!') =>\n  new GraphQLError(message, {\n    extensions: { code: 'FORBIDDEN', http: { status: 403 } },\n  })\n\n/**\n * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.\n * @param message Optional override for the error message.\n */\nexport function throwUnauthorised(message?: string): never {\n  throw unauthorisedError(message)\n}\n\n/**\n * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.\n *\n * Use at the top of resolvers or services to fail fast on authorization checks while keeping\n * the happy path unindented.\n *\n * @param hasPermission Boolean guard; the function returns normally only when this is `true`.\n * @param message Optional override for the error message thrown on failure.\n *\n * Usage:\n *\n * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')\n * // past this line, TypeScript knows the condition held\n */\nexport function permissionInvariant(hasPermission: boolean, message?: string): asserts hasPermission {\n  if (!hasPermission) throwUnauthorised(message)\n}\n"],"names":["GraphQLError"],"mappings":";;;;AAEA;;;;;;;AAOG;AACI,MAAM,iBAAiB,GAAG,CAAC,OAAA,GAAkB,iBAAiB,KACnE,IAAIA,oBAAY,CAAC,OAAO,EAAE;AACxB,IAAA,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;AACzD,CAAA;AAEH;;;AAGG;AACG,SAAU,iBAAiB,CAAC,OAAgB,EAAA;AAChD,IAAA,MAAM,iBAAiB,CAAC,OAAO,CAAC;AAClC;AAEA;;;;;;;;;;;;;AAaG;AACG,SAAU,mBAAmB,CAAC,aAAsB,EAAE,OAAgB,EAAA;AAC1E,IAAA,IAAI,CAAC,aAAa;QAAE,iBAAiB,CAAC,OAAO,CAAC;AAChD;;;;;;"}

package/unauthorised.mjs

@@ -0,0 +1,41 @@
+import { GraphQLError } from 'graphql';
+
+/**
+ * Builds a `GraphQLError` representing an authorization failure.
+ *
+ * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and
+ * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.
+ *
+ * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.
+ */
+const unauthorisedError = (message = 'Not Authorized!') => new GraphQLError(message, {
+    extensions: { code: 'FORBIDDEN', http: { status: 403 } },
+});
+/**
+ * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.
+ * @param message Optional override for the error message.
+ */
+function throwUnauthorised(message) {
+    throw unauthorisedError(message);
+}
+/**
+ * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.
+ *
+ * Use at the top of resolvers or services to fail fast on authorization checks while keeping
+ * the happy path unindented.
+ *
+ * @param hasPermission Boolean guard; the function returns normally only when this is `true`.
+ * @param message Optional override for the error message thrown on failure.
+ *
+ * Usage:
+ *
+ * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')
+ * // past this line, TypeScript knows the condition held
+ */
+function permissionInvariant(hasPermission, message) {
+    if (!hasPermission)
+        throwUnauthorised(message);
+}
+
+export { permissionInvariant, throwUnauthorised, unauthorisedError };
+//# sourceMappingURL=unauthorised.mjs.map

package/unauthorised.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"unauthorised.mjs","sources":["../src/unauthorised.ts"],"sourcesContent":["import { GraphQLError } from 'graphql'\n\n/**\n * Builds a `GraphQLError` representing an authorization failure.\n *\n * Sets the Apollo-standard `FORBIDDEN` extension code and an HTTP 403 status, so clients and\n * gateways that inspect `extensions.code` / `extensions.http.status` see a consistent shape.\n *\n * @param message Error message shown to the client. Defaults to `'Not Authorized!'`.\n */\nexport const unauthorisedError = (message: string = 'Not Authorized!') =>\n  new GraphQLError(message, {\n    extensions: { code: 'FORBIDDEN', http: { status: 403 } },\n  })\n\n/**\n * Throws an {@link unauthorisedError}. Return type is `never` so TypeScript narrows control flow past the call.\n * @param message Optional override for the error message.\n */\nexport function throwUnauthorised(message?: string): never {\n  throw unauthorisedError(message)\n}\n\n/**\n * Assertion helper: throws an {@link unauthorisedError} when `hasPermission` is false, otherwise narrows it to `true`.\n *\n * Use at the top of resolvers or services to fail fast on authorization checks while keeping\n * the happy path unindented.\n *\n * @param hasPermission Boolean guard; the function returns normally only when this is `true`.\n * @param message Optional override for the error message thrown on failure.\n *\n * Usage:\n *\n * permissionInvariant(ctx.user?.id === record.ownerId, 'Only the owner can edit this record')\n * // past this line, TypeScript knows the condition held\n */\nexport function permissionInvariant(hasPermission: boolean, message?: string): asserts hasPermission {\n  if (!hasPermission) throwUnauthorised(message)\n}\n"],"names":[],"mappings":";;AAEA;;;;;;;AAOG;AACI,MAAM,iBAAiB,GAAG,CAAC,OAAA,GAAkB,iBAAiB,KACnE,IAAI,YAAY,CAAC,OAAO,EAAE;AACxB,IAAA,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;AACzD,CAAA;AAEH;;;AAGG;AACG,SAAU,iBAAiB,CAAC,OAAgB,EAAA;AAChD,IAAA,MAAM,iBAAiB,CAAC,OAAO,CAAC;AAClC;AAEA;;;;;;;;;;;;;AAaG;AACG,SAAU,mBAAmB,CAAC,aAAsB,EAAE,OAAgB,EAAA;AAC1E,IAAA,IAAI,CAAC,aAAa;QAAE,iBAAiB,CAAC,OAAO,CAAC;AAChD;;;;"}

package/shield.d.ts

@@ -1,43 +0,0 @@
-import type { and, chain, or, race } from 'graphql-shield';
-import { allow } from 'graphql-shield';
-import type { Primitive } from './type-utils';
-type RuleCombinator = typeof chain | typeof race | typeof or | typeof and;
-export type ShieldRule = ReturnType<(typeof allow)['getRules']>[number];
-export declare const createRule: <TContext, TParent = unknown, TArgs = unknown>(logic: (parent: TParent, args: TArgs, ctx: TContext) => boolean | Promise<boolean> | Error, cache?: "contextual" | "strict") => ShieldRule;
-/**
- * Combines a given rule with all existing defined rules using the provided combinator
- * @param schema The existing shield schema with rules
- * @param rule The rule to be combined with existing rules
- * @param combinator The combinator to use. Eg. and | or | chain | race
- *
- * Usage:
- *
- * const updatedSchema = combineRuleWithAll(shieldSchema, rules.accountNotBlocked, chain)
- */
-export declare function combineRuleWithAll<T>(schema: ShieldSchema<T>, rule: ShieldRule, combinator: RuleCombinator): ShieldSchema<T>;
-/**
- * Creates graphql shield middleware making use of generics to type the definition of the rules.
- * @param schema A mapping of schema objects to the shield rules that define the access to that object
- * @param fallbackRule A fallback rule to apply to any object or property which doesn't have a defined rule.
- *
- * Usage:
- * import { Resolvers } from '../generated/types'
- *
- * const shieldSchema = createShieldSchema<Resolvers>({
- *   Query: {
- *     getThings: allow,
- *     dontGetThings: deny,
- *   }
- * })
- *
- * let schema = makeExecutableSchema({...})
- *
- * schema = applyMiddleware(schema, shieldSchema)
- */
-export declare function createShieldSchema<TRootResolvers>(schema: ShieldSchema<TRootResolvers>, fallbackRule?: ShieldRule): import("graphql-middleware").IMiddlewareGenerator<any, any, any>;
-export type ShieldSchema<TResolver> = TResolver extends Primitive ? ShieldRule : {
-    [key in keyof TResolver]?: ShieldSchema<TResolver[key]> | ShieldRule;
-} & {
-    '*'?: ShieldRule;
-};
-export {};