From 6c91f1f631e53c0254af6826290d34fcb462f5b2 Mon Sep 17 00:00:00 2001 From: Elliot Lintz <45725915+Elliot67@users.noreply.github.com> Date: Sat, 19 Oct 2024 00:41:43 +0200 Subject: [PATCH 1/2] doc: fix some typos and grammatical errors --- packages/plugin-scope-auth/README.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/packages/plugin-scope-auth/README.md b/packages/plugin-scope-auth/README.md index ec6675658..05bb0c354 100644 --- a/packages/plugin-scope-auth/README.md +++ b/packages/plugin-scope-auth/README.md @@ -58,7 +58,7 @@ const builder = new SchemaBuilder<{ In the above setup, We import the `scope-auth` plugin, and include it in the builders plugin list. We also define 2 important things: -1. The `AuthScopes` type in the builder `SchemaTypes`. This is a map of types that define the types +1. The `AuthScopes` type in the builder `SchemaTypes`. This is a map of types that defines the types used by each of your scopes. We'll see how this is used in more detail below. 2. The `scope initializer` function, which is the implementation of each of the scopes defined in @@ -90,7 +90,7 @@ A lot of terms around authorization are overloaded, and can mean different thing people. Here is a short list of a few terms used in this document, and how they should be interpreted: -- `scope`: A scope is unit of authorization that can be used to authorize a request to resolve a +- `scope`: A scope is the unit of authorization that can be used to authorize a request to resolve a field. - `scope map`: A map of scope names and scope parameters. This defines the set of scopes that will @@ -98,7 +98,7 @@ interpreted: - `scope loader`: A function for dynamically loading scope given a scope parameter. Scope loaders are ideal for integrating with a permission service, or creating scopes that can be customized - based in the field or values that they are authorizing. + based on the field or values that they are authorizing. - `scope parameter`: A parameter that will be passed to a scope loader. These are the values in the authScopes objects. @@ -106,7 +106,7 @@ interpreted: - `scope initializer`: The function that creates the scopes or scope loaders for the current request. -While this plugin uses `scopes` as the term for it's authorization mechanism, this plugin can easily +While this plugin uses `scopes` as the term for its authorization mechanism, this plugin can easily be used for role or permission based schemes, and is not intended to dictate a specific philosophy around how to authorize requests/access to resources. @@ -236,11 +236,11 @@ default scopes. ### Running scopes on types rather than fields By default, all auth scopes are tested before a field resolves. This includes both scopes defined on -a type and scopes defined on a fields. When scopes for a `type` fail, you will end up with an error +a type and scopes defined on a field. When scopes for a `type` fail, you will end up with an error for each field of that type. Type level scopes are only executed once, but the errors are emitted for each affected field. -The behavior may not be desireable for all users. You can set `runScopesOnType` to true, either on +The behavior may not be desirable for all users. You can set `runScopesOnType` to true, either on object types, or in the `scopeAuth` options of the builder ```typescript @@ -267,7 +267,7 @@ builder.objectType(Article, { }, fields: (t) => ({ title: t.exposeString('title', { - // this will not have any affect because type scopes are not evaluated at the field level + // this will not have any effect because type scopes are not evaluated at the field level skipTypeScopes: true, }), content: t.exposeString('title', {}), @@ -277,7 +277,7 @@ builder.objectType(Article, { Enabling this has a couple of limitations: -1. THIS DOES NOT CURRENTLY WORK WITH `graphql-jit`. This options uses the `isTypeOf` function, but +1. THIS DOES NOT CURRENTLY WORK WITH `graphql-jit`. This option uses the `isTypeOf` function, but `graphql-jit` does not support async `isTypeOf`, and also does not correctly pass the context object to the isTypeOf checks. Until this is resolved, this option will not work with `graphql-jit`. @@ -469,7 +469,7 @@ const builder = new SchemaBuilder<{ }); ``` -This will ensure that if a request access a field that requests a `humanPermission` scope, and the +This will ensure that if a request accesses a field that requests a `humanPermission` scope, and the request is made by another service or bot, we don't have to run the `hasPermission` check at all for those requests, since we know it would return false anyways. @@ -551,7 +551,7 @@ builder.queryField('viewer', (t) => ### Logical operations on auth scopes \(any/all\) -By default the the scopes in a scope map are evaluated in parallel, and if the request has any of +By default the scopes in a scope map are evaluated in parallel, and if the request has any of the requested scopes, the field will be resolved. In some cases, you may want to require multiple scopes: @@ -697,7 +697,7 @@ builder.objectType(Article, { In the above example, the fields of the `Article` type normally require the `public` scope granted to logged in users, but can also be accessed with the `$granted` scope `readArticle`. This means -that if the field that returned the Article "granted" the scope, the article ran be read. The +that if the field that returned the Article "granted" the scope, the article can be read. The `freeArticle` field on the `Query` type grants this scope, allowing anyone querying that field to access fields of the free article. `$granted` scopes are separate from other scopes, and do not give a request access to normal scopes of the same name. `$granted` scopes are also not inherited by @@ -743,7 +743,7 @@ builder.objectType(Article, { ``` In the above example, `title`, `content`, and `viewCount` each use `$granted` scopes. In this case, -rather than scopes being granted by the parent field, they are granted by the the Article type +rather than scopes being granted by the parent field, they are granted by the Article type itself. This allows the access to each field to change based on some dynamic conditions \(if the request is from the author, and if the article is a draft\) without having to duplicate that logic in each individual field. From 2e4598077cb0743e07e120e934c3e05329303a5d Mon Sep 17 00:00:00 2001 From: Elliot67 Date: Sat, 19 Oct 2024 01:00:52 +0200 Subject: [PATCH 2/2] doc: replicate doc fixes in website --- website/content/docs/plugins/scope-auth.mdx | 24 ++++++++++----------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/website/content/docs/plugins/scope-auth.mdx b/website/content/docs/plugins/scope-auth.mdx index 8661815fc..cde2ccef0 100644 --- a/website/content/docs/plugins/scope-auth.mdx +++ b/website/content/docs/plugins/scope-auth.mdx @@ -61,7 +61,7 @@ const builder = new SchemaBuilder<{ In the above setup, We import the `scope-auth` plugin, and include it in the builders plugin list. We also define 2 important things: -1. The `AuthScopes` type in the builder `SchemaTypes`. This is a map of types that define the types +1. The `AuthScopes` type in the builder `SchemaTypes`. This is a map of types that defines the types used by each of your scopes. We'll see how this is used in more detail below. 2. The `scope initializer` function, which is the implementation of each of the scopes defined in @@ -93,7 +93,7 @@ A lot of terms around authorization are overloaded, and can mean different thing people. Here is a short list of a few terms used in this document, and how they should be interpreted: -- `scope`: A scope is unit of authorization that can be used to authorize a request to resolve a +- `scope`: A scope is the unit of authorization that can be used to authorize a request to resolve a field. - `scope map`: A map of scope names and scope parameters. This defines the set of scopes that will @@ -101,7 +101,7 @@ interpreted: - `scope loader`: A function for dynamically loading scope given a scope parameter. Scope loaders are ideal for integrating with a permission service, or creating scopes that can be customized - based in the field or values that they are authorizing. + based on the field or values that they are authorizing. - `scope parameter`: A parameter that will be passed to a scope loader. These are the values in the authScopes objects. @@ -109,7 +109,7 @@ interpreted: - `scope initializer`: The function that creates the scopes or scope loaders for the current request. -While this plugin uses `scopes` as the term for it's authorization mechanism, this plugin can easily +While this plugin uses `scopes` as the term for its authorization mechanism, this plugin can easily be used for role or permission based schemes, and is not intended to dictate a specific philosophy around how to authorize requests/access to resources. @@ -239,11 +239,11 @@ default scopes. ### Running scopes on types rather than fields By default, all auth scopes are tested before a field resolves. This includes both scopes defined on -a type and scopes defined on a fields. When scopes for a `type` fail, you will end up with an error +a type and scopes defined on a field. When scopes for a `type` fail, you will end up with an error for each field of that type. Type level scopes are only executed once, but the errors are emitted for each affected field. -The behavior may not be desireable for all users. You can set `runScopesOnType` to true, either on +The behavior may not be desirable for all users. You can set `runScopesOnType` to true, either on object types, or in the `scopeAuth` options of the builder ```typescript @@ -270,7 +270,7 @@ builder.objectType(Article, { }, fields: (t) => ({ title: t.exposeString('title', { - // this will not have any affect because type scopes are not evaluated at the field level + // this will not have any effect because type scopes are not evaluated at the field level skipTypeScopes: true, }), content: t.exposeString('title', {}), @@ -280,7 +280,7 @@ builder.objectType(Article, { Enabling this has a couple of limitations: -1. THIS DOES NOT CURRENTLY WORK WITH `graphql-jit`. This options uses the `isTypeOf` function, but +1. THIS DOES NOT CURRENTLY WORK WITH `graphql-jit`. This option uses the `isTypeOf` function, but `graphql-jit` does not support async `isTypeOf`, and also does not correctly pass the context object to the isTypeOf checks. Until this is resolved, this option will not work with `graphql-jit`. @@ -472,7 +472,7 @@ const builder = new SchemaBuilder<{ }); ``` -This will ensure that if a request access a field that requests a `humanPermission` scope, and the +This will ensure that if a request accesses a field that requests a `humanPermission` scope, and the request is made by another service or bot, we don't have to run the `hasPermission` check at all for those requests, since we know it would return false anyways. @@ -554,7 +554,7 @@ builder.queryField('viewer', (t) => ### Logical operations on auth scopes \(any/all\) -By default the the scopes in a scope map are evaluated in parallel, and if the request has any of +By default the scopes in a scope map are evaluated in parallel, and if the request has any of the requested scopes, the field will be resolved. In some cases, you may want to require multiple scopes: @@ -700,7 +700,7 @@ builder.objectType(Article, { In the above example, the fields of the `Article` type normally require the `public` scope granted to logged in users, but can also be accessed with the `$granted` scope `readArticle`. This means -that if the field that returned the Article "granted" the scope, the article ran be read. The +that if the field that returned the Article "granted" the scope, the article can be read. The `freeArticle` field on the `Query` type grants this scope, allowing anyone querying that field to access fields of the free article. `$granted` scopes are separate from other scopes, and do not give a request access to normal scopes of the same name. `$granted` scopes are also not inherited by @@ -746,7 +746,7 @@ builder.objectType(Article, { ``` In the above example, `title`, `content`, and `viewCount` each use `$granted` scopes. In this case, -rather than scopes being granted by the parent field, they are granted by the the Article type +rather than scopes being granted by the parent field, they are granted by the Article type itself. This allows the access to each field to change based on some dynamic conditions \(if the request is from the author, and if the article is a draft\) without having to duplicate that logic in each individual field.