@vendure/docs 0.0.0-202601161541

package/docs/reference/typescript-api/auth/auth-options.md

@@ -0,0 +1,165 @@
+---
+title: "AuthOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## AuthOptions
+
+<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="360" packageName="@vendure/core" />
+
+The AuthOptions define how authentication and authorization is managed.
+
+```ts title="Signature"
+interface AuthOptions {
+    disableAuth?: boolean;
+    tokenMethod?: 'cookie' | 'bearer' | ReadonlyArray<'cookie' | 'bearer'>;
+    cookieOptions?: CookieOptions;
+    authTokenHeaderKey?: string;
+    sessionDuration?: string | number;
+    sessionCacheStrategy?: SessionCacheStrategy;
+    sessionCacheTTL?: string | number;
+    requireVerification?: boolean;
+    verificationTokenDuration?: string | number;
+    superadminCredentials?: SuperadminCredentials;
+    shopAuthenticationStrategy?: AuthenticationStrategy[];
+    adminAuthenticationStrategy?: AuthenticationStrategy[];
+    customPermissions?: PermissionDefinition[];
+    passwordHashingStrategy?: PasswordHashingStrategy;
+    passwordValidationStrategy?: PasswordValidationStrategy;
+    verificationTokenStrategy?: VerificationTokenStrategy;
+}
+```
+
+<div className="members-wrapper">
+
+### disableAuth
+
+<MemberInfo kind="property" type={`boolean`} default={`false`}   />
+
+Disable authentication & permissions checks.
+NEVER set the to true in production. It exists
+only to aid certain development tasks.
+### tokenMethod
+
+<MemberInfo kind="property" type={`'cookie' | 'bearer' | ReadonlyArray&#60;'cookie' | 'bearer'&#62;`} default={`'cookie'`}   />
+
+Sets the method by which the session token is delivered and read.
+
+* 'cookie': Upon login, a 'Set-Cookie' header will be returned to the client, setting a
+  cookie containing the session token. A browser-based client (making requests with credentials)
+  should automatically send the session cookie with each request.
+* 'bearer': Upon login, the token is returned in the response and should be then stored by the
+  client app. Each request should include the header `Authorization: Bearer <token>`.
+
+Note that if the bearer method is used, Vendure will automatically expose the configured
+`authTokenHeaderKey` in the server's CORS configuration (adding `Access-Control-Expose-Headers: vendure-auth-token`
+by default).
+
+From v1.2.0 it is possible to specify both methods as a tuple: `['cookie', 'bearer']`.
+### cookieOptions
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/cookie-options#cookieoptions'>CookieOptions</a>`}   />
+
+Options related to the handling of cookies when using the 'cookie' tokenMethod.
+### authTokenHeaderKey
+
+<MemberInfo kind="property" type={`string`} default={`'vendure-auth-token'`}   />
+
+Sets the header property which will be used to send the auth token when using the 'bearer' method.
+### sessionDuration
+
+<MemberInfo kind="property" type={`string | number`} default={`'1y'`}   />
+
+Session duration, i.e. the time which must elapse from the last authenticated request
+after which the user must re-authenticate.
+
+If passed as a number should represent milliseconds and if passed as a string describes a time span per
+[zeit/ms](https://github.com/zeit/ms.js).  Eg: `60`, `'2 days'`, `'10h'`, `'7d'`
+### sessionCacheStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a>`} default={`<a href='/reference/typescript-api/auth/default-session-cache-strategy#defaultsessioncachestrategy'>DefaultSessionCacheStrategy</a>`}   />
+
+This strategy defines how sessions will be cached. By default, since v3.1.0, sessions are cached using
+the underlying cache strategy defined in the <a href='/reference/typescript-api/configuration/system-options#systemoptions'>SystemOptions</a>`.cacheStrategy`.
+### sessionCacheTTL
+
+<MemberInfo kind="property" type={`string | number`} default={`300`}   />
+
+The "time to live" of a given item in the session cache. This determines the length of time that a cache entry
+is kept before being considered "stale" and being replaced with fresh data taken from the database.
+
+If passed as a number should represent seconds and if passed as a string describes a time span per
+[zeit/ms](https://github.com/zeit/ms.js). Eg: `60`, `'2 days'`, `'10h'`, `'7d'`
+### requireVerification
+
+<MemberInfo kind="property" type={`boolean`} default={`true`}   />
+
+Determines whether new User accounts require verification of their email address.
+
+If set to "true", the customer will be required to verify their email address using a verification token
+they receive in their email. See the `registerCustomerAccount` mutation for more details on the verification behavior.
+### verificationTokenDuration
+
+<MemberInfo kind="property" type={`string | number`} default={`'7d'`}   />
+
+Sets the length of time that a verification token is valid for, after which the verification token must be refreshed.
+
+If passed as a number should represent milliseconds and if passed as a string describes a time span per
+[zeit/ms](https://github.com/zeit/ms.js).  Eg: `60`, `'2 days'`, `'10h'`, `'7d'`
+### superadminCredentials
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/superadmin-credentials#superadmincredentials'>SuperadminCredentials</a>`}   />
+
+Configures the credentials to be used to create a superadmin
+### shopAuthenticationStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a>[]`} default={`<a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>`}   />
+
+Configures one or more AuthenticationStrategies which defines how authentication
+is handled in the Shop API.
+### adminAuthenticationStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/authentication-strategy#authenticationstrategy'>AuthenticationStrategy</a>[]`} default={`<a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>`}   />
+
+Configures one or more AuthenticationStrategy which defines how authentication
+is handled in the Admin API.
+### customPermissions
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/permission-definition#permissiondefinition'>PermissionDefinition</a>[]`} default={`[]`}   />
+
+Allows custom Permissions to be defined, which can be used to restrict access to custom
+GraphQL resolvers defined in plugins.
+### passwordHashingStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/password-hashing-strategy#passwordhashingstrategy'>PasswordHashingStrategy</a>`} default={`<a href='/reference/typescript-api/auth/bcrypt-password-hashing-strategy#bcryptpasswordhashingstrategy'>BcryptPasswordHashingStrategy</a>`}  since="1.3.0"  />
+
+Allows you to customize the way passwords are hashed when using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.
+### passwordValidationStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/password-validation-strategy#passwordvalidationstrategy'>PasswordValidationStrategy</a>`} default={`<a href='/reference/typescript-api/auth/default-password-validation-strategy#defaultpasswordvalidationstrategy'>DefaultPasswordValidationStrategy</a>`}  since="1.5.0"  />
+
+Allows you to set a custom policy for passwords when using the <a href='/reference/typescript-api/auth/native-authentication-strategy#nativeauthenticationstrategy'>NativeAuthenticationStrategy</a>.
+By default, it uses the <a href='/reference/typescript-api/auth/default-password-validation-strategy#defaultpasswordvalidationstrategy'>DefaultPasswordValidationStrategy</a>, which will impose a minimum length
+of four characters. To improve security for production, you are encouraged to specify a more strict
+policy, which you can do like this:
+
+*Example*
+
+```ts
+{
+  passwordValidationStrategy: new DefaultPasswordValidationStrategy({
+    // Minimum eight characters, at least one letter and one number
+    regexp: /^(?=.*[A-Za-z])(?=.*\d)[A-Za-z\d]{8,}$/,
+  }),
+}
+```
+### verificationTokenStrategy
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/auth/verification-token-strategy#verificationtokenstrategy'>VerificationTokenStrategy</a>`} default={`<a href='/reference/typescript-api/auth/default-verification-token-strategy#defaultverificationtokenstrategy'>DefaultVerificationTokenStrategy</a>`}  since="3.2.0"  />
+
+Allows you to customize the way verification tokens are generated.
+
+
+</div>

package/docs/reference/typescript-api/auth/authentication-strategy.md

@@ -0,0 +1,97 @@
+---
+title: "AuthenticationStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## AuthenticationStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/auth/authentication-strategy.ts" sourceLine="23" packageName="@vendure/core" />
+
+An AuthenticationStrategy defines how a User (which can be a Customer in the Shop API or
+and Administrator in the Admin API) may be authenticated.
+
+Real-world examples can be found in the [Authentication guide](/guides/core-concepts/auth/).
+
+:::info
+
+This is configured via the `authOptions.shopAuthenticationStrategy` and `authOptions.adminAuthenticationStrategy`
+properties of your VendureConfig.
+
+:::
+
+```ts title="Signature"
+interface AuthenticationStrategy<Data = unknown> extends InjectableStrategy {
+    readonly name: string;
+    defineInputType(): DocumentNode;
+    authenticate(ctx: RequestContext, data: Data): Promise<User | false | string>;
+    onLogOut?(ctx: RequestContext, user: User): Promise<void>;
+}
+```
+* Extends: <code><a href='/reference/typescript-api/common/injectable-strategy#injectablestrategy'>InjectableStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### name
+
+<MemberInfo kind="property" type={`string`}   />
+
+The name of the strategy, for example `'facebook'`, `'google'`, `'keycloak'`.
+### defineInputType
+
+<MemberInfo kind="method" type={`() => DocumentNode`}   />
+
+Defines the type of the GraphQL Input object expected by the `authenticate`
+mutation. The final input object will be a map, with the key being the name
+of the strategy. The shape of the input object should match the generic `Data`
+type argument.
+
+*Example*
+
+For example, given the following:
+
+```ts
+defineInputType() {
+  return gql`
+     input MyAuthInput {
+       token: String!
+     }
+  `;
+}
+```
+
+assuming the strategy name is "my_auth", then the resulting call to `authenticate`
+would look like:
+
+```GraphQL
+authenticate(input: {
+  my_auth: {
+    token: "foo"
+  }
+}) {
+  # ...
+}
+```
+
+**Note:** if more than one graphql `input` type is being defined (as in a nested input type), then
+the _first_ input will be assumed to be the top-level input.
+### authenticate
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, data: Data) => Promise&#60;<a href='/reference/typescript-api/entities/user#user'>User</a> | false | string&#62;`}   />
+
+Used to authenticate a user with the authentication provider. This method
+will implement the provider-specific authentication logic, and should resolve to either a
+<a href='/reference/typescript-api/entities/user#user'>User</a> object on success, or `false | string` on failure.
+A `string` return could be used to describe what error happened, otherwise `false` to an unknown error.
+### onLogOut
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, user: <a href='/reference/typescript-api/entities/user#user'>User</a>) => Promise&#60;void&#62;`}   />
+
+Called when a user logs out, and may perform any required tasks
+related to the user logging out with the external provider.
+
+
+</div>

package/docs/reference/typescript-api/auth/bcrypt-password-hashing-strategy.md

@@ -0,0 +1,38 @@
+---
+title: "BcryptPasswordHashingStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## BcryptPasswordHashingStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/auth/bcrypt-password-hashing-strategy.ts" sourceLine="12" packageName="@vendure/core" since="1.3.0" />
+
+A hashing strategy which uses bcrypt (https://en.wikipedia.org/wiki/Bcrypt) to hash plaintext password strings.
+
+```ts title="Signature"
+class BcryptPasswordHashingStrategy implements PasswordHashingStrategy {
+    hash(plaintext: string) => Promise<string>;
+    check(plaintext: string, hash: string) => Promise<boolean>;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/auth/password-hashing-strategy#passwordhashingstrategy'>PasswordHashingStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### hash
+
+<MemberInfo kind="method" type={`(plaintext: string) => Promise&#60;string&#62;`}   />
+
+
+### check
+
+<MemberInfo kind="method" type={`(plaintext: string, hash: string) => Promise&#60;boolean&#62;`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/auth/cookie-options.md

@@ -0,0 +1,108 @@
+---
+title: "CookieOptions"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## CookieOptions
+
+<GenerationInfo sourceFile="packages/core/src/config/vendure-config.ts" sourceLine="255" packageName="@vendure/core" />
+
+Options for the handling of the cookies used to track sessions (only applicable if
+`authOptions.tokenMethod` is set to `'cookie'`). These options are passed directly
+to the Express [cookie-session middleware](https://github.com/expressjs/cookie-session).
+
+```ts title="Signature"
+interface CookieOptions {
+    name?: string | { shop: string; admin: string };
+    secret?: string;
+    path?: string;
+    domain?: string;
+    sameSite?: 'strict' | 'lax' | 'none' | boolean;
+    secure?: boolean;
+    secureProxy?: boolean;
+    httpOnly?: boolean;
+    signed?: boolean;
+    overwrite?: boolean;
+    maxAge?: number;
+    expires?: Date;
+}
+```
+
+<div className="members-wrapper">
+
+### name
+
+<MemberInfo kind="property" type={`string | { shop: string; admin: string }`} default={`'session'`}   />
+
+The name of the cookies to set.
+If set to a string, both cookies for the Admin API and Shop API will have the same name.
+If set as an object, it makes it possible to give different names to the Admin API and the Shop API cookies
+### secret
+
+<MemberInfo kind="property" type={`string`} default={`(random character string)`}   />
+
+The secret used for signing the session cookies for authenticated users. Only applies
+tokenMethod is set to 'cookie'.
+
+In production applications, this should not be stored as a string in
+source control for security reasons, but may be loaded from an external
+file not under source control, or from an environment variable, for example.
+### path
+
+<MemberInfo kind="property" type={`string`} default={`'/'`}   />
+
+a string indicating the path of the cookie.
+### domain
+
+<MemberInfo kind="property" type={`string`}   />
+
+a string indicating the domain of the cookie (no default).
+### sameSite
+
+<MemberInfo kind="property" type={`'strict' | 'lax' | 'none' | boolean`} default={`false`}   />
+
+a boolean or string indicating whether the cookie is a "same site" cookie (false by default). This can be set to 'strict',
+'lax', 'none', or true (which maps to 'strict').
+### secure
+
+<MemberInfo kind="property" type={`boolean`}   />
+
+a boolean indicating whether the cookie is only to be sent over HTTPS (false by default for HTTP, true by default for HTTPS).
+### secureProxy
+
+<MemberInfo kind="property" type={`boolean`}   />
+
+a boolean indicating whether the cookie is only to be sent over HTTPS (use this if you handle SSL not in your node process).
+### httpOnly
+
+<MemberInfo kind="property" type={`boolean`} default={`true`}   />
+
+a boolean indicating whether the cookie is only to be sent over HTTP(S), and not made available to client JavaScript (true by default).
+### signed
+
+<MemberInfo kind="property" type={`boolean`}   />
+
+a boolean indicating whether the cookie is to be signed (true by default). If this is true, another cookie of the same name with the .sig
+suffix appended will also be sent, with a 27-byte url-safe base64 SHA1 value representing the hash of cookie-name=cookie-value against the
+first Keygrip key. This signature key is used to detect tampering the next time a cookie is received.
+### overwrite
+
+<MemberInfo kind="property" type={`boolean`}   />
+
+a boolean indicating whether to overwrite previously set cookies of the same name (true by default). If this is true, all cookies set during
+the same request with the same name (regardless of path or domain) are filtered out of the Set-Cookie header when setting this cookie.
+### maxAge
+
+<MemberInfo kind="property" type={`number`}  since="2.2.0"  />
+
+A number representing the milliseconds from Date.now() for expiry
+### expires
+
+<MemberInfo kind="property" type={`Date`}  since="2.2.0"  />
+
+a Date object indicating the cookie's expiration date (expires at the end of session by default).
+
+
+</div>

package/docs/reference/typescript-api/auth/default-password-validation-strategy.md

@@ -0,0 +1,44 @@
+---
+title: "DefaultPasswordValidationStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## DefaultPasswordValidationStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/auth/default-password-validation-strategy.ts" sourceLine="18" packageName="@vendure/core" since="1.5.0" />
+
+The DefaultPasswordValidationStrategy allows you to specify a minimum length and/or
+a regular expression to match passwords against. The default `maxLength` is `72`.
+
+TODO:
+By default, the `minLength` will be set to `4`. This is rather permissive and is only
+this way in order to reduce the risk of backward-compatibility breaks. In the next major version
+this default will be made more strict.
+
+```ts title="Signature"
+class DefaultPasswordValidationStrategy implements PasswordValidationStrategy {
+    constructor(options: { minLength?: number; maxLength?: number; regexp?: RegExp })
+    validate(ctx: RequestContext, password: string) => boolean | string;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/auth/password-validation-strategy#passwordvalidationstrategy'>PasswordValidationStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### constructor
+
+<MemberInfo kind="method" type={`(options: { minLength?: number; maxLength?: number; regexp?: RegExp }) => DefaultPasswordValidationStrategy`}   />
+
+
+### validate
+
+<MemberInfo kind="method" type={`(ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, password: string) => boolean | string`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/auth/default-session-cache-strategy.md

@@ -0,0 +1,73 @@
+---
+title: "DefaultSessionCacheStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## DefaultSessionCacheStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/session-cache/default-session-cache-strategy.ts" sourceLine="17" packageName="@vendure/core" since="3.1.0" />
+
+The default <a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a> delegates to the configured
+<a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a> to store the session data. This should be suitable
+for most use-cases, assuming you select a suitable <a href='/reference/typescript-api/cache/cache-strategy#cachestrategy'>CacheStrategy</a>
+
+```ts title="Signature"
+class DefaultSessionCacheStrategy implements SessionCacheStrategy {
+    protected cacheService: CacheService;
+    constructor(options?: {
+            ttl?: number;
+            cachePrefix?: string;
+        })
+    init(injector: Injector) => ;
+    set(session: CachedSession) => Promise<void>;
+    get(sessionToken: string) => Promise<CachedSession | undefined>;
+    delete(sessionToken: string) => void | Promise<void>;
+    clear() => Promise<void>;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/auth/session-cache-strategy#sessioncachestrategy'>SessionCacheStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### cacheService
+
+<MemberInfo kind="property" type={`<a href='/reference/typescript-api/cache/cache-service#cacheservice'>CacheService</a>`}   />
+
+
+### constructor
+
+<MemberInfo kind="method" type={`(options?: {             ttl?: number;             cachePrefix?: string;         }) => DefaultSessionCacheStrategy`}   />
+
+
+### init
+
+<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />
+
+
+### set
+
+<MemberInfo kind="method" type={`(session: <a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a>) => Promise&#60;void&#62;`}   />
+
+
+### get
+
+<MemberInfo kind="method" type={`(sessionToken: string) => Promise&#60;<a href='/reference/typescript-api/auth/session-cache-strategy#cachedsession'>CachedSession</a> | undefined&#62;`}   />
+
+
+### delete
+
+<MemberInfo kind="method" type={`(sessionToken: string) => void | Promise&#60;void&#62;`}   />
+
+
+### clear
+
+<MemberInfo kind="method" type={`() => Promise&#60;void&#62;`}   />
+
+
+
+
+</div>

package/docs/reference/typescript-api/auth/default-verification-token-strategy.md

@@ -0,0 +1,47 @@
+---
+title: "DefaultVerificationTokenStrategy"
+generated: true
+---
+<!-- This file was generated from the Vendure source. Do not modify. Instead, re-run the "docs:build" script -->
+
+
+## DefaultVerificationTokenStrategy
+
+<GenerationInfo sourceFile="packages/core/src/config/auth/default-verification-token-strategy.ts" sourceLine="20" packageName="@vendure/core" since="3.2.0" />
+
+The default VerificationTokenStrategy which generates a token consisting of the
+base64-encoded current time concatenated with a random id. The token is considered
+valid if the current time is within the configured `verificationTokenDuration` of the
+time encoded in the token.
+
+```ts title="Signature"
+class DefaultVerificationTokenStrategy implements VerificationTokenStrategy {
+    init(injector: Injector) => ;
+    generateVerificationToken(_ctx: RequestContext) => string;
+    verifyVerificationToken(_ctx: RequestContext, token: string) => boolean;
+}
+```
+* Implements: <code><a href='/reference/typescript-api/auth/verification-token-strategy#verificationtokenstrategy'>VerificationTokenStrategy</a></code>
+
+
+
+<div className="members-wrapper">
+
+### init
+
+<MemberInfo kind="method" type={`(injector: <a href='/reference/typescript-api/common/injector#injector'>Injector</a>) => `}   />
+
+
+### generateVerificationToken
+
+<MemberInfo kind="method" type={`(_ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>) => string`}   />
+
+
+### verifyVerificationToken
+
+<MemberInfo kind="method" type={`(_ctx: <a href='/reference/typescript-api/request/request-context#requestcontext'>RequestContext</a>, token: string) => boolean`}   />
+
+
+
+
+</div>