@solidxai/core 0.1.13-beta.19 → 0.1.13-beta.20

package/src/constants/error-messages.ts

@@ -127,6 +127,20 @@ export const ERROR_MESSAGES = {
 
     DEFAULT_REGEX_PATTERN_NOT_MATCHING_ERROR_MSG: 'Invalid regex pattern.',
 
+    // MPIN errors.
+    // MPIN_INVALID is deliberately shared by "wrong MPIN" and "unknown handle",
+    // so a failed sign-in never reveals whether the credential handle was real.
+    // MPIN_REVOKED is separate and is returned for any attempt against a
+    // deactivated credential - it discloses nothing useful, since a dead
+    // credential grants no capability, and it lets the client stop retrying.
+    MPIN_INVALID: 'Invalid MPIN.',
+    MPIN_LOCKED: 'MPIN sign-in is temporarily locked due to repeated failed attempts.',
+    MPIN_REVOKED: 'MPIN sign-in has been disabled for this device. Please sign in normally.',
+    MPIN_NOT_ENABLED: 'MPIN sign-in is not enabled.',
+    MPIN_FORMAT_INVALID: 'MPIN does not meet the required format.',
+    MPIN_TOO_PREDICTABLE: 'MPIN is too easy to guess. Avoid repeated or sequential digits.',
+    MPIN_CREDENTIAL_NOT_FOUND: 'MPIN device credential not found.',
+
     PERMISSION_MESSAGES: {
     insertMany: (model?: string) =>
       `You do not have permission to import ${model ?? 'these'} records.`,

package/src/constants/success-messages.ts

@@ -6,6 +6,11 @@ export const SUCCESS_MESSAGES = {
     LOGOUT_SUCCESS: 'Logged out successfully',
     USER_REGISTERED: 'User registered successfully.',
 
+    // MPIN messages
+    MPIN_SETUP_SUCCESS: 'MPIN set up successfully.',
+    MPIN_CHANGED_SUCCESS: 'MPIN changed successfully.',
+    MPIN_DEVICE_REVOKED: 'MPIN sign-in removed for this device.',
+
     // CRUD service messages
     RECORD_RECOVERED: 'Record successfully recovered',
     SELECTED_RECORDS_RECOVERED: 'Selected records successfully recovered',

package/src/controllers/mpin-authentication.controller.ts

@@ -0,0 +1,67 @@
+import { Body, Controller, Delete, Get, HttpCode, HttpStatus, Param, ParseIntPipe, Post } from '@nestjs/common';
+import { ApiBearerAuth, ApiTags } from '@nestjs/swagger';
+import { ActiveUser } from '../decorators/active-user.decorator';
+import { Public } from '../decorators/public.decorator';
+import { ChangeMpinDto } from '../dtos/change-mpin.dto';
+import { MpinLoginDto } from '../dtos/mpin-login.dto';
+import { SetupMpinDto } from '../dtos/setup-mpin.dto';
+import { ActiveUserData } from '../interfaces/active-user-data.interface';
+import { MpinService } from '../services/mpin.service';
+
+/**
+ * There is deliberately no public "is MPIN set up for this identifier" route.
+ * That would reintroduce exactly the user-enumeration oracle the opaque
+ * credential handle removes. The client decides whether to show the MPIN
+ * screen from the presence of its own stored handle.
+ */
+@Controller('iam/mpin')
+@ApiTags('Solid Core')
+export class MpinAuthenticationController {
+    constructor(private readonly mpinService: MpinService) { }
+
+    @ApiBearerAuth('jwt')
+    @Post('setup')
+    @HttpCode(HttpStatus.OK)
+    setup(
+        @Body() setupMpinDto: SetupMpinDto,
+        @ActiveUser() activeUser: ActiveUserData,
+    ) {
+        return this.mpinService.setupMpin(activeUser, setupMpinDto);
+    }
+
+    @ApiBearerAuth('jwt')
+    @Post('change')
+    @HttpCode(HttpStatus.OK)
+    change(
+        @Body() changeMpinDto: ChangeMpinDto,
+        @ActiveUser() activeUser: ActiveUserData,
+    ) {
+        return this.mpinService.changeMpin(activeUser, changeMpinDto);
+    }
+
+    // Public by necessity - the caller has no session yet. The credential
+    // handle is unguessable, so this carries no enumeration surface.
+    @Public()
+    @Post('login')
+    @HttpCode(HttpStatus.OK)
+    login(@Body() mpinLoginDto: MpinLoginDto) {
+        return this.mpinService.loginWithMpin(mpinLoginDto);
+    }
+
+    @ApiBearerAuth('jwt')
+    @Get('devices')
+    listDevices(@ActiveUser() activeUser: ActiveUserData) {
+        return this.mpinService.listDevices(activeUser);
+    }
+
+    // By row id, never by credential handle, so the management UI never has to
+    // hold the secret.
+    @ApiBearerAuth('jwt')
+    @Delete('devices/:id')
+    revokeDevice(
+        @Param('id', ParseIntPipe) id: number,
+        @ActiveUser() activeUser: ActiveUserData,
+    ) {
+        return this.mpinService.revokeDevice(activeUser, id);
+    }
+}

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

@@ -0,0 +1,18 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+export class ChangeMpinDto {
+    @IsNotEmpty()
+    @IsString()
+    @MaxLength(128)
+    credentialRef: string;
+
+    @IsNotEmpty()
+    @IsString()
+    @MaxLength(32)
+    currentMpin: string;
+
+    @IsNotEmpty()
+    @IsString()
+    @MaxLength(32)
+    newMpin: string;
+}

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

@@ -0,0 +1,24 @@
+import { IsNotEmpty, IsString, MaxLength } from 'class-validator';
+
+/**
+ * Deliberately carries no identifier - no mobile, email or username.
+ *
+ * `credentialRef` is a server-issued 256-bit handle that already points at a
+ * single credential row, and therefore at a single user. That is what removes
+ * the user-enumeration surface a public login route would otherwise have: an
+ * attacker cannot probe "does this phone number have MPIN?" because there is
+ * nowhere to put a phone number.
+ */
+export class MpinLoginDto {
+    // Bounded so a pathological payload never reaches the regex test or the
+    // hash comparison. The handle is always 64 hex characters.
+    @IsNotEmpty()
+    @IsString()
+    @MaxLength(128)
+    credentialRef: string;
+
+    @IsNotEmpty()
+    @IsString()
+    @MaxLength(32)
+    mpin: string;
+}

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/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/helpers/solid-core-error-codes-provider.service.ts

@@ -32,6 +32,59 @@ export class SolidCoreErrorCodesProvider implements IErrorCodeProvider {
                     httpStatus: 401,
                 },
             },
+            // MPIN rules sit above the generic session rules so that an MPIN
+            // failure is never reported as a session problem. The three codes
+            // drive three different client behaviours: retry, wait, and
+            // discard-the-handle.
+            {
+                code: 'solidx-mpin-locked',
+                priority: 120,
+                match: (txt) => txt.includes(ERROR_MESSAGES.MPIN_LOCKED.toLowerCase()),
+                meta: {
+                    message: ERROR_MESSAGES.MPIN_LOCKED,
+                    httpStatus: 401,
+                },
+            },
+            {
+                code: 'solidx-mpin-revoked',
+                priority: 120,
+                match: (txt) => txt.includes(ERROR_MESSAGES.MPIN_REVOKED.toLowerCase()),
+                meta: {
+                    message: ERROR_MESSAGES.MPIN_REVOKED,
+                    httpStatus: 401,
+                },
+            },
+            {
+                code: 'solidx-mpin-invalid',
+                priority: 120,
+                match: (txt) => txt.includes(ERROR_MESSAGES.MPIN_INVALID.toLowerCase()),
+                meta: {
+                    message: ERROR_MESSAGES.MPIN_INVALID,
+                    httpStatus: 401,
+                },
+            },
+            // Setup-time rejections. Distinct codes so the client can say
+            // "choose a less predictable PIN" rather than parsing a message.
+            // Safe to distinguish: both occur only on bearer-authenticated
+            // routes, so neither discloses anything.
+            {
+                code: 'solidx-mpin-too-predictable',
+                priority: 120,
+                match: (txt) => txt.includes(ERROR_MESSAGES.MPIN_TOO_PREDICTABLE.toLowerCase()),
+                meta: {
+                    message: ERROR_MESSAGES.MPIN_TOO_PREDICTABLE,
+                    httpStatus: 400,
+                },
+            },
+            {
+                code: 'solidx-mpin-format-invalid',
+                priority: 120,
+                match: (txt) => txt.includes(ERROR_MESSAGES.MPIN_FORMAT_INVALID.toLowerCase()),
+                meta: {
+                    message: ERROR_MESSAGES.MPIN_FORMAT_INVALID,
+                    httpStatus: 400,
+                },
+            },
             {
                 code: 'solidx-mcp-server-unavailable',
                 priority: 100,

package/src/index.ts

@@ -160,6 +160,12 @@ export * from './entities/role-metadata.entity'
 export * from './entities/sms-template.entity'
 export * from './entities/user.entity'
 export * from './entities/user-api-key.entity'
+export * from './entities/user-device-credential.entity'
+export * from './repository/user-device-credential.repository'
+export * from './services/mpin.service'
+export * from './dtos/setup-mpin.dto'
+export * from './dtos/change-mpin.dto'
+export * from './dtos/mpin-login.dto'
 export * from './entities/view-metadata.entity'
 export * from './entities/setting.entity'
 export * from './entities/saved-filters.entity'

package/src/repository/user-device-credential.repository.ts

@@ -0,0 +1,17 @@
+import { Injectable } from '@nestjs/common';
+import { UserDeviceCredential } from 'src/entities/user-device-credential.entity';
+import { RequestContextService } from 'src/services/request-context.service';
+import { DataSource } from 'typeorm';
+import { SecurityRuleRepository } from './security-rule.repository';
+import { SolidBaseRepository } from './solid-base.repository';
+
+@Injectable()
+export class UserDeviceCredentialRepository extends SolidBaseRepository<UserDeviceCredential> {
+    constructor(
+        readonly dataSource: DataSource,
+        readonly requestContextService: RequestContextService,
+        readonly securityRuleRepository: SecurityRuleRepository,
+    ) {
+        super(UserDeviceCredential, dataSource, requestContextService, securityRuleRepository);
+    }
+}

package/src/seeders/seed-data/solid-core-metadata.json

@@ -2360,6 +2360,164 @@
           }
         ]
       },
+      {
+        "singularName": "userDeviceCredential",
+        "tableName": "ss_user_device_credential",
+        "pluralName": "userDeviceCredentials",
+        "displayName": "User Device Credential",
+        "description": "Per-device MPIN credentials",
+        "dataSource": "default",
+        "dataSourceType": "postgres",
+        "userKeyFieldUserKey": "credentialKey",
+        "isSystem": true,
+        "fields": [
+          {
+            "name": "credentialKey",
+            "displayName": "Credential Key",
+            "description": "Natural key: <username>-<deviceId>. Populated by MpinService, not by the computed-field pipeline.",
+            "type": "shortText",
+            "length": 512,
+            "required": true,
+            "unique": true,
+            "index": true,
+            "private": false,
+            "encrypt": false,
+            "isUserKey": true,
+            "isSystem": true
+          },
+          {
+            "name": "hashedCredentialRef",
+            "displayName": "Hashed Credential Ref",
+            "type": "shortText",
+            "length": 512,
+            "required": true,
+            "unique": true,
+            "index": true,
+            "private": true,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "hashedMpin",
+            "displayName": "Hashed MPIN",
+            "type": "shortText",
+            "length": 512,
+            "required": true,
+            "unique": false,
+            "index": false,
+            "private": true,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "mpinScheme",
+            "displayName": "MPIN Scheme",
+            "type": "selectionStatic",
+            "required": true,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true,
+            "selectionStaticValues": [
+              "bcrypt:bcrypt"
+            ]
+          },
+          {
+            "name": "mpinSchemeVersion",
+            "displayName": "MPIN Scheme Version",
+            "type": "int",
+            "required": true,
+            "private": false,
+            "encrypt": false,
+            "defaultValue": "1",
+            "isSystem": true
+          },
+          {
+            "name": "deviceId",
+            "displayName": "Device Id",
+            "type": "shortText",
+            "length": 512,
+            "required": true,
+            "unique": false,
+            "index": true,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "deviceName",
+            "displayName": "Device Name",
+            "type": "shortText",
+            "length": 512,
+            "required": false,
+            "unique": false,
+            "index": false,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "platform",
+            "displayName": "Platform",
+            "type": "shortText",
+            "length": 512,
+            "required": false,
+            "unique": false,
+            "index": false,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "isActive",
+            "displayName": "Is Active",
+            "type": "boolean",
+            "required": true,
+            "unique": false,
+            "index": false,
+            "private": false,
+            "encrypt": false,
+            "defaultValue": "true",
+            "isSystem": true
+          },
+          {
+            "name": "failedAttempts",
+            "displayName": "Failed Attempts",
+            "type": "int",
+            "required": true,
+            "private": false,
+            "encrypt": false,
+            "defaultValue": "0",
+            "isSystem": true
+          },
+          {
+            "name": "lockedUntil",
+            "displayName": "Locked Until",
+            "type": "datetime",
+            "required": false,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "lastUsedAt",
+            "displayName": "Last Used At",
+            "type": "datetime",
+            "required": false,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true
+          },
+          {
+            "name": "user",
+            "displayName": "User",
+            "type": "relation",
+            "required": true,
+            "private": false,
+            "encrypt": false,
+            "isSystem": true
+          }
+        ]
+      },
       {
         "singularName": "userActivityHistory",
         "tableName": "ss_user_activity_history",