@vendure/docs 0.0.0-202601161541

package/docs/guides/developer-guide/rest-endpoint/index.md

@@ -0,0 +1,99 @@
+---
+title: "Add a REST endpoint"
+showtoc: true
+---
+
+REST-style endpoints can be defined as part of a [plugin](/guides/developer-guide/plugins/).
+
+:::info
+REST endpoints are implemented as NestJS Controllers. For comprehensive documentation, see the [NestJS controllers documentation](https://docs.nestjs.com/controllers).
+:::
+
+In this guide we will define a plugin that adds a single REST endpoint at `http://localhost:3000/products` which returns a list of all products.
+
+## Create a controller
+
+First let's define the controller:
+
+```ts title="src/plugins/rest-plugin/api/products.controller.ts"
+// products.controller.ts
+import { Controller, Get } from '@nestjs/common';
+import { Ctx, ProductService, RequestContext } from '@vendure/core';
+
+@Controller('products')
+export class ProductsController {
+    constructor(private productService: ProductService) {
+    }
+
+    @Get()
+    findAll(@Ctx() ctx: RequestContext) {
+        return this.productService.findAll(ctx);
+    }
+}
+```
+
+The key points to note here are:
+
+- The `@Controller()` decorator defines the base path for all endpoints defined in this controller. In this case, all endpoints will be prefixed with `/products`.
+- The `@Get()` decorator defines a GET endpoint at the base path. The method name `findAll` is arbitrary.
+- The `@Ctx()` decorator injects the [RequestContext](/reference/typescript-api/request/request-context/) which is required for all service methods.
+
+## Register the controller with the plugin
+
+```ts title="src/plugins/rest-plugin/rest.plugin.ts"
+import { PluginCommonModule, VendurePlugin } from '@vendure/core';
+import { ProductsController } from './api/products.controller';
+
+@VendurePlugin({
+  imports: [PluginCommonModule],
+  controllers: [ProductsController],
+})
+export class RestPlugin {}
+```
+
+:::info
+**Note:** [The `PluginCommonModule`](/reference/typescript-api/plugin/plugin-common-module/) should be imported to gain access to Vendure core providers - in this case it is required in order to be able to inject `ProductService` into our controller.
+:::
+
+The plugin can then be added to the `VendureConfig`:
+
+```ts title="src/vendure-config.ts"
+import { VendureConfig } from '@vendure/core';
+import { RestPlugin } from './plugins/rest-plugin/rest.plugin';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        // ...
+        // highlight-next-line
+        RestPlugin,
+    ],
+};
+```
+
+## Controlling access to REST endpoints
+
+You can use the [`@Allow()` decorator](/reference/typescript-api/request/allow-decorator/) to declare the permissions required to access a REST endpoint:
+
+```ts title="src/plugins/rest-plugin/api/products.controller.ts"
+import { Controller, Get } from '@nestjs/common';
+import { Allow, Permission, Ctx, ProductService, RequestContext } from '@vendure/core';
+
+@Controller('products')
+export class ProductsController {
+    constructor(private productService: ProductService) {}
+
+    // highlight-next-line
+    @Allow(Permission.ReadProduct)
+    @Get()
+    findAll(@Ctx() ctx: RequestContext) {
+        return this.productService.findAll(ctx);
+    }
+}
+```
+
+:::tip
+The following Vendure [API decorators](/guides/developer-guide/the-api-layer/#api-decorators) can also be used with NestJS controllers: `@Allow()`, `@Transaction()`, `@Ctx()`.
+
+Additionally, NestJS supports a number of other REST decorators detailed in the [NestJS controllers guide](https://docs.nestjs.com/controllers#request-object)
+:::

package/docs/guides/developer-guide/scheduled-tasks/index.md

@@ -0,0 +1,298 @@
+---
+title: 'Scheduled Tasks'
+showtoc: true
+---
+
+Scheduled tasks are a way of executing some code at pre-defined intervals. There are many examples of work that can be done using scheduled tasks,
+such as:
+
+- Generating a sitemap
+- Synchronizing data between different systems
+- Sending abandoned cart emails
+- Cleaning up old data
+
+Since Vendure v3.3, there is a built-in mechanism which allows you to define scheduled tasks in a convenient and powerful way.
+
+:::info
+All the information on page applies to Vendure v3.3+
+
+For older versions, there is no built-in support for scheduled tasks, but you can
+instead use a [stand-alone script](/guides/developer-guide/stand-alone-scripts/) triggered by a cron job.
+:::
+
+## Setting up the DefaultSchedulerPlugin
+
+In your Vendure config, import and add the [DefaultSchedulerPlugin](/reference/typescript-api/scheduled-tasks/default-scheduler-plugin) to your
+plugins array. If you created your project with a version newer than v3.3, this should already be configured.
+
+```ts title="vendure-config.ts"
+import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [DefaultSchedulerPlugin.init()],
+};
+```
+
+When you first add this plugin to your config, you'll need to [generate a migration](/guides/developer-guide/migrations/) because the
+plugin will make use of a new database table in order to guarantee only-once execution of tasks.
+
+You can then start adding tasks. Vendure ships with a task that will clean up old sessions from the database.
+
+:::note
+The `cleanSessionsTask` task is actually configured by default from v3.3+, so normally you won't have to specify this
+manually unless you wish to change any of the default configuration using the `.configure()` method.
+:::
+
+```ts title="vendure-config.ts"
+import { cleanSessionsTask, DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+    // ...
+    schedulerOptions: {
+        tasks: [
+            // Use the task as is
+            cleanSessionsTask,
+            // or further configure the task
+            cleanSessionsTask.configure({
+                // Run the task every day at 3:00am
+                // The default schedule is every day at 00:00am
+                schedule: cron => cron.everyDayAt(3, 0),
+                params: {
+                    // How many sessions to process in each batch
+                    // Default: 10_000
+                    batchSize: 5_000,
+                },
+            }),
+        ],
+    },
+    plugins: [DefaultSchedulerPlugin.init()],
+};
+```
+
+## Creating a Scheduled Task
+
+Let's imagine that you have created a `SitemapPlugin` that exposes a `SitemapService` which generates a sitemap for your store. You want to run this
+task every night at midnight.
+
+Inside the plugin, you would first define a new [ScheduledTask](/reference/typescript-api/scheduled-tasks/scheduled-task) instance:
+
+```ts title="/plugins/sitemap/config/generate-sitemap-task.ts"
+import { ScheduledTask, RequestContextService } from '@vendure/core';
+
+import { SitemapService } from '../services/sitemap.service';
+
+export const generateSitemapTask = new ScheduledTask({
+    // Give your task a unique ID
+    id: 'generate-sitemap',
+    // A human-readable description of the task
+    description: 'Generates a sitemap file',
+    // Params can be used to further configure aspects of the
+    // task. They get passed in to the `execute` function as the
+    // second argument.
+    // They can be later modified using the `.configure()` method on the instance
+    params: {
+        shopBaseUrl: 'https://www.myshop.com',
+    },
+    // Define a default schedule. This can be modified using the
+    // `.configure()` method on the instance later.
+    schedule: cron => cron.everyDayAt(0, 0),
+    // This is the function that will be executed per the schedule.
+    async execute({injector, params}) {
+        // Using `injector.get()` we can grab an instance of _any_ provider defined in the
+        // Vendure core as well as by our plugins.
+        const sitemapService = injector.get(SitemapService);
+
+        // For most service methods, we'll need to pass a RequestContext object.
+        // We can use the RequestContextService to create one.
+        const ctx = await injector.get(RequestContextService).create({
+            apiType: 'admin',
+        });
+
+        // Here's the actual work we want to perform.
+        const result = await sitemapService.generateSitemap(ctx);
+
+        // The return value from the `execute` function will be available
+        // as the `lastResult` property when viewing tasks.
+        return { result };
+    },
+});
+```
+
+## Using a task
+
+Now that the task has been defined, we need to tell Vendure to use it.
+
+To do so we need to add it to the [schedulerOptions.tasks](/reference/typescript-api/scheduled-tasks/scheduler-options#tasks) array.
+
+### Adding directly in Vendure config
+
+This can be done directly in your Vendure config file:
+
+```ts title="vendure-config.ts"
+import { cleanSessionsTask, DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
+
+// highlight-next-line
+import { SitemapPlugin, generateSitemapTask } from './plugins/sitemap';
+
+export const config: VendureConfig = {
+    // ...
+    schedulerOptions: {
+        tasks: [
+            cleanSessionsTask,
+            // highlight-start
+            // Here's an example of overriding the
+            // default params using the `configure()` method.
+            generateSitemapTask.configure({
+                params: {
+                    shopBaseUrl: 'https://www.shoes.com'
+                }
+            }),
+            // highlight-end
+        ],
+    },
+    plugins: [
+        // highlight-next-line
+        SitemapPlugin,
+        DefaultSchedulerPlugin.init()
+    ],
+};
+```
+
+### Adding in plugin configuration function
+
+An alternative is that a plugin can automatically add the task to the config using the
+plugin's [configuration function](/reference/typescript-api/plugin/vendure-plugin-metadata#configuration), which allows plugins to alter the Vendure config.
+
+This allows a plugin to encapsulate any scheduled tasks so that the plugin consumer only needs to add the plugin, and not worry about
+separately adding the task to the tasks array.
+
+```ts title="src/plugins/sitemap/sitemap.plugin.ts"
+import { VendurePlugin, PluginCommonModule, Type, ScheduledTask, VendureConfig } from '@vendure/core';
+
+import { PLUGIN_OPTIONS } from './constants';
+import { SitemapPluginOptions } from './types';
+import { SitemapService } from './services/sitemap.service';
+import { generateSitemapTask } from './config/generate-sitemap-task';
+
+@VendurePlugin({
+    imports: [PluginCommonModule],
+    providers: [SitemapService],
+    configuration: (config: VendureConfig) => {
+        // highlight-start
+        // Add the task to the schedulerOptions.tasks array
+        config.schedulerOptions.tasks.push(
+            generateSitemapTask.configure({
+                params: {
+                    shopBaseUrl: SitemapPlugin.options.shopBaseUrl,
+                }
+            })
+        );
+        // highlight-end
+        return config;
+    },
+})
+export class SitemapPlugin {
+    static options: SitemapPluginOptions;
+
+    static init(options?: SitemapPluginOptions) {
+        this.options = {
+            shopBaseUrl: '',
+            ...(options ?? {}),
+        }
+    }
+}
+```
+
+This plugin can now be consumed like this:
+
+```ts title="vendure-config.ts"
+import { DefaultSchedulerPlugin, VendureConfig } from '@vendure/core';
+
+// highlight-next-line
+import { SitemapPlugin } from './plugins/sitemap';
+
+export const config: VendureConfig = {
+    // ...
+    plugins: [
+        // highlight-start
+        SitemapPlugin.init({
+            shopBaseUrl: 'https://www.shoes.com'
+        }),
+        // highlight-end
+        DefaultSchedulerPlugin.init()
+    ],
+};
+```
+
+## How scheduled tasks work
+
+The key problems solved by Vendure's task scheduler are:
+
+- Ensuring that a task is only run a single time per scheduled execution, even when you have multiple instances of servers and workers running.
+- Keeping scheduled task work away from the server instances, so that it does not affect API responsiveness.
+
+The first problem is handled by the [SchedulerStrategy](/reference/typescript-api/scheduled-tasks/scheduler-strategy), which implements a locking
+mechanism to ensure that the task is executed only once.
+
+The second problem is handled by having tasks only executed on worker processes.
+
+## Scheduled tasks vs job queue
+
+There is some overlap between the use of a scheduled task and a [job queue job](/guides/developer-guide/worker-job-queue/). They both perform some
+task on the worker, independent of requests coming in to the server.
+
+The first difference is that jobs must be triggered explicitly, whereas scheduled tasks are triggered automatically according to the schedule.
+
+Secondly, jobs are put in a _queue_ and executed once any prior pending jobs have been processed. On the other hand, scheduled tasks are executed
+as soon as the schedule dictates.
+
+It is possible to combine the two: namely, you can define a scheduled task which adds a job to the job queue. This is, for instance, how the
+built-in [cleanSessionsTask](/reference/typescript-api/scheduled-tasks/clean-sessions-task) works. This pattern is something you should
+consider if the scheduled task may take a significant amount of time or resources and you want to let the job queue manage that.
+
+It also has the advantage of giving you a record of results for that work that has been put on the job queue, whereas scheduled tasks
+only record that result of the last execution.
+
+
+## A note on @nestjs/schedule
+
+NestJS provides a [dedicated package for scheduling tasks](https://docs.nestjs.com/techniques/task-scheduling), called `@nestjs/schedule`.
+
+You can also use this approach to schedule tasks, but you need to aware of a very important caveat:
+
+:::warning
+When using `@nestjs/schedule`, any method decorated with the `@Cron()` decorator will run
+on _all_ instances of the application. This means it will run on the server _and_ on the
+worker. If you are running multiple instances, then it will run on all instances.
+
+This is the specific issue solved by the built-in ScheduledTask system described above.
+Therefore it is not recommended to use the `@nestjs/schedule` package under normal
+circumstances.
+:::
+
+You can, for instance, inject the [ProcessContext](/reference/typescript-api/common/process-context) into the service and check if the current instance is the worker or the server.
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { Cron } from '@nestjs/schedule';
+
+@Injectable()
+export class SitemapService {
+    constructor(private processContext: ProcessContext) {}
+
+    @Cron('0 0 * * *')
+    async generateSitemap() {
+        // highlight-start
+        if (this.processContext.isWorker) {
+            // Only run on the worker
+            await this.triggerGenerate();
+        }
+        // highlight-end
+    }
+}
+```
+
+The above code will run the `generateSitemap()` method every night at midnight, but only on the worker instance.
+
+Again, if you have multiple worker instances running, it would run on all instances.

package/docs/guides/developer-guide/security/index.md

@@ -0,0 +1,264 @@
+---
+title: "Security"
+---
+
+Security of your Vendure application includes considering how to prevent and protect against common security threats such as:
+
+- Data breaches
+- Unauthorized access
+- Attacks aimed at disrupting the service
+
+Vendure itself is designed with security in mind, but you must also consider the security of your own application code, the server environment, and the network architecture.
+
+## Basics
+
+Here are some basic measures you should use to secure your Vendure application. These are not exhaustive, but they are a good starting point.
+
+### Change the default credentials
+
+Do not deploy any public Vendure instance with the default superadmin credentials (`superadmin:superadmin`). Use your hosting platform's environment variables to set a **strong** password for the Superadmin account.
+
+```ts
+import { VendureConfig } from '@vendure/core';
+
+export const config: VendureConfig = {
+  authOptions: {
+    tokenMethod: ['bearer', 'cookie'],
+    superadminCredentials: {
+      identifier: process.env.SUPERADMIN_USERNAME,
+      password: process.env.SUPERADMIN_PASSWORD,
+    },
+  },
+  // ...
+};
+```
+
+### Use the HardenPlugin
+
+It is recommended that you install and configure the [HardenPlugin](/reference/core-plugins/harden-plugin/) for all production deployments. This plugin locks down your schema 
+(disabling introspection and field suggestions) and protects your Shop API against malicious queries that could otherwise overwhelm your server.
+
+Install the plugin:
+
+```sh
+npm install @vendure/harden-plugin
+
+# or
+
+yarn add @vendure/harden-plugin
+```
+
+Then add it to your VendureConfig:
+
+```ts
+import { VendureConfig } from '@vendure/core';
+import { HardenPlugin } from '@vendure/harden-plugin';
+
+const IS_DEV = process.env.APP_ENV === 'dev';
+
+export const config: VendureConfig = {
+  // ...
+  plugins: [
+    HardenPlugin.init({
+      maxQueryComplexity: 500,
+      apiMode: IS_DEV ? 'dev' : 'prod',
+    }),
+    // ...
+  ]
+};
+```
+
+:::info
+For a detailed explanation of how to best configure this plugin, see the [HardenPlugin docs](/reference/core-plugins/harden-plugin/).
+:::
+
+### Harden the AssetServerPlugin
+
+If you are using the [AssetServerPlugin](/reference/core-plugins/asset-server-plugin/), it is possible by default to use the dynamic
+image transform feature to overload the server with requests for new image sizes & formats. To prevent this, you can
+configure the plugin to only allow transformations for the preset sizes, and limited quality levels and formats.
+Since v3.1 we ship the [PresetOnlyStrategy](/reference/core-plugins/asset-server-plugin/preset-only-strategy/) for this purpose, and
+you can also create your own strategies.
+
+```ts
+import { VendureConfig } from '@vendure/core';
+import { AssetServerPlugin, PresetOnlyStrategy } from '@vendure/asset-server-plugin';
+
+export const config: VendureConfig = {
+  // ...
+  plugins: [
+    AssetServerPlugin.init({
+      // ...
+      // highlight-start  
+      imageTransformStrategy: new PresetOnlyStrategy({
+        defaultPreset: 'large',
+        permittedQuality: [0, 50, 75, 85, 95],
+        permittedFormats: ['jpg', 'webp', 'avif'],
+        allowFocalPoint: false,
+      }),
+      // highlight-end
+    }),
+  ]
+};
+```
+
+## OWASP Top Ten Security Assessment
+
+The Open Worldwide Application Security Project (OWASP) is a nonprofit foundation that works to improve the security of software.
+
+It publishes a top 10 list of common web application vulnerabilities: https://owasp.org/Top10
+
+This section assesses Vendure against this list, stating what is covered **out of the box** (built in to the framework or easily configurable) and what needs to be **additionally considered.**
+
+### 1. Broken Access Control
+
+Reference: https://owasp.org/Top10/A01_2021-Broken_Access_Control/
+
+Out of the box:
+
+- Vendure uses role-based access control
+- We deny by default for non-public API requests
+- Built-in CORS controls for session cookies
+- Directory listing is not possible via default configuration (e.g. exposing web root dir contents)
+- Stateful session identifiers should be invalidated on the server after logout. On logout we delete all session records from the DB & session cache.
+
+To consider:
+
+- Rate limit API and controller access to minimize the harm from automated attack tooling.
+
+### 2. Cryptographic Failures
+
+Reference: https://owasp.org/Top10/A02_2021-Cryptographic_Failures/
+
+Out of the box:
+
+- Vendure defaults to bcrypt with 12 salt rounds for storing passwords. This strategy is configurable if security requirements mandate alternative algorithms.
+- No deprecated hash functions (SHA1, MD5) are used in security-related contexts (only for things like creating cache keys).
+- Payment information is not stored in Vendure by default. Payment integrations rely on the payment provider to store all sensitive data.
+
+To consider:
+
+- The Vendure server will not use TLS be default. The usual configuration is to handle this at the gateway level on your production platform.
+- If a network caching layer is used (e.g. Stellate), ensure it is configured to not cache user-related data (customer details, active order etc)
+
+### 3. Injection
+
+Reference: https://owasp.org/Top10/A03_2021-Injection/
+
+Out of the box:
+
+- GraphQL has built-in validation of incoming data
+- All database operations are parameterized - no string concatenation using user-supplied data.
+- List queries apply default limits to prevent mass disclosure of records.
+
+To consider:
+
+- If using custom fields, you should consider defining a validation function to prevent bad data from getting into the database.
+
+### 4. Insecure Design
+
+Reference: https://owasp.org/Top10/A04_2021-Insecure_Design/
+
+Out of the box:
+
+- Use of established libraries for the critical underlying components: NestJS, TypeORM, Angular.
+- End-to-end tests of security-related flows such as authentication, verification, and RBAC permissions controls.
+- Harden plugin provides pre-configured protections against common attack vectors targeting GraphQL APIs.
+
+To consider:
+
+- Tiered exposure such as an API gateway which prevents exposure of the Admin API to the public internet.
+- Limit resource usage of Vendure server & worker instances via containerization.
+- Rate limiting & other network-level protections (such as Cloudflare) should be considered.
+
+### 5. Security Misconfiguration
+
+Reference: https://owasp.org/Top10/A05_2021-Security_Misconfiguration/
+
+Out of the box:
+
+- Single point of configuration for the entire application, reducing the chance of misconfiguration.
+- A default setup only requires a database, which means there are few components to configure and harden.
+- Stack traces are not leaked in API errors
+
+To consider:
+
+- Ensure the default superadmin credentials are not used in production
+- Use environment variables to turn off development features such as the GraphQL playground
+- Use the HardenPlugin in production to automatically turn of development features and restrict system information leaking via API.
+- Use fine-grained permissions and roles for your administrator accounts to reduce the attack surface if an account is compromised.
+
+### 6. Vulnerable and Outdated Components
+
+Reference: https://owasp.org/Top10/A06_2021-Vulnerable_and_Outdated_Components/
+
+Out of the box:
+
+- All dependencies are updated to current versions with each minor release
+- Modular design limits the number of dependencies for core packages.
+- Automated code & dependency scanning is used in the Vendure repo
+
+To consider:
+
+- Run your own audits on your code base.
+- Use version override mechanisms if needed to patch and critical Vendure dependencies that did not yet get updated.
+
+### 7. Identification and Authentication Failures
+
+Reference: https://owasp.org/Top10/A07_2021-Identification_and_Authentication_Failures/
+
+Out of the box:
+
+- Valid usernames are not leaked via mechanisms such as account reset
+- Does not permit "knowlege-based" account recovery
+- Uses strong password hashing (bcrypt with 12 salt rounds)
+- Session identifiers are not exposed in API urls (instead we use headers/cookies)
+- New session tokens always regenerated after successful login
+- Sessions deleted during logout
+- Cryptographically-strong, high-entropy session tokens are used (crypto.randomBytes API)
+
+To consider:
+
+- Implementing a multi-factor authentication flow
+- Do not use default superadmin credentials in production
+- Implementing a custom PasswordValidationStrategy to disallow weak/common passwords
+- Subscribe to AttemptedLoginEvent to implement detection of brute-force attacks
+
+### 8. Software and Data Integrity Failures
+
+Reference: https://owasp.org/Top10/A08_2021-Software_and_Data_Integrity_Failures/
+
+To consider:
+
+- Exercise caution when introducing new dependencies to your project.
+- Do not use untrusted Vendure plugins. Where possible review the code prior to use.
+- Exercise caution if using auto-updating mechanisms for dependencies.
+- If storing serialized data in custom fields, implement validation to prevent untrusted data getting into the database.
+- Evaluate your CI/CD pipeline against the OWASP recommendations for this point
+
+### 9. Security Logging and Monitoring Failures
+
+Reference: https://owasp.org/Top10/A09_2021-Security_Logging_and_Monitoring_Failures/
+
+Out of the box:
+
+- APIs for integrating logging & monitoring tools & services, e.g. configurable Logger interface & ErrorHandlerStrategy
+- Official Sentry integration for application performance monitoring
+
+To consider:
+
+- Integrate with dedicated logging tools for improved log management
+- Integrate with monitoring tools such as Sentry
+- Use the EventBus to monitor events such as repeated failed login attempts and high-value orders
+
+### 10. Server-Side Request Forgery (SSRF)
+
+Reference: [https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_(SSRF)/](https://owasp.org/Top10/A10_2021-Server-Side_Request_Forgery_%28SSRF%29/)
+
+Out of the box:
+
+- By default Vendure does not rely on requests to remote servers for core functionality
+
+To consider:
+
+- Review the OWASP recommendations against your network architecture