@solidxai/core 0.1.16-beta.1 → 0.1.16-beta.3

package/src/enums/signup-intent.enum.ts

@@ -0,0 +1,22 @@
+/**
+ * Declares what kind of user a signup call is creating.
+ *
+ * The distinction is a domain one, not a mechanical one:
+ *
+ * - a base `User` is someone who administers the system - the seeded `sa`, users
+ *   created from the admin console;
+ * - an extension user is someone who *uses* the app - public signup, OTP
+ *   registration, OAuth sign-in, and the extension model's own CRUD form.
+ *
+ * Each call site states which it means. Nothing inspects the request body to
+ * decide, so the same payload posted to two endpoints cannot produce two
+ * different kinds of user.
+ */
+export enum SignupIntent {
+  /** Public self-registration: an anonymous visitor creating their own account. */
+  SelfRegistration = 'self-registration',
+  /** Explicit create of the extension model, via its generated CRUD form. */
+  ExtensionModel = 'extension-model',
+  /** Admin console and internal callers: a plain core user. */
+  CoreUser = 'core-user',
+}

package/src/index.ts

@@ -193,6 +193,7 @@ export * from './entities/workflow-secret.entity'
 
 export * from './enums/auth-type.enum'
 export * from './enums/legacy-table-type.enum'
+export * from './enums/signup-intent.enum'
 export * from './decorators/disallow-in-production.decorator'
 
 export * from './filters/http-exception.filter'

package/src/seeders/module-metadata-seeder.service.ts

@@ -41,6 +41,7 @@ import { User } from '../entities/user.entity';
 import { MENU_ROLE_JOIN_TABLE_NAME, MENU_ROLE_JOIN_TABLE_NAME_MENU_COL, MENU_ROLE_JOIN_TABLE_NAME_ROLE_COL } from '../dtos/create-menu-item-metadata.dto';
 import { DEFAULT_SA_PASSWORD } from '../dtos/create-user.dto';
 import { SignUpDto } from '../dtos/sign-up.dto';
+import { SignupIntent } from '../enums/signup-intent.enum';
 import {
     ADMIN_ROLE_NAME,
     ALLOWED_TO_EXPORT_ROLE_NAME,
@@ -86,6 +87,33 @@ import { EventDetails, EventType, ModuleMetadataSeederEventPayload } from 'src/i
  * - View/action preload + in-memory no-op detection so unchanged rows skip save() entirely.
  * - Menu entity no-op detection, though menu relation lookups are still mostly serial and remain a future candidate.
  */
+
+/**
+ * A user entry in seed metadata.
+ *
+ * The array is genuinely mixed: core seeds `sa` (a technical user), while an app's
+ * module metadata can seed its own users - an "Operations User" and the like, which
+ * are app users and belong on the extension entity. One intent for the whole list
+ * cannot express that, so each entry declares its own.
+ *
+ * Extends SignUpDto with an index signature because a flagged entry carries the
+ * extension model's own fields (`userType`, relation keys) straight through to the
+ * provider.
+ */
+type SeedUserSpec = SignUpDto & {
+    /**
+     * Seed through the registered IExtensionUserCreationProvider, producing the app's
+     * extension entity instead of a base `User`. Absent means a base `User`, so
+     * existing metadata is unaffected.
+     *
+     * `roles` is ignored on a flagged entry - the provider derives them from the
+     * extension fields, as it does on the model's own CRUD form.
+     */
+    isExtensionUser?: boolean;
+    isAllowedToGenerateApiKeys?: boolean;
+    [key: string]: any;
+};
+
 @Injectable()
 export class ModuleMetadataSeederService {
     private readonly adminPermissionExclusionPrefixes = [
@@ -758,7 +786,7 @@ export class ModuleMetadataSeederService {
 
     // Ok
     private async seedUsers(overallMetadata: any): Promise<{ pruned: number; upserted: number }> {
-        const users = this.getSeedArray<SignUpDto>(overallMetadata?.users);
+        const users = this.getSeedArray<SeedUserSpec>(overallMetadata?.users);
         // usersDetail = users;
         await this.timeOperation('handle-users', () => this.handleSeedUsers(users), {
             moduleName: overallMetadata?.moduleMetadata?.name,
@@ -1543,13 +1571,13 @@ export class ModuleMetadataSeederService {
     }
 
     // OK
-    private async handleSeedUsers(users: SignUpDto[]) {
+    private async handleSeedUsers(users: SeedUserSpec[]) {
         if (!users) {
             return;
         }
 
         for (let l = 0; l < users.length; l++) {
-            const user: SignUpDto = users[l];
+            const user: SeedUserSpec = users[l];
             const isSystemAdminUser = user.username === 'sa';
             let exisitingUser = await this.timeOperation('user-find-by-username', () => this.userService.findOneByUsername(user.username), {
                 component: 'users',
@@ -1561,10 +1589,15 @@ export class ModuleMetadataSeederService {
                     user.password = DEFAULT_SA_PASSWORD;
                 }
                 if (isSystemAdminUser) {
-                    (user as SignUpDto & { isAllowedToGenerateApiKeys?: boolean }).isAllowedToGenerateApiKeys = true;
+                    user.isAllowedToGenerateApiKeys = true;
                 }
 
-                exisitingUser = await this.timeOperation('user-sign-up', () => this.authenticationService.signUp(user), {
+                // The flag is seeder metadata, not user data - keep it out of the DTO
+                // the provider and performSignUp see.
+                const { isExtensionUser, ...signUpDto } = user;
+                const intent = isExtensionUser ? SignupIntent.ExtensionModel : SignupIntent.CoreUser;
+
+                exisitingUser = await this.timeOperation('user-sign-up', () => this.authenticationService.signUp(signUpDto, null, intent), {
                     component: 'users',
                     serviceCall: 'authenticationService.signUp',
                     details: `username=${user.username}`,

package/src/seeders/module-test-data.service.ts

@@ -10,6 +10,7 @@ import solidCoreMetadata from './seed-data/solid-core-metadata.json';
 import { CreateModuleMetadataDto } from 'src/dtos/create-module-metadata.dto';
 import { CreateModelMetadataDto } from 'src/dtos/create-model-metadata.dto';
 import { MediaStorageProviderType } from 'src/dtos/create-media-storage-provider-metadata.dto';
+import { SignupIntent } from 'src/enums/signup-intent.enum';
 import { getDynamicModuleNamesBasedOnMetadata } from 'src/helpers/module.helper';
 import { SolidRegistry } from 'src/helpers/solid-registry';
 import { InternationalisationHelperService } from 'src/services/internationalisation-helper.service';
@@ -475,7 +476,14 @@ export class ModuleTestDataService {
         continue;
       }
 
-      await authService.signUp({ ...user });
+      // The flag is seeder metadata, not user data - keep it out of the DTO the
+      // provider and performSignUp see.
+      const { isExtensionUser, ...signUpDto } = user;
+      await authService.signUp(
+        signUpDto,
+        null,
+        isExtensionUser ? SignupIntent.ExtensionModel : SignupIntent.CoreUser,
+      );
       this.logger.log(`Created test user "${user.username}"${user.roles?.length ? ` with roles [${user.roles.join(', ')}]` : ''}`);
     }
   }

package/src/services/authentication.service.ts

@@ -36,6 +36,7 @@ import { OTPSignUpDto } from "../dtos/otp-sign-up.dto";
 import { RefreshTokenDto } from "../dtos/refresh-token.dto";
 import { SignInDto } from "../dtos/sign-in.dto";
 import { SignUpDto } from "../dtos/sign-up.dto";
+import { SignupIntent } from "../enums/signup-intent.enum";
 import { User } from "../entities/user.entity";
 import { EventDetails, EventType } from "../interfaces";
 import { ActiveUserData } from "../interfaces/active-user-data.interface";
@@ -67,6 +68,60 @@ interface otp {
   expiresAt: Date;
 }
 
+/** Where a signup's role names come from. */
+enum RolesSource {
+  /**
+   * Ask nobody; returning [] lets performSignUp apply the configured `defaultRole`.
+   *
+   * No intent maps here today - it is kept for paths that deliberately bypass the
+   * provider. OAuth is the live example: its DTO can never carry a discriminator, so
+   * it takes `defaultRole` outright (currently inline in UserService).
+   */
+  Default,
+  /**
+   * `provider.roles(dto)` - and nothing else. Yields [] when no provider is registered
+   * or when the provider declines to name any, which falls through to `defaultRole`.
+   */
+  Provider,
+  /** The caller's own `dto.roles`. */
+  Caller,
+}
+
+/**
+ * The single place that decides, per intent, which entity a signup builds and where
+ * its roles come from.
+ *
+ * Where an extension user provider is registered it is the authority on that app's user
+ * roles, so every provider-backed intent asks it. `defaultRole` is the *fallback* for
+ * when it names none - or when there is no provider at all - not the rule.
+ *
+ * SelfRegistration and ExtensionModel resolve identically today. They stay separate
+ * intents because only SelfRegistration is gated on `allowPublicRegistration`, and
+ * because "an anonymous visitor signing themselves up" and "an admin creating a user
+ * from the model's own form" are different things that may yet need to diverge.
+ *
+ * `useProvider` is computable from `rolesSource` today (`Caller` implies false), but the
+ * two answer different questions - "which entity?" and "which roles?" - that merely
+ * coincide across these intents. Keep both, and change behaviour here, not at a call site.
+ */
+const SIGNUP_POLICY: Record<
+  SignupIntent,
+  { useProvider: boolean; rolesSource: RolesSource }
+> = {
+  [SignupIntent.SelfRegistration]: {
+    useProvider: true,
+    rolesSource: RolesSource.Provider,
+  },
+  [SignupIntent.ExtensionModel]: {
+    useProvider: true,
+    rolesSource: RolesSource.Provider,
+  },
+  [SignupIntent.CoreUser]: {
+    useProvider: false,
+    rolesSource: RolesSource.Caller,
+  },
+};
+
 @Injectable()
 export class AuthenticationService {
   private readonly logger = new Logger(AuthenticationService.name);
@@ -184,52 +239,69 @@ export class AuthenticationService {
     }
   }
 
-  private static readonly SIGNUP_DTO_KEYS = new Set([
-    "username",
-    "email",
-    "password",
-    "fullName",
-    "mobile",
-    "roles",
-    "forcePasswordChange",
-    "isAllowedToGenerateApiKeys",
-    "failedLoginAttempts",
-  ]);
-
   async signUp(
     signUpDto: SignUpDto & Record<string, any>,
     activeUser: ActiveUserData = null,
+    intent: SignupIntent = SignupIntent.SelfRegistration,
   ): Promise<User> {
-    const hasExtensionFields = Object.keys(signUpDto).some(
-      (k) => !AuthenticationService.SIGNUP_DTO_KEYS.has(k),
+    const { useProvider, rolesSource } = SIGNUP_POLICY[intent];
+
+    if (intent === SignupIntent.SelfRegistration) {
+      this.assertPublicRegistrationEnabled();
+    }
+
+    const { entity, repo } = await this.userService.buildSignupTarget(
+      signUpDto,
+      useProvider,
     );
-    if (hasExtensionFields) {
-      const provider = this.solidRegistry.getExtensionUserCreationProvider();
-      if (!provider) {
-        throw new InternalServerErrorException(
-          "No ExtensionUserCreationProvider registered. Register one to handle extension user creation.",
-        );
-      }
-      const entity = await provider.buildExtensionEntity(signUpDto);
-      const effectiveDto = { ...signUpDto, roles: provider.roles(signUpDto) };
-      return this.performSignUp(
-        effectiveDto,
-        entity,
-        provider.repo as Repository<User>,
-        true,
+    const roles = this.resolveSignupRoles(signUpDto, rolesSource);
+
+    return this.performSignUp({ ...signUpDto, roles }, entity, repo);
+  }
+
+  private resolveSignupRoles(
+    dto: Record<string, any>,
+    source: RolesSource,
+  ): string[] {
+    // Only `Caller` reads dto.roles. Anywhere else, roles in the body are ignored -
+    // which is what keeps an anonymous caller from naming their own on a @Public()
+    // endpoint - so say so rather than dropping them silently.
+    if (source !== RolesSource.Caller && dto.roles?.length) {
+      this.logger.warn(
+        `Ignoring caller-supplied roles for "${dto.username}": roles on this path come from ` +
+          (source === RolesSource.Provider
+            ? "the extension user provider"
+            : "the configured defaultRole"),
       );
     }
-    return this.performSignUp(signUpDto, new User(), this.userRepository);
+
+    switch (source) {
+      case RolesSource.Provider:
+        // Sole authority. Reading dto.roles as a preference or fallback would skip
+        // roles(), which is where a provider validates its discriminator, and
+        // CreateUserDto types roles as UpdateRoleMetadataDto[] where performSignUp
+        // expects role-name strings. [] here falls through to `defaultRole`.
+        return (
+          this.solidRegistry
+            .getExtensionUserCreationProvider()
+            ?.roles(dto as any) ?? []
+        );
+
+      case RolesSource.Caller:
+        return dto.roles ?? [];
+
+      case RolesSource.Default:
+        return [];
+    }
   }
 
   private async performSignUp<T extends User>(
     signUpDto: SignUpDto,
     entity: T,
     repo: Repository<T>,
-    preferEntityApiKeyFlag: boolean = false,
   ): Promise<T> {
     try {
-      await this.assertUniqueSignupIdentifiers(signUpDto, repo);
+      await this.assertUniqueSignupIdentifiers(signUpDto);
       await this.metadataValidationService.validateCreateDto("user", signUpDto);
 
       const onForcePasswordChange =
@@ -249,11 +321,11 @@ export class AuthenticationService {
         activateUserOnRegistration,
         onForcePasswordChange,
       );
+      // An explicitly supplied value wins over whatever the entity carries. The
+      // entity's own flag cannot be trusted as a signal: User initialises it to
+      // false, so "the provider set it" is indistinguishable from "nobody set it".
       const privateDto = signUpDto as { isAllowedToGenerateApiKeys?: boolean };
-      if (
-        !preferEntityApiKeyFlag &&
-        privateDto.isAllowedToGenerateApiKeys !== undefined
-      ) {
+      if (privateDto.isAllowedToGenerateApiKeys !== undefined) {
         user.isAllowedToGenerateApiKeys = privateDto.isAllowedToGenerateApiKeys;
       }
       const savedUser = await repo.save(user);
@@ -283,33 +355,41 @@ export class AuthenticationService {
     }
   }
 
-  private async assertUniqueSignupIdentifiers<T extends User>(
+  /**
+   * Always queries the base `User` repository, never the caller's repository.
+   *
+   * `User` is a `@TableInheritance` root, so a child repository scopes every query
+   * to its own discriminator. Checking through one would only compare against users
+   * of the same subtype, and `email`/`mobile` carry non-unique `@Index()` - there is
+   * no database constraint behind them to catch what the query misses. A duplicate
+   * against a base `User` or a sibling subtype would be silently accepted.
+   */
+  private async assertUniqueSignupIdentifiers(
     signUpDto: SignUpDto,
-    repo: Repository<T>,
   ): Promise<void> {
     const username = signUpDto.username?.trim();
     const email = signUpDto.email?.trim();
     const mobile = signUpDto.mobile?.trim();
 
-    const where: FindOptionsWhere<T>[] = [];
+    const where: FindOptionsWhere<User>[] = [];
 
     if (username) {
-      where.push({ username } as FindOptionsWhere<T>);
+      where.push({ username });
     }
 
     if (email) {
-      where.push({ email } as FindOptionsWhere<T>);
+      where.push({ email });
     }
 
     if (mobile) {
-      where.push({ mobile } as FindOptionsWhere<T>);
+      where.push({ mobile });
     }
 
     if (where.length === 0) {
       return;
     }
 
-    const existingUser = await repo.findOne({ where });
+    const existingUser = await this.userRepository.findOne({ where });
 
     if (!existingUser) {
       return;
@@ -401,7 +481,12 @@ export class AuthenticationService {
     }
     user.username = signUpDto.username;
     user.email = signUpDto.email;
-    user.fullName = signUpDto.fullName;
+    // `fullName` is optional on SignUpDto and the stock signup screen only sends it when
+    // showNameFieldsForRegistration is on, so assigning it unconditionally left every
+    // self-registered user with a null display name. `username` is always present -
+    // non-nullable on the entity and @IsNotEmpty() on the DTO - so it is a safe fallback.
+    // `||` rather than `??`: a form posting an empty string means "not supplied" too.
+    user.fullName = signUpDto.fullName?.trim() || signUpDto.username;
     user.forcePasswordChange = onForcePasswordChange;
     if (signUpDto.mobile) {
       user.mobile = signUpDto.mobile;
@@ -602,7 +687,32 @@ export class AuthenticationService {
     }
   }
 
+  /**
+   * Gates *self-service* account creation only - the public register endpoints, where
+   * an anonymous visitor creates their own account. Callers that create a user on
+   * someone else's behalf (the admin console, an extension model's CRUD form, the
+   * seeders) are deliberately unaffected, so turning this off does not disable user
+   * creation across the system.
+   *
+   * Compared against both representations because `getConfigValue` returns the raw
+   * cached value, which is a boolean when it comes from the provider default and a
+   * string once persisted or edited through the Settings screen - see the same
+   * defensive comparison for `mcpEnabled` in setting.service.ts. A plain falsy check
+   * would read `'false'` as truthy and never fire.
+   */
+  private assertPublicRegistrationEnabled(): void {
+    const allowPublicRegistration =
+      this.settingService.getConfigValue<SolidCoreSetting>(
+        "allowPublicRegistration",
+      );
+    if (allowPublicRegistration === false || allowPublicRegistration === "false") {
+      throw new ForbiddenException(ERROR_MESSAGES.PUBLIC_REGISTRATION_DISABLED);
+    }
+  }
+
   async otpInitiateRegistration(signUpDto: OTPSignUpDto) {
+    this.assertPublicRegistrationEnabled();
+
     const isPasswordlessRegistrationEnabled =
       await this.isPasswordlessRegistrationEnabled();
     if (!isPasswordlessRegistrationEnabled) {
@@ -682,32 +792,68 @@ export class AuthenticationService {
     signUpDto: OTPSignUpDto,
     validationSource: string,
   ): Promise<User> {
-    let user = existingUser;
-    if (isEmpty(user)) {
-      user = this.createUser(signUpDto);
-      user.active = false; // User will be activated only after OTP verification, hence setting active to false for new user.
-      await this.assignRegistrationOtp(validationSource, user);
-      await this.userRepository.save(user);
-      await this.userService.addRoleToUser(
-        user.username,
-        this.settingService.getConfigValue<SolidCoreSetting>("defaultRole"),
+    if (isEmpty(existingUser)) {
+      // Resolved before anything is written: where a provider requires its discriminator
+      // roles() throws, and that should surface as a rejected request rather than as a
+      // half-registered user with no roles.
+      const roles = this.resolveSignupRoles(
+        signUpDto,
+        SIGNUP_POLICY[SignupIntent.SelfRegistration].rolesSource,
       );
-    } else {
+
+      // A new registration is saved through whichever repository createUser resolved,
+      // which is the provider's when the app registers one.
+      const { entity: user, repo } = await this.createUser(signUpDto);
+      user.active = false; // User will be activated only after OTP verification, hence setting active to false for new user.
       await this.assignRegistrationOtp(validationSource, user);
-      await this.userRepository.save(user);
+      await repo.save(user);
+
+      if (roles.length) {
+        await this.userService.addRolesToUser(user.username, roles);
+      } else {
+        // The provider named none, or there is no provider: fall back to the configured
+        // default, matching what performSignUp does on the password paths.
+        await this.userService.addRoleToUser(
+          user.username,
+          this.settingService.getConfigValue<SolidCoreSetting>("defaultRole"),
+        );
+      }
+      return user;
     }
+
+    // An existing row is saved back through the base repository: `User` is the
+    // inheritance root, so TypeORM hydrated it as its own subclass on the way in and
+    // round-trips the discriminator on the way out.
+    const user = existingUser;
+    await this.assignRegistrationOtp(validationSource, user);
+    await this.userRepository.save(user);
     return user;
   }
 
-  // Create a new user entity.
-  private createUser(signUpDto: OTPSignUpDto) {
-    const user = new User();
-    user.username = signUpDto.username;
-    user.email = signUpDto.email;
-    user.mobile = signUpDto.mobile;
-    user.customPayload = signUpDto.customPayload;
-    user.lastLoginProvider = LoginProvider.OTP;
-    return user;
+  /**
+   * Creates a new user entity for OTP registration - of whichever type this app
+   * registers its users as, since passwordless signup is self-registration like any
+   * other. Returns the repository alongside it, because a provider-built entity has
+   * to be saved through the provider's own repository.
+   */
+  private async createUser(
+    signUpDto: OTPSignUpDto,
+  ): Promise<{ entity: User; repo: Repository<User> }> {
+    const { useProvider } = SIGNUP_POLICY[SignupIntent.SelfRegistration];
+    const { entity, repo } = await this.userService.buildSignupTarget(
+      signUpDto,
+      useProvider,
+    );
+
+    entity.username = signUpDto.username;
+    entity.email = signUpDto.email;
+    entity.mobile = signUpDto.mobile;
+    // OTPSignUpDto declares no `fullName`, so username is the only source here. Mirrors the fallback in populateForSignup, which this path does not go through.
+    entity.fullName = signUpDto.fullName?.trim() || signUpDto.username;
+    entity.customPayload = signUpDto.customPayload;
+    entity.lastLoginProvider = LoginProvider.OTP;
+
+    return { entity, repo };
   }
 
   // Generate the validation tokens for the user i.e (system configured + user provided)

package/src/services/crud.service.ts

@@ -3,6 +3,7 @@ import { DiscoveryService, ModuleRef } from "@nestjs/core";
 import { isArray } from "class-validator";
 import { CommonEntity } from "../entities/common.entity";
 import { User } from "../entities/user.entity";
+import { SignupIntent } from "../enums/signup-intent.enum";
 import { SolidBaseRepository } from "../repository/solid-base.repository";
 import { SettingService } from "./setting.service";
 import { ERROR_MESSAGES } from "src/constants/error-messages";
@@ -113,7 +114,7 @@ export class CRUDService<T extends CommonEntity> { // Add two generic value i.e
         }
         const { AuthenticationService } = await import('./authentication.service');
         const authService = this.moduleRef.get(AuthenticationService, { strict: false });
-        return authService.signUp(createDto) as unknown as T;
+        return authService.signUp(createDto, null, SignupIntent.ExtensionModel) as unknown as T;
     }
 
     async create(createDto: any, files: Express.Multer.File[] = [], solidRequestContext: any = {}): Promise<T> {

package/src/services/user.service.ts

@@ -15,6 +15,7 @@ import { RoleMetadata } from "../entities/role-metadata.entity";
 import { User } from "../entities/user.entity";
 import { ActiveUserData } from "../interfaces/active-user-data.interface";
 import { ERROR_MESSAGES } from "src/constants/error-messages";
+import { SolidRegistry } from "src/helpers/solid-registry";
 import { UserRepository } from "src/repository/user.repository";
 import { RoleMetadataRepository } from "src/repository/role-metadata.repository";
 import { HashingService } from "./hashing.service";
@@ -111,6 +112,39 @@ export class UserService extends CRUDService<User> {
     return super.deleteMany(ids, solidRequestContext);
   }
 
+  /**
+   * Resolves which entity a signup should build and which repository it should be
+   * saved through.
+   *
+   * When `useProvider` is set and the app registered an `IExtensionUserCreationProvider`,
+   * the provider builds the entity and owns the repository; otherwise a plain `User`
+   * is saved through the base repository. The caller decides `useProvider` from its
+   * `SignupIntent` - nothing here inspects the DTO.
+   *
+   * The registry is resolved lazily through `moduleRef` rather than injected, mirroring
+   * `CRUDService.tryCreateAsExtensionUser`, to keep this off the DI graph that
+   * AuthenticationService and CRUDService already form a cycle around.
+   */
+  async buildSignupTarget(
+    dto: Record<string, any>,
+    useProvider: boolean,
+  ): Promise<{ entity: User; repo: Repository<User> }> {
+    const provider = useProvider
+      ? this.moduleRef
+          .get(SolidRegistry, { strict: false })
+          ?.getExtensionUserCreationProvider()
+      : null;
+
+    if (!provider) {
+      return { entity: new User(), repo: this.repo };
+    }
+
+    return {
+      entity: await provider.buildExtensionEntity(dto as any),
+      repo: provider.repo as Repository<User>,
+    };
+  }
+
   async findOneByEmail(email: string): Promise<User> {
     return await this.repo.findOne({
       where: {

package/src/testing/contracts/testing-metadata.types.ts

@@ -18,6 +18,18 @@ export interface TestingUserSpec {
   fullName?: string;
   mobile?: string;
   roles?: string[];
+  /**
+   * Seed this user through the registered IExtensionUserCreationProvider, making it
+   * an instance of the app's extension entity rather than a base `User`.
+   *
+   * Absent means a base `User`, so existing specs are unaffected. Set it on users
+   * that carry extension fields (`userType` and the like) - without it those fields
+   * are ignored and a plain `User` is created.
+   *
+   * `roles` is ignored on a flagged user: the provider derives them from the
+   * extension fields, exactly as it does on the model's own CRUD form.
+   */
+  isExtensionUser?: boolean;
   [key: string]: any;
 }