Skip to content

Commit

Permalink
Run migration script
Browse files Browse the repository at this point in the history
  • Loading branch information
@emmatown
emmatown committed Aug 12, 2022
1 parent 524eb87 commit 29977d2
Show file tree
Hide file tree
Showing 40 changed files with 855 additions and 823 deletions.
68 changes: 49 additions & 19 deletions docs/pages/docs/apis/access-control.mdx → docs/pages/docs/apis/access-control.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
import { Markdown } from '../../../components/Markdown';
---
title: "Access Control API"
description: "Complete reference docs for Keystone’s Access Control API. Configure who can read, create, update, and delete items in your Keystone system."
---

# Access Control API

?> We recently improved this API so it’s easier to program, and makes it harder to introduce security gaps in your system. If you were using it prior to September 6th 2021, [read this guide](/updates/new-access-control) for info on how to upgrade.
{% hint kind="warn" %}
We recently improved this API so it’s easier to program, and makes it harder to introduce security gaps in your system. If you were using it prior to September 6th 2021, [read this guide](/updates/new-access-control) for info on how to upgrade.
{% /hint %}

The `access` property of the [list configuration](./schema) object configures who can query, create, update, and delete items in your Keystone system.
The `access` property of the [field configuration](./fields) object configures who can read, create, and update specific field values of an item.
Expand Down Expand Up @@ -36,9 +39,13 @@ There are three types of access control that can be configured on the `access` o

Each of these types of access control are applied before [hooks](./hooks).

?> Please note that Keystone does not automatically configure nor leverage database row security policies or row level security
{% hint kind="warn" %}
Please note that Keystone does not automatically configure nor leverage database row security policies or row level security
{% /hint %}

!> **Access denied:** **Mutations** return `null` data with an access denied error. **Queries** never return access denied errors, and instead treat items as if they didn't exist.
{% hint kind="tip" %}
**Access denied:** **Mutations** return `null` data with an access denied error. **Queries** never return access denied errors, and instead treat items as if they didn't exist.
{% /hint %}

If access is **denied** due to any of the access control methods, the following responses will be returned from the GraphQL API:

Expand All @@ -56,9 +63,13 @@ If access is **denied** due to any of the access control methods, the following
Operation-level access control lets you control which operations can be accessed by a user based on the `session` and `context`.
Individual functions can be provided for each of the operations.

?> Each operation type _defaults to public_ unless configured.
{% hint kind="warn" %}
Each operation type _defaults to public_ unless configured.
{% /hint %}

!> These functions must return `true` if the operation is allowed, or `false` if it is not allowed.
{% hint kind="tip" %}
These functions must return `true` if the operation is allowed, or `false` if it is not allowed.
{% /hint %}

```typescript
import { config, list } from '@keystone-6/core';
Expand All @@ -79,9 +90,11 @@ export default config({
});
```

?> The `query` access control is applied only when running GraphQL query operations.
{% hint kind="warn" %}
The `query` access control is applied only when running GraphQL query operations.
A user can still **read** fields as part of a return query when using a mutation `operation` (`create`, `update` or `delete`).
If you want to limit access to fields, use [field access control](https://keystonejs.com/docs/apis/access-control#field-access-control).
{% /hint %}

### Filter

Expand All @@ -93,7 +106,9 @@ Filter-level access control lets you restrict which items can be operated on by
In general, the filter access control functions will return GraphQL filters.
They can also return boolean values `true` or `false` to match or exclude all items.

?> Each `filter` type _defaults to an empty filter_, unless configured.
{% hint kind="warn" %}
Each `filter` type _defaults to an empty filter_, unless configured.
{% /hint %}

```typescript
import { config, list } from '@keystone-6/core';
Expand Down Expand Up @@ -125,10 +140,14 @@ export default config({
});
```

!> Filter based access control cannot be used for `create` operations.
{% hint kind="tip" %}
Filter based access control cannot be used for `create` operations.
If you want to limit `create` operations, use either `access.operation.create` or `access.item.create`.
{% /hint %}

?> Filter based access control can impact the performance of your database queries.
{% hint kind="warn" %}
Filter based access control can impact the performance of your database queries.
{% /hint %}

### Item (mutations only)

Expand All @@ -138,9 +157,13 @@ Individual functions can be provided for each of the operations, with each funct
- the **input data** of the mutation (for `create` and `update` operations), and/or
- the **existing item** in the database (for `update` and `delete` operations).

?> Each `item` access type _defaults to public_ unless configured.
{% hint kind="warn" %}
Each `item` access type _defaults to public_ unless configured.
{% /hint %}

!> These functions must return `true` if the operation is allowed, or `false` if it is not allowed.
{% hint kind="tip" %}
These functions must return `true` if the operation is allowed, or `false` if it is not allowed.
{% /hint %}

```typescript
import { config, list } from '@keystone-6/core';
Expand All @@ -161,8 +184,10 @@ export default config({
});
```

?> Item-level access control is not available for `query` operations.
{% hint kind="warn" %}
Item-level access control is not available for `query` operations.
Applying access control after fetching items would lead to inconsistent pagination behaviour and incorrect `count` results.
{% /hint %}

### Function Arguments

Expand All @@ -182,7 +207,9 @@ List-level access control functions are passed a collection of arguments which c
Keystone also allows you to set up access control on a per-field basis.
Rules can be set for `read`, `create` and `update` operations.

!> Each operation is defined by a function which returns `true` if access is allowed and `false` if access is not allowed.
{% hint kind="tip" %}
Each operation is defined by a function which returns `true` if access is allowed and `false` if access is not allowed.
{% /hint %}

### Mutations

Expand All @@ -197,7 +224,9 @@ Field-level access control rules are applied when trying to resolve a field on t
If access is denied then the query will still return an item object, but the specific field will return `null`.
No errors will be returned for `read` access denied.

!> The `read` access control is applied to fields returned from both **queries** and **mutations**.
{% hint kind="tip" %}
The `read` access control is applied to fields returned from both **queries** and **mutations**.
{% /hint %}

```typescript
import { config, list } from '@keystone-6/core';
Expand All @@ -220,7 +249,9 @@ export default config({
});
```

!> Field-level access control is not available for `delete` operations. Restrict `delete` operations at the List-level instead with `access.operation.delete`, `access.filter.delete` or `access.item.delete`.
{% hint kind="tip" %}
Field-level access control is not available for `delete` operations. Restrict `delete` operations at the List-level instead with `access.operation.delete`, `access.filter.delete` or `access.item.delete`.
{% /hint %}

### Function Arguments

Expand All @@ -236,4 +267,3 @@ Field-level access control functions are passed a collection of arguments which
| `inputData` | For `create` and `update` operations, this is the value of `data` passed into the mutation. |
| `item` | The existing item being read/updated in `read` and `update` operations. |

export default ({ children }) => <Markdown description="Complete reference docs for Keystone’s Access Control API. Configure who can read, create, update, and delete items in your Keystone system.">{children}</Markdown>;
25 changes: 11 additions & 14 deletions docs/pages/docs/apis/auth.mdx → docs/pages/docs/apis/auth.md
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,7 @@
import { Markdown } from '../../../components/Markdown';
import { Well } from '../../../components/primitives/Well';
import { RelatedContent } from '../../../components/RelatedContent';

# Authentication API
---
title: "Authentication API"
description: "API reference for supporting authentication against a password field using the createAuth() function in the `@keystone-6/auth` package."
---

Keystone allows you to extend your Keystone system to support authentication against a `password` field using the `createAuth()` function in the `@keystone-6/auth` package.
Additional options to this function provide support for creating an initial item in your database, sending password reset tokens, and sending one-time authentication tokens.
Expand Down Expand Up @@ -457,13 +456,11 @@ The authenticated item will be returned as `item`.

## Related resources

<RelatedContent>
<Well
heading="Example Project: Authentication"
href="https://github.com/keystonejs/keystone/tree/main/examples/with-auth"
>
Adds password-based authentication to the Task Manager starter project.
</Well>
</RelatedContent>
{% related-content %}
{% well
heading="Example Project: Authentication"
href="https://github.com/keystonejs/keystone/tree/main/examples/with-auth" %}
Adds password-based authentication to the Task Manager starter project.
{% /well %}
{% /related-content %}

export default ({ children }) => <Markdown description="API reference for supporting authentication against a password field using the createAuth() function in the `@keystone-6/auth` package.">{children}</Markdown>;
26 changes: 11 additions & 15 deletions docs/pages/docs/apis/config.mdx → docs/pages/docs/apis/config.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
import { Markdown } from '../../../components/Markdown';
import { Well } from '../../../components/primitives/Well';
import { RelatedContent } from '../../../components/RelatedContent';
import { InlineCode } from '../../../components/primitives/Code';

# System Configuration API
---
title: "System Configuration API"
description: "API reference for configuring your Keystone system: Lists, Database, Admin UI, Server, Sessions, GraphQl, Files, Images, and experimental options."
---

The `keystone` [CLI](../guides/cli) expects to find a module named `keystone.ts` with a default export of a Keystone system configuration returned from the function `config()`.

Expand Down Expand Up @@ -517,13 +515,11 @@ Options:

## Related resources

<RelatedContent>
<Well
heading="Schema API Reference"
href="/docs/apis/schema"
>
The API to configure your options used with the <InlineCode>list</InlineCode> function.
</Well>
</RelatedContent>
{% related-content %}
{% well
heading="Schema API Reference"
href="/docs/apis/schema" %}
The API to configure your options used with the `list` function.
{% /well %}
{% /related-content %}

export default ({ children }) => <Markdown description="API reference for configuring your Keystone system: Lists, Database, Admin UI, Server, Sessions, GraphQl, Files, Images, and experimental options.">{children}</Markdown>;
39 changes: 17 additions & 22 deletions docs/pages/docs/apis/context.mdx → docs/pages/docs/apis/context.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
import { Markdown } from '../../../components/Markdown';
import { Well } from '../../../components/primitives/Well';
import { RelatedContent } from '../../../components/RelatedContent';
import { InlineCode } from '../../../components/primitives/Code';

# Context API
---
title: "Context API"
description: "The KeystoneContext object is the primary API entry point for all of the run-time functionality of your system. It's APIs can be used to write things like access control, hooks, testing and GraphQL schema extensions."
---

The `KeystoneContext` object is the primary API entry point for all of the run-time functionality of your Keystone system.
In GraphQL, a [`context`](https://graphql.org/learn/execution/#root-fields-resolvers) is a value which is provided to every resolver and holds important contextual information such as the currently logged in user, or access to a database.
Expand Down Expand Up @@ -161,19 +159,16 @@ They will be removed in future releases.

## Related resources

<RelatedContent>
<Well
heading="Query API Reference"
href="/docs/apis/query"
>
A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.query.&lt;listName&gt;</InlineCode>
</Well>
<Well
heading="DB API Reference"
href="/docs/apis/db-items"
>
The API for running CRUD operations against the internal GraphQL resolvers in your system. It returns internal item objects, which can be returned from GraphQL resolvers.
</Well>
</RelatedContent>

export default ({ children }) => <Markdown description="The KeystoneContext object is the primary API entry point for all of the run-time functionality of your system. It's APIs can be used to write things like access control, hooks, testing and GraphQL schema extensions.">{children}</Markdown>;
{% related-content %}
{% well
heading="Query API Reference"
href="/docs/apis/query" %}
A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at `context.query.<listName>`
{% /well %}
{% well
heading="DB API Reference"
href="/docs/apis/db-items" %}
The API for running CRUD operations against the internal GraphQL resolvers in your system. It returns internal item objects, which can be returned from GraphQL resolvers.
{% /well %}
{% /related-content %}

39 changes: 17 additions & 22 deletions docs/pages/docs/apis/db-items.mdx → docs/pages/docs/apis/db-items.md
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,7 @@
import { Markdown } from '../../../components/Markdown';
import { Well } from '../../../components/primitives/Well';
import { RelatedContent } from '../../../components/RelatedContent';
import { InlineCode } from '../../../components/primitives/Code';

# Database API
---
title: "Database API"
description: "Keystone’s database API is a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system. It bypasses the GraphQL Server itself, invoking resolver functions directly."
---

The database API provides a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system.
Importantly, this API bypasses the GraphQL Server itself, instead invoking the resolver functions directly.
Expand Down Expand Up @@ -145,19 +143,16 @@ const users = await context.db.User.deleteMany({

## Related resources

<RelatedContent>
<Well
heading="Query API Reference"
href="/docs/apis/query"
>
A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at <InlineCode>context.query.&lt;listName&gt;</InlineCode>.
</Well>
<Well
heading="Context API Reference"
href="/docs/apis/context"
>
The API for run-time functionality in your Keystone system. Use it to write business logic for access control, hooks, testing, GraphQL schema extensions, and more.
</Well>
</RelatedContent>

export default ({ children }) => <Markdown description="Keystone’s database API is a programmatic API for running CRUD operations against the internal GraphQL resolvers in your system. It bypasses the GraphQL Server itself, invoking resolver functions directly.">{children}</Markdown>;
{% related-content %}
{% well
heading="Query API Reference"
href="/docs/apis/query" %}
A programmatic API for running CRUD operations against your GraphQL API. For each list in your system you get an API at `context.query.<listName>`.
{% /well %}
{% well
heading="Context API Reference"
href="/docs/apis/context" %}
The API for run-time functionality in your Keystone system. Use it to write business logic for access control, hooks, testing, GraphQL schema extensions, and more.
{% /well %}
{% /related-content %}

48 changes: 23 additions & 25 deletions docs/pages/docs/apis/fields.mdx → docs/pages/docs/apis/fields.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
import { Markdown } from '../../../components/Markdown';
import { Well } from '../../../components/primitives/Well';
import { RelatedContent } from '../../../components/RelatedContent';
import { InlineCode } from '../../../components/primitives/Code';
---
title: "Fields API"
description: "A reference of Keystone’s field types, and the configuration options they accept."
---

# Fields API

?> We recently improved this API. If you were using it prior to October 5th 2021, [read this guide](/releases/2021-10-05#upgrade-guide) for details on how to upgrade.
{% hint kind="warn" %}
We recently improved this API. If you were using it prior to October 5th 2021, [read this guide](/releases/2021-10-05#upgrade-guide) for details on how to upgrade.
{% /hint %}

The `fields` option of a [list configuration](./schema) defines the names, types, and configuration of the fields in the list.
This configuration option takes an object with field names as keys, and configured field types as values.
Expand Down Expand Up @@ -241,7 +241,7 @@ export default config({
A `bigInt` field represents a 64 bit signed integer value.
When interacting with the field with GraphQL, values will be strings.
When interacting with the field in hooks, values will be [Javascript `BigInt`s](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#bigint_type).
Javascript `BigInt`s are used since [integers in Javascript are unsafe beyond 2<sup>53</sup>](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).
Javascript `BigInt`s are used since [integers in Javascript are unsafe beyond 2{% sup %}53{% /sup %}](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER).

Options:

Expand Down Expand Up @@ -629,10 +629,12 @@ Options:
This is only allowed when you have no create access control because otherwise, the item will always fail access control
if a user doesn't have access to create the particular field regardless of whether or not they specify the field in the create.

!> **\*Warning** Unlike with other `keystone` fields, `db.isNullable` is defaulted to `false` for the text field.
{% hint kind="tip" %}
**\*Warning** Unlike with other `keystone` fields, `db.isNullable` is defaulted to `false` for the text field.
This is primarily in the interest of not having to make assumptions about how a `null` value can be represented in a text field in the Admin-UI in the default case.
These differences, and the rationale for them, are examined in detail [on GitHub](https://github.com/keystonejs/keystone/discussions/7158).
You can opt into this behaviour by explicitly setting `isNullable: true`.
{% /hint %}

```typescript
import { config, list } from '@keystone-6/core';
Expand Down Expand Up @@ -1022,19 +1024,15 @@ export default config({

## Related resources

<RelatedContent>
<Well
heading="Schema API Reference"
href="/docs/apis/schema"
>
The API to configure your options used with the <InlineCode>list()</InlineCode> function.
</Well>
<Well
heading="GraphQL API Reference"
href="/docs/apis/graphql"
>
A complete CRUD (create, read, update, delete) GraphQL API derived from the list and field names you configure in your system.
</Well>
</RelatedContent>

export default ({ children }) => <Markdown description="A reference of Keystone’s field types, and the configuration options they accept.">{children}</Markdown>
{% related-content %}
{% well
heading="Schema API Reference"
href="/docs/apis/schema" %}
The API to configure your options used with the `list()` function.
{% /well %}
{% well
heading="GraphQL API Reference"
href="/docs/apis/graphql" %}
A complete CRUD (create, read, update, delete) GraphQL API derived from the list and field names you configure in your system.
{% /well %}
{% /related-content %}
Loading

0 comments on commit 29977d2

Please sign in to comment.