feat: add universal RNG engine

Author: TeaCoder52

package.json

@@ -37,10 +37,11 @@
 		"2fa"
 	],
 	"devDependencies": {
+		"@types/node": "^24.10.1",
+		"@vitest/coverage-v8": "^4.0.14",
+		"ts-node": "^10.9.2",
 		"tsup": "^8.0.0",
 		"typescript": "^5.6.0",
-		"vitest": "^4.0.14",
-		"@vitest/coverage-v8": "^4.0.14",
-		"ts-node": "^10.9.2"
+		"vitest": "^4.0.14"
 	}
 }

src/index.ts

@@ -3,35 +3,48 @@ import {
 	CodeLength,
 	Strategy,
 	CustomStrategyContext,
-	CodeAnalysis,
+	HumanProfile,
+	SecurityMode,
+	RngProfile,
+	type CodeAnalysis,
+	type CodePrediction,
 } from './types'
 import { getStrategyImpl } from './strategy'
 import { isCodeAllowed } from './validator'
 import {
 	getAllowedDigits,
-	getRng,
 	fromDigits,
 	isAllSame,
 	isTooSimpleSequence,
 	pickDigit,
 	pickTwoDifferentDigits,
 	pickThreeDifferentDigits,
+	getRng,
 } from './utils'
+import { registerRng } from './rng'
+import { analyze } from './analyze'
+import { predictCodeQuality } from './predictor'
 
-export { analyze } from './analyze'
-
-export {
+export type {
 	GenerateOptions,
 	CodeLength,
-	Strategy,
 	CustomStrategyContext,
+	HumanProfile,
+	SecurityMode,
+	RngProfile,
 	CodeAnalysis,
+	CodePrediction,
 }
+export { Strategy, analyze, predictCodeQuality, registerRng }
 
 export function generateCode(options: GenerateOptions = {}): string {
 	const length: CodeLength = options.length === 4 ? 4 : 6
 	const strategy: Strategy = options.strategy ?? Strategy.Mixed
 
+	if (options.mode === 'banking') {
+		return generateBankingCode({ ...options, length })
+	}
+
 	const impl = getStrategyImpl(length, strategy, options)
 
 	const maxAttempts = 100
@@ -50,6 +63,32 @@ export function generateCode(options: GenerateOptions = {}): string {
 	return code.slice(0, length)
 }
 
+function generateBankingCode(options: GenerateOptions = {}): string {
+	const length: CodeLength = options.length === 4 ? 4 : 6
+	const digits = getAllowedDigits(options)
+	const rng = getRng({ ...options, mode: 'banking' })
+
+	const maxAttempts = 100
+	for (let i = 0; i < maxAttempts; i++) {
+		const result: string[] = []
+		while (result.length < length) {
+			const d = pickDigit(digits, rng)
+			if (!result.includes(d)) {
+				result.push(d)
+			}
+		}
+		const code = fromDigits(result)
+		if (isCodeAllowed(code, { ...options, mode: 'banking' })) {
+			return code
+		}
+	}
+
+	const fallback = fromDigits(
+		Array.from({ length }, () => pickDigit(digits, rng))
+	)
+	return fallback.slice(0, length)
+}
+
 export function isHumanFriendly(
 	code: string,
 	options?: GenerateOptions

src/predictor.ts

@@ -0,0 +1,52 @@
+import type { CodePrediction, GenerateOptions } from './types'
+import { analyze } from './analyze'
+
+function hammingSimilarity(a: string, b: string): number {
+	if (!a || !b || a.length !== b.length) return 0
+	let same = 0
+	for (let i = 0; i < a.length; i++) {
+		if (a[i] === b[i]) same++
+	}
+	return same / a.length
+}
+
+export function predictCodeQuality(
+	code: string,
+	options: GenerateOptions = {}
+): CodePrediction {
+	const a = analyze(code)
+
+	let baseMem = 0.5
+	if (a.memorability === 'low') baseMem = 0.25
+	if (a.memorability === 'medium') baseMem = 0.55
+	if (a.memorability === 'high') baseMem = 0.85
+
+	switch (options.profile) {
+		case 'children':
+			baseMem += 0.1
+			break
+		case 'elderly':
+			if (a.entropy > 10) baseMem -= 0.1
+			break
+		case 'asia':
+			if (code.includes('4')) baseMem -= 0.15
+			break
+		case 'latam':
+			if (a.memorability === 'high') baseMem += 0.05
+			break
+		default:
+			break
+	}
+
+	let confusion = 0
+	if (options.previousCode && options.previousCode.length === code.length) {
+		confusion = hammingSimilarity(code, options.previousCode)
+	}
+
+	const clamp = (v: number) => Math.max(0, Math.min(1, v))
+
+	return {
+		memorabilityScore: clamp(baseMem),
+		confusionScore: clamp(confusion),
+	}
+}

src/profile.ts

@@ -0,0 +1,76 @@
+import type { GenerateOptions, HumanProfile, SecurityMode } from './types'
+import { analyze } from './analyze'
+import { isAllSame, isTooSimpleSequence } from './utils'
+import { predictCodeQuality } from './predictor'
+
+function hasRepeats(code: string): boolean {
+	return new Set(code).size < code.length
+}
+
+export function isProfileCompatible(
+	code: string,
+	options: GenerateOptions
+): boolean {
+	const profile: HumanProfile = options.profile ?? 'default'
+	const analysis = analyze(code)
+	const prediction = predictCodeQuality(code, options)
+
+	switch (profile) {
+		case 'children': {
+			if (analysis.memorability === 'low') return false
+			if (prediction.memorabilityScore < 0.6) return false
+			if (analysis.isSequentialAsc || analysis.isSequentialDesc)
+				return false
+			return true
+		}
+		case 'elderly': {
+			if (analysis.memorability === 'low') return false
+			if (analysis.entropy > 11 && analysis.length === 6) return false
+			return true
+		}
+		case 'asia': {
+			if (code.includes('4')) return false
+			return true
+		}
+		case 'latam': {
+			if (code[0] === '0' || code[0] === '1') return false
+			return true
+		}
+		case 'default':
+		default:
+			return true
+	}
+}
+
+export function isModeCompatible(
+	code: string,
+	options: GenerateOptions
+): boolean {
+	const mode: SecurityMode = options.mode ?? 'normal'
+	if (mode === 'normal') return true
+
+	const a = analyze(code)
+
+	if (isAllSame(code)) return false
+	if (isTooSimpleSequence(code)) return false
+	if (hasRepeats(code)) return false
+	if (a.isSequentialAsc || a.isSequentialDesc) return false
+
+	if (a.length === 4 && a.entropy < 6.5) return false
+	if (a.length === 6 && a.entropy < 10) return false
+
+	return true
+}
+
+export function isPredictionCompatible(
+	code: string,
+	options: GenerateOptions
+): boolean {
+	if (!options.avoidSimilarPrevious || !options.previousCode) return true
+	if (options.previousCode.length !== code.length) return true
+
+	const prediction = predictCodeQuality(code, options)
+
+	if (prediction.confusionScore > 0.5) return false
+	return true
+}

src/rng.ts

@@ -0,0 +1,64 @@
+import type { GenerateOptions, RngProfile } from './types'
+
+export type RngFunction = () => number
+
+const rngRegistry = new Map<RngProfile, RngFunction>()
+
+function defaultInsecureRng(): number {
+	return Math.random()
+}
+
+function defaultSecureRng(): number {
+	if (typeof globalThis !== 'undefined') {
+		const g: any = globalThis as any
+		if (g.crypto && typeof g.crypto.getRandomValues === 'function') {
+			const arr = new Uint32Array(1)
+			g.crypto.getRandomValues(arr)
+			return arr[0]! / 0xffffffff
+		}
+	}
+
+	try {
+		const nodeCrypto = require('crypto')
+		const web = nodeCrypto.webcrypto
+
+		if (web && typeof web.getRandomValues === 'function') {
+			const arr = new Uint32Array(1)
+			web.getRandomValues(arr)
+			return arr[0]! / 0xffffffff
+		}
+	} catch {}
+
+	return Math.random()
+}
+
+function defaultHybridRng(): number {
+	const a = defaultInsecureRng()
+	const b = defaultSecureRng()
+	return (a + b) % 1
+}
+
+rngRegistry.set('insecure', defaultInsecureRng)
+rngRegistry.set('secure', defaultSecureRng)
+rngRegistry.set('hybrid', defaultHybridRng)
+
+export function registerRng(name: RngProfile, rng: RngFunction): void {
+	if (typeof rng !== 'function') {
+		throw new Error('RNG must be a function that returns number in [0,1)')
+	}
+	rngRegistry.set(name, rng)
+}
+
+export function resolveRng(options?: GenerateOptions): RngFunction {
+	if (options?.rng) return options.rng
+
+	if (options?.rngProfile && rngRegistry.has(options.rngProfile)) {
+		return rngRegistry.get(options.rngProfile)!
+	}
+
+	if (options?.mode === 'banking') {
+		return rngRegistry.get('secure') ?? defaultSecureRng
+	}
+
+	return rngRegistry.get('insecure') ?? defaultInsecureRng
+}

src/types.ts

@@ -11,6 +11,10 @@ export enum Strategy {
 	Custom = 'custom',
 }
 
+export type HumanProfile = 'default' | 'children' | 'elderly' | 'asia' | 'latam'
+export type SecurityMode = 'normal' | 'banking'
+export type RngProfile = 'insecure' | 'secure' | 'hybrid' | (string & {})
+
 export interface CustomStrategyContext {
 	length: CodeLength
 	pickDigit(): string
@@ -21,6 +25,24 @@ export interface CustomStrategyContext {
 	isAllSame(code: string): boolean
 }
 
+export interface CodeAnalysis {
+	length: CodeLength
+	isAllSame: boolean
+	isTooSimple: boolean
+	isSequentialAsc: boolean
+	isSequentialDesc: boolean
+	repeatedGroups: number
+
+	entropy: number
+	collisionRisk: 'low' | 'medium' | 'high'
+	memorability: 'low' | 'medium' | 'high'
+}
+
+export interface CodePrediction {
+	memorabilityScore: number
+	confusionScore: number
+}
+
 export interface GenerateOptions {
 	length?: CodeLength
 	strategy?: Strategy
@@ -29,19 +51,14 @@ export interface GenerateOptions {
 	blackList?: string[]
 	previousCode?: string
 	allowedDigits?: string[]
+
 	rng?: () => number
-	customStrategy?: (ctx: CustomStrategyContext) => string
-}
+	rngProfile?: RngProfile
 
-export interface CodeAnalysis {
-	length: CodeLength
-	isAllSame: boolean
-	isTooSimple: boolean
-	isSequentialAsc: boolean
-	isSequentialDesc: boolean
-	repeatedGroups: number
-	pattern?: string
-	entropy: number
-	memorability: 'low' | 'medium' | 'high'
-	collisionRisk: 'low' | 'medium' | 'high'
+	profile?: HumanProfile
+	mode?: SecurityMode
+
+	avoidSimilarPrevious?: boolean
+
+	customStrategy?: (ctx: CustomStrategyContext) => string
 }