docs(core): Document creating a RequestContext for a specific user

docs/docs/guides/developer-guide/plugins/index.mdx

@@ -111,6 +111,34 @@ If you have code that should only run either in the server context or worker con
 you can inject the [ProcessContext provider](/reference/typescript-api/common/process-context/).
 :::
 
+A plugin can implement these hooks directly, rather than only on the providers it defines:
+
+```ts title="src/plugins/my-plugin/my.plugin.ts"
+import { OnApplicationBootstrap } from '@nestjs/common';
+import { PluginCommonModule, ProcessContext, VendurePlugin } from '@vendure/core';
+
+@VendurePlugin({
+    imports: [PluginCommonModule],
+})
+export class MyPlugin implements OnApplicationBootstrap {
+    constructor(private processContext: ProcessContext) {}
+
+    async onApplicationBootstrap() {
+        // Without this guard the work below would run twice: once in the
+        // server and once in the worker.
+        if (this.processContext.isWorker) {
+            return;
+        }
+        // Do something on the server only
+    }
+}
+```
+
+If that startup work needs to call Vendure's services, it will need a `RequestContext`, which
+outside of the request-response cycle you create yourself — see
+[Creating a RequestContext](/guides/developer-guide/stand-alone-scripts/#creating-a-requestcontext),
+including how to give it a user so that permission checks pass.
+
 ### Configure
 
 Another hook that is not strictly a lifecycle hook, but which can be useful to know is the [`configure` method](https://docs.nestjs.com/middleware#applying-middleware) which is

docs/docs/guides/developer-guide/stand-alone-scripts/index.mdx

@@ -113,3 +113,49 @@ async function getProductCount() {
     const { totalItems } = await productService.findAll(ctx, {take: 0});
 }
 ```
+
+### Acting as a specific user
+
+The context above is anonymous — it carries no user, and therefore no permissions. That is fine for
+services which do not check them, but services such as the [`RoleService`](/reference/typescript-api/services/role-service/)
+will reject it.
+
+To act as a particular user, pass that user in the `user` option. The example below loads the
+superadmin, which is usually what you want for an administrative script:
+
+```ts title="src/get-product-count.ts"
+// ...
+import { ConfigService, RequestContextService, TransactionalConnection, User } from '@vendure/core';
+
+async function getProductCount() {
+    const { app } = await bootstrapWorker(config);
+
+    // Load the user the script should act as. Any User will do — the superadmin is used here
+    // because an administrative script generally needs unrestricted permissions.
+    const { superadminCredentials } = app.get(ConfigService).authOptions; // [!code highlight]
+    const superAdminUser = await app // [!code highlight]
+        .get(TransactionalConnection) // [!code highlight]
+        .rawConnection.getRepository(User) // [!code highlight]
+        .findOneOrFail({ // [!code highlight]
+            where: { identifier: superadminCredentials.identifier }, // [!code highlight]
+            // The roles (and their channels) must be loaded, or the resulting context // [!code highlight]
+            // has the user's id but no permissions. // [!code highlight]
+            relations: { roles: { channels: true } }, // [!code highlight]
+        }); // [!code highlight]
+
+    const ctx = await app.get(RequestContextService).create({
+        apiType: 'admin',
+        user: superAdminUser, // [!code highlight]
+    });
+
+    // `ctx` now carries the superadmin's permissions, so permission-checking
+    // services will accept it.
+}
+```
+
+:::note
+Loading the `roles` relation (and its `channels`) is what gives the context its permissions. Omit
+it and the context still has the user's id — enough for services that reload the user by id, but
+its `channelPermissions` are empty, so any check that reads them directly (for example the entity
+access-control checks behind `connection.getRepository(ctx, Entity)`) will deny access.
+:::

docs/docs/reference/typescript-api/request/request-context-service.mdx

@@ -30,6 +30,25 @@ class RequestContextService {
 Creates a RequestContext based on the config provided. This can be useful when interacting
 with services outside the request-response cycle, for example in stand-alone scripts or in
 worker jobs.
+
+Without a `user`, the resulting context is anonymous and carries no permissions, which
+services that perform permission checks will reject. Pass the `User` the context should act
+as — commonly the superadmin for administrative scripts:
+
+```ts
+const { superadminCredentials } = this.configService.authOptions;
+const superAdminUser = await this.connection.rawConnection.getRepository(User).findOneOrFail({
+    where: { identifier: superadminCredentials.identifier },
+    // The roles (and their channels) must be loaded, or the resulting context
+    // has the user's id but no permissions.
+    relations: { roles: { channels: true } },
+});
+
+const ctx = await this.requestContextService.create({
+    apiType: 'admin',
+    user: superAdminUser,
+});
+```
 ### fromRequest
 
 <MemberInfo kind="method" type={`(req: Request, info?: GraphQLResolveInfo, requiredPermissions?: <a href='/reference/typescript-api/common/permission#permission'>Permission</a>[], session?: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => Promise<<a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>>`}   />

packages/core/src/service/helpers/request-context/request-context.service.ts

@@ -36,6 +36,25 @@ export class RequestContextService {
      * with services outside the request-response cycle, for example in stand-alone scripts or in
      * worker jobs.
      *
+     * Without a `user`, the resulting context is anonymous and carries no permissions, which
+     * services that perform permission checks will reject. Pass the `User` the context should act
+     * as — commonly the superadmin for administrative scripts:
+     *
+     * ```ts
+     * const { superadminCredentials } = this.configService.authOptions;
+     * const superAdminUser = await this.connection.rawConnection.getRepository(User).findOneOrFail({
+     *     where: { identifier: superadminCredentials.identifier },
+     *     // The roles (and their channels) must be loaded, or the resulting context
+     *     // has the user's id but no permissions.
+     *     relations: { roles: { channels: true } },
+     * });
+     *
+     * const ctx = await this.requestContextService.create({
+     *     apiType: 'admin',
+     *     user: superAdminUser,
+     * });
+     * ```
+     *
      * @since 1.5.0
      */
     async create(config: {