@solidxai/core 0.1.13-beta.9 → 0.1.13

package/src/dtos/setup-mpin.dto.ts

@@ -0,0 +1,51 @@
+import { IsNotEmpty, IsOptional, IsString, IsUUID, Matches, MaxLength } from 'class-validator';
+
+export class SetupMpinDto {
+    /**
+     * Stable identifier for the physical device, generated once by the client.
+     * Validated as a UUID before it ever reaches a cache key or a bucket name,
+     * so it cannot smuggle delimiters into the keyspace.
+     */
+    @IsUUID()
+    deviceId: string;
+
+    /**
+     * A string, not a number, even though it looks like digits.
+     *
+     * A numeric MPIN cannot carry a leading zero: JSON forbids leading zeros in
+     * number literals, so a client serialising `012345` numerically emits
+     * `12345` and the server stores a five-digit MPIN the user never chose -
+     * which still satisfies the default `^\d{4,6}$` and so raises no error.
+     * `mpinRegex` is also tenant-configurable and may permit non-digits.
+     *
+     * Note this cannot be enforced here: the global ValidationPipe runs with
+     * `enableImplicitConversion`, so a numeric payload is coerced to a string
+     * before @IsString() sees it. Clients must send a quoted JSON string; that
+     * requirement is documented in the mobile integration guide.
+     *
+     * Length and shape are checked server-side against `mpinRegex`, since that
+     * setting is the single authority. This only bounds the input.
+     */
+    @IsNotEmpty()
+    @IsString()
+    @MaxLength(32)
+    mpin: string;
+
+    /**
+     * Rendered in a device-management list, so it is bounded here rather than
+     * trusting every consuming UI to escape it.
+     */
+    @IsOptional()
+    @IsString()
+    @MaxLength(64)
+    @Matches(/^[\w\s.'()-]*$/, {
+        message: 'deviceName may contain only letters, numbers, spaces and . \' ( ) - _',
+    })
+    deviceName?: string;
+
+    @IsOptional()
+    @IsString()
+    @MaxLength(32)
+    @Matches(/^[\w.-]*$/, { message: 'platform may contain only letters, numbers and . - _' })
+    platform?: string;
+}

package/src/entities/dashboard-user-layout.entity.ts

@@ -6,12 +6,12 @@ import { ModuleMetadata } from 'src/entities/module-metadata.entity'
 @Entity('ss_dashboard_user_layout')
 export class DashboardUserLayout extends CommonEntity {
     @Index()
-    @ManyToOne(() => User, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => User, { nullable: false })
     @JoinColumn()
     user: User;
 
     @Index()
-    @ManyToOne(() => ModuleMetadata, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => ModuleMetadata, { nullable: false })
     @JoinColumn()
     module: ModuleMetadata;
 

package/src/entities/field-metadata.entity.ts

@@ -77,6 +77,9 @@ export class FieldMetadata extends CommonEntity {
     @Column({ name: 'media_max_size_kb', nullable: true })
     mediaMaxSizeKb: number;
 
+    @Column({ name: 'media_allowed_extensions', nullable: true, type: "simple-json" })
+    mediaAllowedExtensions: string[];
+
     @Index()
     @ManyToOne(() => MediaStorageProviderMetadata, { onDelete: 'SET NULL' })
     @JoinColumn({ name: 'media_storage_provider_id' })

package/src/entities/user-device-credential.entity.ts

@@ -0,0 +1,130 @@
+import { Exclude, Expose } from "class-transformer";
+import { CommonEntity } from "src/entities/common.entity";
+import { Column, Entity, Index, ManyToOne } from "typeorm";
+import { User } from "./user.entity";
+
+/**
+ * A per-device MPIN credential.
+ *
+ * Login presents `credentialRef` (a server-issued opaque handle) plus the MPIN.
+ * The handle - not a mobile number or email - is what identifies the account,
+ * which is why the login route needs no identifier and offers no user
+ * enumeration surface.
+ */
+@Entity("ss_user_device_credential")
+// Non-unique: one physical device may legitimately hold credentials for
+// several accounts, and each account setup mints its own row.
+@Index(["user", "deviceId"])
+@Exclude()
+export class UserDeviceCredential extends CommonEntity {
+
+    // SHA-256 of the opaque handle, and the login lookup key. Never exposed:
+    // the raw handle is returned to the client once at setup and never stored.
+    // SHA-256 rather than bcrypt because the handle is 256 bits of randomness -
+    // there is nothing to brute-force, so a slow hash would only add latency.
+    // Same treatment as UserApiKey.hashedKey.
+    @Index({ unique: true })
+    @Column()
+    hashedCredentialRef: string;
+
+    // bcrypt hash of the MPIN, via HashingService. Never exposed - same
+    // treatment as User.password. Slow hashing is warranted here: a 4-6 digit
+    // secret is exactly the low-entropy case bcrypt exists for.
+    @Column()
+    hashedMpin: string;
+
+    // Mirrors User.passwordScheme / passwordSchemeVersion so
+    // HashingService.needsRehash can upgrade the hash on a successful login.
+    @Column()
+    mpinScheme: string;
+
+    /**
+     * The hashing *policy* version this row was hashed under - not a version of
+     * MPIN itself. It comes from `HashingService.currentVersion()`, which
+     * `BcryptService` currently returns as **2**, so freshly created rows read
+     * 2, exactly as `ss_user.password_scheme_version` does.
+     *
+     * It matters because `BcryptService.normalize` applies the configured
+     * pepper only when `version >= 2`. Storing the version per row means an
+     * older hash still verifies after the policy changes: `compare()` uses the
+     * version the row was written with, and `needsRehash()` upgrades it on the
+     * next successful login.
+     *
+     * The `default: 1` is inherited from the `User` precedent and is never
+     * reached, since every write path sets this explicitly. Note it would be
+     * *wrong* if it ever were: a row hashed at 2 but recorded as 1 would be
+     * compared without the pepper and could never authenticate.
+     */
+    @Column({ default: 1 })
+    mpinSchemeVersion: number;
+
+    // Client-supplied, stable for the physical device. Used for grouping and
+    // the device-management UI only - never a lookup key. Deliberately NOT
+    // unique: several accounts on one device share a deviceId.
+    @Expose()
+    @Column()
+    deviceId: string;
+
+    /**
+     * Human-readable natural key - `<username>-<deviceId>` - unique per row.
+     *
+     * Neither column alone can serve as the model's user key: `deviceId` is
+     * shared by every account on a device, and `deviceName` is nullable.
+     * Combining them is unique in both directions - one user across many
+     * devices, and many users on one device.
+     *
+     * Populated by MpinService rather than declared as a `computed` field in
+     * the metadata manifest. Computed fields are evaluated by
+     * ComputedFieldCrudManager on the generic CRUD path (`crud.service.ts`),
+     * which this service bypasses by writing through the repository directly,
+     * so a computed declaration would silently leave this null. It is also
+     * beyond ConcatComputedFieldProvider, which resolves `dto[field]` flatly
+     * within one model and cannot reach `username` across the user relation.
+     */
+    @Expose()
+    @Index({ unique: true })
+    @Column()
+    credentialKey: string;
+
+    @Expose()
+    @Column({ nullable: true })
+    deviceName: string;
+
+    @Expose()
+    @Column({ nullable: true })
+    platform: string;
+
+    // Revocation is a soft-delete: the row survives so that a correct MPIN can
+    // be answered with "this device was removed" rather than a baffling
+    // "incorrect MPIN". Only active rows count towards mpinMaxDevicesPerUser.
+    @Expose()
+    @Column({ default: true })
+    isActive: boolean;
+
+    // Cumulative, and reset only on a successful login - never when a lockout
+    // expires. That is what makes the second threshold detectable without a
+    // separate lockout counter.
+    @Expose()
+    @Column({ default: 0 })
+    failedAttempts: number;
+
+    @Expose()
+    @Column({ nullable: true })
+    lockedUntil: Date;
+
+    @Expose()
+    @Column({ nullable: true })
+    lastUsedAt: Date;
+
+    // Deliberately no inverse property on User. Nothing needs
+    // `user.deviceCredentials`, and leaving the most widely referenced entity
+    // in the system untouched keeps this feature purely additive.
+    //
+    // `nullable: false` because TypeORM makes relations nullable by default,
+    // which would let a credential exist with no owner. Such a row could never
+    // authenticate - loginWithMpin rejects it - so it would simply be dead
+    // data, but the database should refuse it outright. This also keeps the
+    // column honest against the metadata manifest, which declares it required.
+    @ManyToOne(() => User, { nullable: false })
+    user: User;
+}

package/src/entities/user.entity.ts

@@ -36,12 +36,12 @@ export class User extends CommonEntity {
     @Expose()
     username: string;
 
-    @Index({ unique: true })
+    @Index()
     @Column({ type: "varchar", nullable: true })
     @Expose()
     email: string;
 
-    @Index({ unique: true })
+    @Index()
     @Column({ type: "varchar", nullable: true })
     @Expose()
     mobile: string;

package/src/entities/view-metadata.entity.ts

@@ -19,11 +19,11 @@ export class ViewMetadata extends CommonEntity {
     @Column({ name: "type", type: "varchar" })
     type: string;
 
-    //TODO: To make this truly cross db compatible, we should avoid setting a db type
+    // TODO: To make this truly cross db compatible, we should avoid setting a db type  
     @Column({ name: "context", type: "text" })
     context: any = "{}";
 
-    //TODO: To make this truly cross db compatible, we should avoid setting a db type
+    // TODO: To make this truly cross db compatible, we should avoid setting a db type
     @Column({ name: "layout", type: "text" })
     layout: any;
 

package/src/entities/workflow-execution-artifact.entity.ts

@@ -2,6 +2,7 @@ import { CommonEntity } from 'src/entities/common.entity';
 import { Entity, Column, Index, JoinColumn, ManyToOne } from 'typeorm';
 import { WorkflowExecution } from './workflow-execution.entity';
 import { WorkflowStepExecution } from './workflow-step-execution.entity'
+import { getColumnType } from 'src/helpers/typeorm-db-helper';
 
 @Entity('ss_workflow_execution_artifact')
 export class WorkflowExecutionArtifact extends CommonEntity {
@@ -10,12 +11,12 @@ export class WorkflowExecutionArtifact extends CommonEntity {
     artifactKey: string;
 
     @Index()
-    @ManyToOne(() => WorkflowExecution, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => WorkflowExecution, { nullable: false })
     @JoinColumn()
     workflowExecution: WorkflowExecution;
 
     @Index()
-    @ManyToOne(() => WorkflowStepExecution, { onDelete: "CASCADE", nullable: true })
+    @ManyToOne(() => WorkflowStepExecution, { nullable: true })
     @JoinColumn()
     workflowStepExecution: WorkflowStepExecution;
 
@@ -61,7 +62,7 @@ export class WorkflowExecutionArtifact extends CommonEntity {
     checksum: string;
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     producedAt: Date;
 
     @Column({ type: "simple-json", nullable: true })

package/src/entities/workflow-execution-log.entity.ts

@@ -2,6 +2,7 @@ import { CommonEntity } from 'src/entities/common.entity';
 import { Entity, Column, Index, JoinColumn, ManyToOne } from 'typeorm';
 import { WorkflowExecution } from './workflow-execution.entity';
 import { WorkflowStepExecution } from './workflow-step-execution.entity'
+import { getColumnType } from 'src/helpers/typeorm-db-helper';
 
 @Entity('ss_workflow_execution_log')
 export class WorkflowExecutionLog extends CommonEntity {
@@ -10,12 +11,12 @@ export class WorkflowExecutionLog extends CommonEntity {
     logKey: string;
 
     @Index()
-    @ManyToOne(() => WorkflowExecution, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => WorkflowExecution, { nullable: false })
     @JoinColumn()
     workflowExecution: WorkflowExecution;
 
     @Index()
-    @ManyToOne(() => WorkflowStepExecution, { onDelete: "CASCADE", nullable: true })
+    @ManyToOne(() => WorkflowStepExecution, { nullable: true })
     @JoinColumn()
     workflowStepExecution: WorkflowStepExecution;
 
@@ -47,7 +48,7 @@ export class WorkflowExecutionLog extends CommonEntity {
     sequenceNumber: number;
 
     @Index()
-    @Column({ type: "timestamp" })
+    @Column({ ...getColumnType('datetime') })
     occurredAt: Date;
 
     @Column({ type: "simple-json", nullable: true })

package/src/entities/workflow-execution.entity.ts

@@ -4,6 +4,7 @@ import { WorkflowDefinition } from './workflow-definition.entity'
 import { WorkflowStepExecution } from './workflow-step-execution.entity';
 import { WorkflowExecutionLog } from './workflow-execution-log.entity';
 import { WorkflowExecutionArtifact } from './workflow-execution-artifact.entity';
+import { getColumnType } from 'src/helpers/typeorm-db-helper';
 
 @Entity('ss_workflow_execution')
 export class WorkflowExecution extends CommonEntity {
@@ -32,11 +33,11 @@ export class WorkflowExecution extends CommonEntity {
     triggerType: string = "manual";
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     startedAt: Date;
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     finishedAt: Date;
 
     @Column({ type: "bigint", nullable: true })

package/src/entities/workflow-secret.entity.ts

@@ -1,5 +1,6 @@
 import { CommonEntity } from 'src/entities/common.entity';
 import { Entity, Column, Index } from 'typeorm';
+import { getColumnType } from 'src/helpers/typeorm-db-helper';
 
 @Entity('ss_workflow_secret')
 export class WorkflowSecret extends CommonEntity {
@@ -25,9 +26,9 @@ export class WorkflowSecret extends CommonEntity {
     @Column({ type: "varchar", default: "active" })
     status: string = "active";
 
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     lastRotatedAt: Date;
 
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     lastAccessedAt: Date;
 }

package/src/entities/workflow-step-execution.entity.ts

@@ -1,6 +1,7 @@
 import { CommonEntity } from 'src/entities/common.entity';
 import { Entity, Column, Index, JoinColumn, ManyToOne } from 'typeorm';
 import { WorkflowExecution } from './workflow-execution.entity'
+import { getColumnType } from 'src/helpers/typeorm-db-helper';
 
 @Entity('ss_workflow_step_execution')
 export class WorkflowStepExecution extends CommonEntity {
@@ -55,11 +56,11 @@ export class WorkflowStepExecution extends CommonEntity {
     sequenceNumber: number;
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     startedAt: Date;
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     finishedAt: Date;
 
     @Column({ type: "bigint", nullable: true })

package/src/entities/workflow-trigger-execution.entity.ts

@@ -2,6 +2,7 @@ import { CommonEntity } from 'src/entities/common.entity';
 import { Entity, Column, Index, JoinColumn, ManyToOne } from 'typeorm';
 import { WorkflowDefinition } from './workflow-definition.entity';
 import { WorkflowExecution } from './workflow-execution.entity'
+import { getColumnType } from 'src/helpers/typeorm-db-helper';
 
 @Entity('ss_workflow_trigger_execution')
 export class WorkflowTriggerExecution extends CommonEntity {
@@ -10,12 +11,12 @@ export class WorkflowTriggerExecution extends CommonEntity {
     triggerExecutionKey: string;
 
     @Index()
-    @ManyToOne(() => WorkflowDefinition, { onDelete: "CASCADE", nullable: false })
+    @ManyToOne(() => WorkflowDefinition, { nullable: false })
     @JoinColumn()
     workflowDefinition: WorkflowDefinition;
 
     @Index()
-    @ManyToOne(() => WorkflowExecution, { onDelete: "CASCADE", nullable: true })
+    @ManyToOne(() => WorkflowExecution, { nullable: true })
     @JoinColumn()
     workflowExecution: WorkflowExecution;
 
@@ -39,15 +40,15 @@ export class WorkflowTriggerExecution extends CommonEntity {
     matched: boolean = false;
 
     @Index()
-    @Column({ type: "timestamp" })
+    @Column({ ...getColumnType('datetime') })
     firedAt: Date;
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     startedAt: Date;
 
     @Index()
-    @Column({ type: "timestamp", nullable: true })
+    @Column({ nullable: true, ...getColumnType('datetime') })
     finishedAt: Date;
 
     @Column({ type: "bigint", nullable: true })

package/src/filters/http-exception.filter.ts

@@ -30,12 +30,22 @@ export class HttpExceptionFilter implements ExceptionFilter {
         const isHttp = exception instanceof HttpException;
         const explicitStatus = isHttp ? exception.getStatus() : undefined;
 
+        // Errors from http-errors-style libraries (e.g. body-parser's PayloadTooLargeError)
+        // are plain Errors carrying their own status. Honour it rather than collapsing to 500.
+        const rawStatus = exception?.status ?? exception?.statusCode;
+        const derivedStatus =
+            typeof rawStatus === 'number' && rawStatus >= 400 && rawStatus < 600
+                ? rawStatus
+                : undefined;
+
         // Canonical code + static message
         const code: ErrorCode = this.errorMapper.mapException(exception);
         const defaultStatus = this.errorMapper.getHttpStatus(code);
         const message = code === 'solidx-unknown-error' ? `${exception?.message}` : this.errorMapper.getMessage(code);
 
-        const status = explicitStatus ?? defaultStatus ?? 500;
+        // derivedStatus must precede defaultStatus: getHttpStatus() returns a hard 500
+        // for unmatched codes, so it is never undefined and would always win otherwise.
+        const status = explicitStatus ?? derivedStatus ?? defaultStatus ?? 500;
 
         // Logging
         this.logger.error(

package/src/helpers/bootstrap.helper.ts

@@ -1,5 +1,6 @@
 import { ClassSerializerInterceptor, ValidationPipe } from '@nestjs/common';
 import { NestFactory, Reflector } from '@nestjs/core';
+import { NestExpressApplication } from '@nestjs/platform-express';
 import { WsAdapter } from '@nestjs/platform-ws';
 import { DocumentBuilder, SwaggerModule } from '@nestjs/swagger';
 import { NextFunction, Request, Response } from 'express';
@@ -12,7 +13,12 @@ import { CommandFactory } from 'nest-commander';
 import { createWinstonLoggerConfig } from '../winston.logger';
 import { WrapResponseInterceptor } from '../interceptors/wrap-response.interceptor';
 import { buildDefaultCorsOptions } from './cors.helper';
-import { buildDefaultSecurityHeaderOptions, buildPermissionsPolicyHeader, PermissionsPolicyConfig } from './security.helper';
+import {
+  buildDefaultSecurityHeaderOptions,
+  buildPermissionsPolicyHeader,
+  PermissionsPolicyConfig,
+  SolidSecurityOptions,
+} from './security.helper';
 import { parseBooleanEnv } from './environment.helper';
 
 // ---- Shared process handlers ----
@@ -50,8 +56,20 @@ export interface SolidBootstrapOptions {
   swagger?: SolidSwaggerOptions | false;
   /** Permissions-Policy header overrides (merged with defaults). */
   permissionsPolicyOverrides?: Partial<PermissionsPolicyConfig>;
+  /** Security header overrides, including iframe frame-ancestor allowlists. */
+  security?: SolidSecurityOptions;
   /** Show full NestJS init logs during bootstrap (route mapping, module deps, pollers). Defaults to false. */
   verboseBootstrap?: boolean;
+  /**
+   * Max request body size for JSON and urlencoded payloads, as a `bytes`-compatible
+   * string (e.g. '10mb', '512kb'). Defaults to '10mb'.
+   *
+   * Does NOT apply to multipart/form-data uploads: body-parser matches on Content-Type,
+   * so multipart requests skip these parsers entirely and are handled by Multer. Raise
+   * this only for large structured JSON (e.g. /bulk arrays), bearing in mind the parsed
+   * object graph can retain several times the raw byte size.
+   */
+  bodyLimit?: string;
 }
 
 /**
@@ -64,19 +82,30 @@ export interface SolidBootstrapOptions {
  * // main.ts
  * bootstrapSolidApp(() => AppModule.forRoot(), {
  *   swagger: { title: 'My API', description: 'My API description' },
+ *   security: { frameAncestors: ["'self'", 'https://portal.example.com'] },
  * });
  */
 export async function bootstrapSolidApp(
   appModuleFactory: () => Promise<any>,
   options: SolidBootstrapOptions = {},
-): Promise<void> {
+): Promise<NestExpressApplication> {
   registerGlobalProcessHandlers();
 
-  const { globalPrefix = 'api', swagger = {}, permissionsPolicyOverrides = {}, verboseBootstrap = false } = options;
+  const {
+    globalPrefix = 'api',
+    swagger = {},
+    permissionsPolicyOverrides = {},
+    security = {},
+    verboseBootstrap = false,
+    bodyLimit = '10mb',
+  } = options;
 
   const startTime = Date.now();
   const appModule = await appModuleFactory();
-  const app = await NestFactory.create(appModule, {
+  const app = await NestFactory.create<NestExpressApplication>(appModule, {
+    // Nest's default parsers are registered during init() with a 100kb limit, ahead of
+    // any module middleware. Disable them so the parsers below own the limit outright.
+    bodyParser: false,
     logger: WinstonModule.createLogger({ ...createWinstonLoggerConfig(), level: verboseBootstrap ? 'debug' : 'error' }),
   });
 
@@ -87,7 +116,7 @@ export async function bootstrapSolidApp(
     app
       .get(WINSTON_MODULE_NEST_PROVIDER)
       .log('API server disabled via API_ENABLED=false. Skipping HTTP listen.', 'Bootstrap');
-    return;
+    return app;
   }
 
   // Health check at root path
@@ -95,7 +124,7 @@ export async function bootstrapSolidApp(
   server.get('/', (_req, res) => res.status(200).send('SOLID OK'));
 
   // Security headers
-  app.use(helmet(buildDefaultSecurityHeaderOptions()));
+  app.use(helmet(buildDefaultSecurityHeaderOptions(security)));
 
   // Nest's Swagger UI HTML injects inline styles; keep CSP strict elsewhere.
   const isSwaggerPath = (path: string) =>
@@ -136,6 +165,12 @@ export async function bootstrapSolidApp(
     next();
   });
 
+  // Body parsers — replaces Nest's default 100kb parsers (disabled via bodyParser: false).
+  // Registered here so the middleware order Nest applied by default is preserved:
+  // helmet -> CSP -> Permissions-Policy -> qs -> body parsers -> routes.
+  app.useBodyParser('json', { limit: bodyLimit });
+  app.useBodyParser('urlencoded', { limit: bodyLimit, extended: true });
+
   // Global ValidationPipe
   app.useGlobalPipes(
     new ValidationPipe({
@@ -195,6 +230,8 @@ export async function bootstrapSolidApp(
 
   const elapsed = ((Date.now() - startTime) / 1000).toFixed(2);
   process.stdout.write(`\x1b[32mServer started on port ${port} in ${elapsed}s\x1b[0m\n`);
+
+  return app;
 }
 
 // ---- CLI bootstrap ----