@servicelabsco/nestjs-utility-services 2.0.15 → 3.0.2

package/CODEBASE-REVIEW.md

@@ -1,227 +0,0 @@
-# Codebase audit — `@servicelabsco/nestjs-utility-services`
-
-**Branch:** `main` · **HEAD:** `fa2fa14a7` · **Date:** 2026-05-18
-**Scope:** 613 TS files / 39,595 LOC across `auth/`, `common/`, `platformUtility/`, `system/`, `security/`, `config/`, `migrations/`.
-**Method:** 6 parallel module-bucket reviewers (`superpowers:code-reviewer`) using `codebase-audit` skill; findings consolidated and ID-tagged here.
-
----
-
-## Part A — Architecture in one page
-
-This is a **publishable npm library** that ships compiled `dist/` and is consumed by other NestJS apps via `entities: [..., 'node_modules/@servicelabsco/**/*.entity.{ts,js}']`. It is also runnable as a standalone Nest app (`main.ts` HTTP + `worker.ts` BullMQ worker) for local dev. Every export is therefore part of the public API surface that ships into every consumer's runtime.
-
-Five top-level modules:
-
-- **`common/`** — framework primitives (`CommonEntity`, `CommonService`, `CommonJob`, `CommonSubscriber`, `MigrationUtility`, static `Auth` accessor over `express-http-context2`, exception classes, helpers: `Hash`, `CustomCrypt`, `DateUtil`, `JsonEvaluator`, `EntityEvaluator`, `DataManager`/`RecordManager`/`ListManager`/`ReportDataManager`).
-- **`auth/`** — users, sessions, JWT, refresh tokens, social login, device tokens, role/permission, four globally-mounted middlewares (`JwtMiddleware`, `BasicAuthMiddleware`, `InternalMiddleware`, `RestrictedMiddleware`).
-- **`platformUtility/`** — infra adapters: S3, SQS, Dynamo, Redis, Cache, Queue (BullMQ), Mail (SMTP/SES), SMS, FCM, RemoteRequest, AwsConfig, AwsSecret, Sql, Zip (Lambda), Maintenance/Startup/Shutdown, `JobConsumer`.
-- **`security/`** — pass-through (entity registration only).
-- **`system/`** — the bulk of the domain (~70 entities for menus, roles, permissions, models, columns, lookups, forms, reports, charts, **scripts**, scheduled events, mail/sms/whatsapp templates, document storage).
-
-Three TypeORM connections (`default` write, `read` replica, `mongodb`); BullMQ via `JobConsumer`; cron-driven scheduled events; subscribers wired to lifecycle hooks dispatching `*Job.delayedDispatch()`. Multi-app migration table (`sys_migrations`) shared across sibling `@servicelabsco/*` packages — duplicate names collide.
-
-**Strongest design:** the recent storage refactor (`StorageService` + `CommonStorageService` + S3/R2 adapters) — clean facade-adapter-registry, eager warm-up, well-documented public-API contracts. Use as the template for refactoring elsewhere.
-
-**Biggest concentrations of risk:**
-1. `system/libraries/*evaluator*.ts`, `system/libraries/process.script.execution.ts`, `system/libraries/execute.code.fix.ts` — six `eval()` call sites running stored DB strings.
-2. `system/controllers/base.controller.ts` — `plainToInstance(entity, req.body)` mass-assignment.
-3. `auth/services/social.service.ts` + `refresh.token.service.ts` + JWT verify config — multiple high-severity gaps.
-4. `platformUtility/consumers/job.consumer.ts` + `maintenance.service.ts` — shared-singleton mutation, broken worker-mode detection, lock-never-released typo.
-5. `config/typeorm.config.ts` — `pg.types.setTypeParser(1700, parseFloat)` library-wide precision loss on every `numeric`/`decimal` column.
-6. `common/libraries/{custom.crypt,data.manager,common.subscriber}.ts` — weak crypto, bypassed user-binding cache key, transactional dispatch hazard for all 27 subscribers.
-
-**Per-module grades:** `common/` C+ · `auth/` C+ · `platformUtility/` C− · `system` services+controllers+libraries D+ · `system` data layer C+ · migrations+config+bootstrap B−.
-
-**Overall grade:** **C−.** Architecture skeleton is uniform and disciplined; the team clearly cares about subtle issues (constant-time compare, helmet hardening, storage refactor). But the eval surface, mass-assignment, plaintext refresh tokens, fail-open security defaults, SSRF, and a library-wide float-precision coercion are each independently shippable-stoppers if a downstream consumer handles real user data or money. Most fixes are localized.
-
----
-
-## Part B — Findings
-
-Severity legend: 🔴 Critical · 🟡 Important · 🟢 Minor
-ID prefix: **S** security · **M** money/precision · **B** confirmed bug · **A** systemic anti-pattern · **E** enhancement
-
-### S — Security (🔴 unless noted)
-
-- [ ] **S1 🔴 Six `eval()` call sites executing stored DB scripts.**
-  `system/libraries/code.evaluator.ts:27`, `system/libraries/process.script.execution.ts:39`, `system/libraries/execute.code.fix.ts:58`, `system/libraries/business.rule.query.evaluator.ts:53`, `system/libraries/business.rule.filter.validator.ts:74`, `system/libraries/security.rule.evaluator.ts:53`. Scripts run with full `process`/`require`/fs/network access; security decisions are themselves evaluated through `eval`. → Move to `isolated-vm` / sandboxed `worker_thread` with frozen globals, or a constrained expression DSL (`jsep`/`expr-eval`). Audit-log every script write.
-- [ ] **S2 🔴 Social login does not verify identity binding.** `auth/controllers/social.controller.ts:31-48`, `auth/services/social.service.ts:23-54`. No `aud`/`client_id` check, no `email_verified`, no `(provider, provider_user_id) → local user` mapping. → Validate audience, require verified email, look up/create local user keyed on provider+id, only then issue JWT.
-- [ ] **S3 🔴 JWT verification doesn't pin algorithm/issuer/audience.** `auth/services/auth.service.ts:96-102`. → `jwtService.verify(token, { algorithms: ['HS256'], issuer, audience })`.
-- [ ] **S4 🔴 Refresh tokens stored plaintext, no rotation, no reuse detection.** `auth/services/refresh.token.service.ts:30-49`, `auth/entities/refresh.token.entity.ts:18-19`, `auth/controllers/admin.auth.controller.ts:125-156`. DB leak → durable session creds. → Store sha256, rotate on use, family-chain reuse detection.
-- [ ] **S5 🔴 SSRF/DoS in RemoteRequestService.** `platformUtility/services/remote.request.service.ts:36-71`. No allow-list, no timeout, no `maxContentLength`, no `maxRedirects` cap, no IP/scheme filter. → Default timeout + content cap + hostname guard + explicit opt-in for internal hosts.
-- [ ] **S6 🔴 SQL injection in `security.rule.service.ts:73-104`.** `operation`, `identifier`, `id`, `sourceType` interpolated raw. Public API → consumer caller with user input gets dropped. → Parameterize via `sqlService.read(sql, params)`.
-- [ ] **S7 🔴 SQL injection in `scheduled.event.service.ts:38`.** `source_type` from DTO interpolated raw. → Parameterize.
-- [ ] **S8 🔴 SQL injection in `sync.all.code.job.ts:191, :265`.** `WHERE table_name = '${model.table_name}'`. → Parameterize.
-- [ ] **S9 🔴 SQL injection in `report.column.sync.job.ts:94`.** `query.replace(new RegExp(key, 'ig'), param.default_value)` — param value inlined into SQL. → Parameterize.
-- [ ] **S10 🔴 BaseController mass-assignment.** `system/controllers/base.controller.ts:107, :171`. `plainToInstance(entityObject, body)` lets clients write `created_by`, `updated_by`, `deleted_at`, `password_hash`, any column. → Allow-list from `ColumnManager.allowed`, strip body keys not in list, null out audit/soft-delete cols.
-- [ ] **S11 🔴 Stored-XSS via originalname-derived S3 keys + missing MIME validation.** `system/controllers/upload.controller.ts:42`, `system/services/storage.service.ts:449`, `system/services/upload.service.ts:96`. `FileTypeDetector` exists but isn't used in `UploadController`. SVG/HTML lands in public bucket served by CDN. → Use `FileTypeDetector` in controller, reject HTML/SVG for public folder, force `Content-Disposition: attachment`.
-- [ ] **S12 🔴 `TrimPipe` mutates body in-place + throws on non-body input.** `platformUtility/middlewares/trim.pipe.ts:24-31`. Registered globally → every query/param throws `BadRequest('Validation failed')`. Arrays not handled. → Clone input, handle `Array.isArray`, short-circuit non-body without throwing.
-- [ ] **S13 🔴 `CustomCrypt` PBKDF2 fixed salt + 1000 iterations.** `common/libraries/custom.crypt.ts:45`. Salt is literal `'salt'`; all historical ciphertexts share one key. → Per-installation random salt, ≥600k iterations.
-- [ ] **S14 🔴 `CustomCrypt` AES-256-CBC unauthenticated + plaintext fallback.** `common/libraries/custom.crypt.ts:80-241`. CBC malleable (padding-oracle); `tryPlaintextFallback()` returns attacker-controlled JSON on decryption failure. → Switch to AES-GCM, gate fallback behind explicit migration flag with metric, retire after backfill.
-- [ ] **S15 🔴 `Math.random()` for tokens/OTPs.** `common/libraries/platform.utility.ts:46-49, 96-101` — `generateRandomNumber`, `generateRandomAlpha`, `generateRandomAlphaNumeric`, `generateBase32`, `generateChars` all public statics. → `crypto.randomBytes`/`randomUUID`; separate non-security `pseudoRandom` helper if needed.
-- [ ] **S16 🔴 `InternalMiddleware` key stored in writable DB row.** `auth/middlewares/internal.middleware.ts:39-54`. `x-internal-token` compared (constant-time, good) against `properties.internal.server.key`, which any admin can edit. Header trivially forgeable via proxy header injection. → Read key from `AwsSecretService`/env, IP allow-list, audit-log every internal call.
-- [ ] **S17 🔴 `Auth.login` merges JWT claims over DB.** `auth/middlewares/jwt.middleware.ts:58` — `{...auth, ...accessObject, req}`. If JWT-encoded roles/permissions land in `auth` and aren't returned by `getUserObject`, they survive the merge. → Drop `...auth`, pass only `id`/`session_identifier`.
-- [ ] **S18 🔴 Fail-open security defaults.** `system/libraries/security.rule.evaluator.ts` returns `true` on missing `filter_condition`/empty `condition`/eval error; `business.rule.filter.validator.ts:71` defaults to `true`. → Default-deny.
-- [ ] **S19 🔴 Prototype-pollution-via-`props` + shared `jobInstance` mutation.** `platformUtility/consumers/job.consumer.ts:67-89`. `Object.assign(jobInstance, data.props)` on a long-lived singleton from BullMQ-JSON payloads → `__proto__` pollution + concurrent jobs overwriting each other's state. → Instantiate per execution, sanitize keys.
-- [ ] **S20 🔴 `pg.types.setTypeParser(1700, parseFloat)` library-wide.** `config/typeorm.config.ts:7-12`, `config/read.typeorm.config.ts`, `config/orm.config.ts`. Every `numeric`/`decimal` in every consumer becomes IEEE-754 float. Money precision lost invisibly. (Also tagged **M1**.) → Default to `string`, wrap arithmetic in `Decimal.js` / `big.js`, make opt-out explicit.
-- [ ] **S21 🟡 AWS credentials static long-lived keys via PropertyService.** `platformUtility/services/aws.config.service.ts:51-63`. Bypasses default credential chain (IRSA/instance profile). → Allow SDK chain when properties absent.
-- [ ] **S22 🟡 Sentry `includeLocalVariables: true` + no `beforeSend` PII scrubber.** `config/sentry.config.ts:5`. Local stack-frame vars include JWTs, password hashes, internal tokens. `SentryInterceptor` (`system/interceptors/sentry.interceptor.ts:14-21`) forwards `req` + `Auth.user()` unscrubbed. → Add `beforeSend` redactor, drop `includeLocalVariables` (or scrub).
-- [ ] **S23 🟡 `/health` endpoints unauthenticated, expose recon info.** `health.check.controller.ts:152-209` (Redis write probe on every call) + `/health/detailed` exposes `process.version`/`platform`/`uptime`. → Gate `detailed` behind `InternalMiddleware`; `/health` should just `PING`.
-- [ ] **S24 🟡 `/health/runtime-check` returns 200 on failure.** `health.check.controller.ts:361-429`. Monitors miss the down state. → Throw or return 503.
-- [ ] **S25 🟡 `CORS_ORIGINS` unset → `origin: true` (reflects any origin).** `main.ts:53`, `config/cors.config.ts:27`. → Deny-by-default with explicit opt-in env.
-- [ ] **S26 🟡 Rate-limit default `max: 10000/min` + `trust proxy 1` hop assumption.** `config/rate.limiter.config.ts:19`, `main.ts:57`. Effectively no limit + bypassable behind 2-hop proxy chain via `X-Forwarded-For` spoof. → Document hop count from env; lower default.
-- [ ] **S27 🟡 Mongo `logging: 'all'` default writes query bodies to file.** `config/mongo.config.ts:22`. No env gate. → Make env-driven like Postgres.
-- [ ] **S28 🟡 Real PII seeded into every consumer's DB.** `migrations/1619193418460-AddDefaultUserDataSeederTable.ts` — real email + phone for user id 1. → Replace with placeholder.
-- [ ] **S29 🟡 RemoteRequestService logs full request headers including `Authorization`.** `platformUtility/services/remote.request.service.ts:104-111`. → Redact auth headers before persist.
-- [ ] **S30 🟡 `InternalServerConnectService` logs full `options` including `x-client-secret`.** `system/services/internal.server.connect.service.ts:75`. → Drop log.
-- [ ] **S31 🟡 `ClientCredentialService` logs `'client secret validated', validated` on every auth.** `system/services/client.credential.service.ts:36`. → Drop log.
-- [ ] **S32 🟡 `refresh.property.cache.job` caches decrypted secrets plaintext in Redis 15min.** `system/jobs/refresh.property.cache.job.ts:24-28`. → Cache encrypted + decrypt on read, or document trust model.
-- [ ] **S33 🟡 `BasicAuthMiddleware` has no throttle/lockout.** `auth/middlewares/basic.auth.middleware.ts:50-57`. Brute-force surface; `UserService.assertCanAttemptLogin` not wired here. → Wire the same throttle as `AdminAuthController.login`.
-- [ ] **S34 🟡 `validateSession` creates session rows on verify path.** `auth/services/auth.service.ts:144-152`. `firstOrCreate` → DB-fill DoS via session_identifier scraping. → Use `findOne`.
-- [ ] **S35 🟡 `getToken` device check bypassable when no device bound.** `auth/controllers/admin.auth.controller.ts:138-139`. → Make device binding mandatory.
-- [ ] **S36 🟡 `logout` doesn't revoke active JWT.** `auth/controllers/admin.auth.controller.ts:164-184`. → Call `revokeSession()`.
-- [ ] **S37 🟡 `logout` returns soft-deleted refresh tokens (PII).** Same controller line 183. → Don't return tokens.
-- [ ] **S38 🟡 `ReportColumnSyncJob` HTTP-triggerable without report-edit permission.** `system/controllers/report.controller.ts:50`. → Add `reportService.hasAccess` check.
-- [ ] **S39 🟡 `JWT_SECRET` read directly via `process.env` without validation.** `config/jwt.config.ts:5-6`. Missing env → signs with `undefined`. → `ConfigService` with required-non-empty validation.
-- [ ] **S40 🟡 `CacheService.getStoreInfo` exposed publicly (`publicExposed = true`), leaks Redis host/port.** `platformUtility/services/cache.service.ts:128-182`. → Admin-only.
-- [ ] **S41 🟡 ZipService hardcoded Lambda URLs in ap-south-1.** `platformUtility/services/zip.service.ts:36, 72`. → Read from properties.
-- [ ] **S42 🟡 S3Service hardcoded `ContentType: 'text/plain'`** for `uploadFile`/`uploadContent`. `platformUtility/services/s3.service.ts:72, 102`. No `ServerSideEncryption`, no path/key sanitization. → Pass detected content-type, add SSE default, sanitize keys.
-
-### M — Money / precision (🔴 unless noted)
-
-- [ ] **M1 🔴 `pg.types.setTypeParser(1700, parseFloat)` library-wide** (also **S20**). Every `numeric`/`decimal` column silently loses precision in every consumer.
-- [ ] **M2 🟡 `@Column({ type: 'float', precision: 20, scale: 3 })` for duration columns.** `system/entities/event.log.entity.ts:24`, `system/entities/system.log.entity.ts:25`. Postgres `float` ignores `precision`/`scale` (only `numeric(p,s)` honors them) — duration drifts. → Switch to `numeric(20,3)` or integer ms.
-
-### B — Confirmed bugs (🟡 unless noted)
-
-- [ ] **B1 🔴 `data.manager.ts:336` — `Auth.id` (function reference) stored, not `Auth.id()`.** Cache user-binding check `data.user_id !== user.id` is always true → cache effectively dead, or worse if comparison ever matches. → Call `Auth.id()`.
-- [ ] **B2 🔴 `DatabaseEventEvaluator.isNewRecord` always false.** `common/libraries/database.event.evaluator.ts:28` — dead condition `!entity[col] && entity[col]`. Affects every subscriber via this evaluator. → Fix to `!this.event.databaseEntity?.[column]`.
-- [ ] **B3 🔴 `QueueService.isWorkerInstance()` returns `... || true` — always truthy.** `platformUtility/services/queue.service.ts:349-351`. Same bug in `StartupService.checkForWorkerQueue` (`startup.service.ts:40`). Pause path unreachable. → `=== 'true'`.
-- [ ] **B4 🔴 `MaintenanceService.removeRuntimeLock` sets `runtimeLock = true`** (typo for `false`). `platformUtility/services/maintenance.service.ts:141-144`. Lock never releases programmatically.
-- [ ] **B5 🔴 `JobConsumer.failedJob` writes `FailedBullJobEntity` on every retry attempt.** `platformUtility/consumers/job.consumer.ts:193-216`. No `attemptsMade >= maxAttempts` guard → table fills with retry duplicates.
-- [ ] **B6 🔴 `sync.all.code.job.ts:147` `allowed_permissions: 'raed'`** — typo for `'read'`. Affects every auto-created model.
-- [ ] **B7 🔴 `sync.all.code.job.ts:212-240 setColumn` inverts NOT NULL semantics** — `required: data.is_nullable` should be `!data.is_nullable`.
-- [ ] **B8 🔴 SQS polling deletes message before processing returns.** `system/jobs/sqs.polling.job.ts:33-56`. Process crash mid-handler = lost message. → Delete after success.
-- [ ] **B9 🔴 `report.column.sync.job.ts:99-104` catch returns `{}` → downstream `removeAllUnusedColumns` soft-deletes every column on the report.** Silent destructive failure.
-- [ ] **B10 🔴 `event.queue.service.ts:80-89, :105-114` swallow all errors silently.** Failed event triggers indistinguishable from success in logs.
-- [ ] **B11 🔴 `DeviceTokenService.setDeviceToken` infinite-recursion-on-save-error.** `auth/services/device.token.service.ts:38-42`. Persistent constraint violation blows the stack.
-- [ ] **B12 🔴 `ShutdownService` does not drain in-flight jobs.** `platformUtility/services/shutdown.service.ts:42-52` — `pause()` then sleep then exit; missing `worker.close(false)`. Active jobs killed mid-execution.
-- [ ] **B13 🔴 `CommonEntity.firstOrNew` / `firstOrCreate` do not honor soft delete.** `common/libraries/common.entity.ts:78-105`. Returns soft-deleted rows, skip create. → `withDeleted: false` or soft-delete-aware repo.
-- [ ] **B14 🟡 `JobConsumer.handleNextJob` swallows all errors with `console.log`.** `job.consumer.ts:121`. Chained jobs silently lost.
-- [ ] **B15 🟡 `set.event.queue.job.ts:40-49 while(true)` no break condition.** Poison row spins until BullMQ timeout. → Max iterations + poison-pill detection.
-- [ ] **B16 🟡 `cleanRecord` non-transactional delete+save.** `system/jobs/scheduled.event.job.ts:32-39`. Crash between = lost cursor.
-- [ ] **B17 🟡 `PreferenceController` missing `await preference.save()`.** `system/controllers/preference.controller.ts:81, :103`.
-- [ ] **B18 🟡 `writeRows` shadowed `row` variable.** `system/libraries/generate.downloadable.report.file.ts:248,254` — inner `let row` shadows outer; final `row.commit()` is dead code.
-- [ ] **B19 🟡 Report `OFFSET` pagination on raw SQL is O(N²)** on large reports. `system/libraries/generate.downloadable.report.file.ts:186-211`. → Keyset.
-- [ ] **B20 🟡 `entity.evaluator.ts` falsy-as-null** — `equals('flag', false)` returns false; same with `0` and `''`. → Explicit `=== null || === undefined`.
-- [ ] **B21 🟡 `CommonSubscriber.handleFloatColumn` rounds updated value but compares against unrounded original** → asymmetric, near-scale-boundary "no change". `common/libraries/common.subscriber.ts:195-202`.
-- [ ] **B22 🟡 `DateUtil` hard-codes IST offset `330` minutes.** `common/libraries/date.util.ts:172-188, 308-311`. Library ships to multi-tenant consumers. → Require offset or read from config.
-- [ ] **B23 🟡 `json.evaluator.ts:188, 194` `rule.value.split(',')` crashes if value is already an array.** Same code coerces with `Number()` → silent `NaN` ranges.
-- [ ] **B24 🟡 `common.job.ts:106-107` `parseInt(env)` with no fallback → `NaN` passed to BullMQ `removeOnComplete`.** Version-dependent behavior.
-- [ ] **B25 🟡 `getReportBaseQuery` regex injection.** `common/libraries/data.manager.ts`, `record.manager.ts`, `list.manager.ts`, `report.data.manager.ts` — `query.replace(new RegExp(key, 'ig'), value)` where key/value are unescaped. → Escape key, neutralize `$`-sequences, parameterize.
-- [ ] **B26 🟡 `DynamoService.updateItem` RMW without `ConditionExpression`** → lost updates. `platformUtility/services/dynamo.service.ts:139-145`.
-- [ ] **B27 🟡 `DynamoService.queryItem` returns `undefined` (not `[]`) when `Items` missing.** Same file:106. Callers iterating throw.
-- [ ] **B28 🟡 `SqsService.add` mutates caller's message; FIFO `MessageGroupId = 'group-1'` hardcoded** → serializes all messages. `platformUtility/services/sqs.service.ts:73`.
-- [ ] **B29 🟡 `MailService.send` returns `undefined` when `NOTIFICATION_DISABLED`** + no idempotency on redelivery → duplicate emails. `platformUtility/services/mail.service.ts:56-61`.
-- [ ] **B30 🟡 `AccessService.hasRoleIds([2])` short-circuits before user check.** `auth/services/access.service.ts:87`. → Decide whether public means anonymous; document or fix.
-- [ ] **B31 🟡 `UserService.LOGIN_FAIL_LIMIT/WINDOW` read `process.env` at class-load.** `auth/services/user.service.ts:29-30`. Library consumers loading env later get `NaN`. → Read via `ConfigService` at runtime.
-- [ ] **B32 🟡 `Hash.generateSalt(len)` passes `len` as bcrypt rounds.** `common/libraries/hash.ts:82-83`. Misleading name + dangerous if called with high "len" (DoS).
-- [ ] **B33 🟡 `MaintenanceMiddleware` mounts on `*` blocks `/health/*`.** `app.module.ts:51-55`. Ops can't detect maintenance via health probe.
-- [ ] **B34 🟡 `worker.ts` `app.init()` not awaited.** Fire-and-forget bootstrap.
-- [ ] **B35 🟡 `BaseMigrationUtility.primary()` defaults to `int`, not `bigint`.** `common/libraries/base.migration.utility.ts:158-172`. Log/audit tables (`sys_mail_logs`, `sys_data_logs`, `sys_event_queues`) will hit 2.1B ceiling. → Default `bigint`.
-- [ ] **B36 🟡 `getDisplayName` uses `str.substr(0, -3)` which returns `''`.** `system/jobs/model.scanner.job.ts:259-266`, `report.column.sync.job.ts:114-121`. `lastChar === '_id'` always false. Duplicated.
-- [ ] **B37 🟡 `model.scanner.job.ts:23` silently returns `model_hash` when model missing.** Caller can't distinguish success from not-found.
-- [ ] **B38 🟡 `refresh.material.view.job` doesn't check `now > date`** like the sibling scheduled-event job does. Past-dated events get enqueued.
-- [ ] **B39 🟡 `AwsConfigService.getProperty` truthy-drops `'0'`/`''`.** `platformUtility/services/aws.config.service.ts:74`.
-- [ ] **B40 🟡 `AuditService.setAuditRecord` uses `return` (not `continue`) inside `for` loop.** `platformUtility/services/audit.service.ts:71`. Skips remaining columns.
-- [ ] **B41 🟡 `AwsSecretService.getItem` swallows errors with `console.log` + logs full error object** (may contain SecretId). `platformUtility/services/aws.secret.service.ts:62-68`.
-- [ ] **B42 🟡 `PropertyService.set firstOrNew` without transaction → race on concurrent writes.** `system/services/property.service.ts`.
-- [ ] **B43 🟡 `DocumentService.setDocument` race; no DB unique on `(source_type, source_id, file_hash)`.**
-- [ ] **B44 🟡 `LoggerService` singleton state leaks across requests** — concurrent requests share `logs[]`. `system/services/logger.service.ts`. → Request-scope or context-store.
-- [ ] **B45 🟡 `ReportEntity.first(...)` result passed to manager without null guard.** `system/controllers/report.controller.ts:87, :118`.
-- [ ] **B46 🟡 Migration `1599567001962-AddUserSequence.ts:5` `queryRunner.query()` not awaited.**
-- [ ] **B47 🟡 `getIpFromRequest` returns unparsed `x-forwarded-for` (CSV string).** `common/libraries/platform.utility.ts:312-323`.
-- [ ] **B48 🟡 `Hash.hashMD5(${date.now()}-${8-digit-int})` collision risk in same ms.** Used as request identifier in `data.manager.ts:333`, `report.data.manager.ts:252`. → `crypto.randomUUID()`.
-- [ ] **B49 🟢 `UserController` constructor parameter named `s` instead of `userService`.** Readability.
-- [ ] **B50 🟢 `getStoreInfo` debug method publicly exposed via `publicExposed = true`.** (Also **S40**.)
-
-### A — Systemic anti-patterns (these recur across the codebase)
-
-- [ ] **A1 🔴 Subscribers dispatch BullMQ jobs synchronously inside the source DB transaction.** `common/libraries/common.subscriber.ts:35-46, 55-61`. 27 subscribers carry this hazard: if outer transaction rolls back, the job is already in Redis processing a stale/nonexistent record. → Enqueue inside `queryRunner.afterTransactionCommit` or buffer-and-flush-on-commit. **Fix once in `CommonSubscriber`, fixes all 27.**
-- [ ] **A2 🔴 No idempotency keys on side-effecting jobs.** `UserGroupMemberJob`, `UserGroupPermissionJob`, `RefreshMaterialViewJob`, `SetScheduledEventJob`, `SetEventQueueJob`, `SyncAllCodeJob`. At-least-once queue + run-once assumptions → duplicates on redelivery. → DB unique constraints + `INSERT ... ON CONFLICT DO NOTHING` / `firstOrCreate({source_type, source_id, ...})`.
-- [ ] **A3 🔴 25+ entities use `@Column('json')` typed as `any`** instead of `jsonb` + typed DTO. `report.entity.ts:60-63`, `event.queue.entity.ts:30,47`, `mail.log.entity.ts:45-49`, `column.entity.ts:28`, etc. Postgres `json` has no GIN; library consumers can't enumerate the shape. → Migrate all to `jsonb`; type each `attributes`/`payload`/`data` with a DTO (`DocumentAttributesDto` is the template).
-- [ ] **A4 🔴 Six `eval()` call sites for business / security / code-fix rules** (also **S1**). Single highest-risk pattern in the codebase.
-- [ ] **A5 🔴 Manual SQL string building with regex placeholder substitution** in 5 manager classes (`data`/`record`/`list`/`report.data`/`report.list` manager). Soft-delete filter, join definitions, parameter substitution drift between managers. Tripwire (`common/libraries/sql.safety.ts`) exists but isn't applied at building sites — only at executing service. → Collapse onto a single internal query builder; wire tripwire at every manager exit.
-- [ ] **A6 🔴 User-controlled strings flow into raw SQL templates in 7+ places** (S6–S10, B25). Escape helper `escapeSqlString` exists; use it everywhere or parameterize.
-- [ ] **A7 🔴 Fail-open security / business rule evaluators** (also **S18**, **B**). Default-deny baseline missing.
-- [ ] **A8 🟡 Error swallowing with `console.log`.** `aws.secret.service.ts:67`, `job.consumer.ts:121`, `cache.service.ts:104`, `custom.crypt.ts`, `event.queue.service.ts:80,105`, `report.column.sync.job.ts:99`, `sync.all.code.job.ts:321-335`. → Route through `CustomLogger`, never swallow.
-- [ ] **A9 🟡 Active Record entity access (`Entity.first/find/firstOrNew`) in controllers and libraries** — no repository abstraction; couples to TypeORM forever; untestable without DB. The storage refactor shows the team can do DI well; extend pattern to data access.
-- [ ] **A10 🟡 Polymorphic FKs (`source_type` MD5-hash + `source_id`) with no DB-level referential integrity, no orphan-cleanup job.** 12+ entities (`column`, `comment`, `document`, `event_queue`, `mail_log`, …). → Document contract + add sweeper job.
-- [ ] **A11 🟡 Static singletons holding context** (`Auth`, `PlatformUtility.setEntity/Service/Job` mutable global registries, `CustomLogger` env-cached at first call). Multi-tenant / cross-request fragility.
-- [ ] **A12 🟡 Cryptography assembled from primitives, not a hardened library.** `CustomCrypt` (PBKDF2-fixed-salt + AES-CBC + JSON.parse fallback) and `Hash` (bcrypt + MD5 + xxhash). Migration comments show team knows about legacy formats — productionize a one-shot re-encrypt job and remove fallback.
-- [ ] **A13 🟡 Library-as-app coupling.** `common/` imports from `system/entities/*`, `platformUtility/services/*`, `auth/dtos/*`. Consumers pulling `common` transitively get everything. → Split `common` into true-primitive layer (no system/auth imports) + higher-level managers layer.
-- [ ] **A14 🟡 27 subscribers are 17-line stubs of identical shape.** → Decorator factory `@SubscribeFor(Entity, JobClass)` + registry; drops to 1 file.
-- [ ] **A15 🟡 Magic IDs scattered.** Role id 1 = superadmin, role id 2 = public, user id 2 = internal middleware login, source-type MD5 literals inlined in `column.mapper.job.ts:11-24`, `relationship.mapper.job.ts:11-20`, `model.service.ts:49-67`. → `Role.SUPER_ADMIN`, `Role.PUBLIC`, `User.INTERNAL`, use `SourceHash.*` consistently.
-- [ ] **A16 🟡 Single-file migrations bundle schema + data fill + index in one transaction.** No two-phase pattern (deploy column → backfill → flip NOT NULL → drop old). Migration DSL has no `CREATE INDEX CONCURRENTLY` helper. → Add DSL helpers; document multi-stage pattern.
-- [ ] **A17 🟡 `PropertyService` is the de-facto config oracle for everything** (URLs, secrets, gateway names, FCM topics). Every service hits it; no centralized cache or rotation. → Extract `CachedProperty<T>` with TTL.
-- [ ] **A18 🟡 PII not redacted before Sentry / logs** (also **S22**, **S29**, **S30**, **S31**, **S32**). → Single redaction list applied at all three exit points (Sentry beforeSend, RemoteRequestService.saveLog, CommonJob.saveLogs).
-- [ ] **A19 🟡 Inheritance for a flag.** `CommonService.publicExposed = false` and several subclasses extend just to flip the flag. → Decorator or composition.
-- [ ] **A20 🟡 Falsy-as-null conflation** (also **B20**). `Auth.id()` returns `boolean | number`; `EntityEvaluator` treats `0`/`''`/`false` as null; soft-delete checks via `if (deleted_at)`. → Tighten return types to `T | null`, explicit `=== null` checks.
-- [ ] **A21 🟡 Float/decimal precision** (also **M1**, **M2**). Library-wide.
-- [ ] **A22 🟢 No `*.spec.ts` for the most load-bearing classes:** all 5 managers (`data`/`record`/`list`/`report.data`/`report.list`), `CommonSubscriber`, `CommonJob`, `BaseMigrationUtility`, every middleware, all subscribers, all jobs. → Backfill priority: managers → middlewares → subscribers → jobs.
-
-### E — Enhancements
-
-- [ ] **E1** Extract `AwsClientFactory` across S3/SQS/Dynamo/Secrets/SES — single credential-chain + retry config.
-- [ ] **E2** Storage refactor template — apply same adapter-registry pattern to SMS (Twilio/MessageBird), Push (FCM/APNs), Secrets backends.
-- [ ] **E3** Sandboxed script execution (`isolated-vm` or DSL) for the 6 eval sites. **Required to land S1/A4 safely.**
-- [ ] **E4** Migration DSL: add `concurrentIndex()`, `bigint`-default `primary()`, two-phase migration helper, `CREATE INDEX CONCURRENTLY` lint.
-- [ ] **E5** CI lint script: `synchronize: true`, `DROP COLUMN`, `NOT NULL` without backfill, `CREATE INDEX` without `CONCURRENTLY`, `UPDATE`/`DELETE` without `WHERE`, `eval(`, template-string SQL, `@Column('json')`, `Math.random`. Pre-commit hook.
-- [ ] **E6** Centralize role/source-hash/user-id constants.
-- [ ] **E7** `Auth.requireUser()` helper that throws `NoLoggedUserException`; tighten `Auth.id()` to `number | null`.
-- [ ] **E8** Backfill `*.spec.ts` for managers / middlewares / crypto / subscribers / jobs (priority order).
-- [ ] **E9** Single PII redaction list applied at Sentry beforeSend + RemoteRequestService.saveLog + CommonJob.saveLogs + LoggerService.
-- [ ] **E10** Remove ~15 leftover `console.log` debug statements in prod code.
-- [ ] **E11** Move all secrets to `AwsSecretService` (JWT_SECRET, internal.server.key, AWS keys).
-- [ ] **E12** Repository / data-access abstraction for entity access (mirror storage adapter pattern).
-- [ ] **E13** Migrate from `pg.types` decimal→float to decimal→string + Decimal.js arithmetic wrapper. Document as breaking change for consumers.
-- [ ] **E14** Migrate all `@Column('json')` → `'jsonb'` + typed DTOs (single multi-table migration).
-- [ ] **E15** Refresh-token rotation + family-chain reuse detection.
-- [ ] **E16** Remove `test.mentity.ts` and `test.mongo.job.ts` from production module.
-- [ ] **E17** Two-phase migration pattern doc + examples.
-- [ ] **E18** Sweeper job for orphan rows on polymorphic FKs.
-- [ ] **E19** Subscriber decorator + registry → drop 27 stubs to 1 file.
-- [ ] **E20** Migration filename cleanup — 60+ files end in `.ts.ts`.
-
----
-
-## Part C — Phase plan
-
-| Phase | Goal | Risk to prod | Items |
-|---|---|---|---|
-| **0 — Safety nets** | Observability, rollback playbook, feature-flag pattern | None | E5 (CI lint), E10 (drop debug logs), E16 (drop test mentity), E20 (filename cleanup) |
-| **1 — Foundations** | Helpers, TS strictness, audit hooks | None | E4 (DSL helpers), E6 (constants), E7 (Auth helpers), E9 (PII redactor) |
-| **2 — Pure bugs (B-series)** | One PR per item; quick wins | Low | B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, B11, B12, B13, B14–B50 |
-| **3 — Security (S-series)** | Discussion per item, staging verify | Medium | S2, S3, S4, S5, S6–S9, S10, S11, S12, S13, S14, S15, S16, S17, S18, S19, plus S21–S42 |
-| **4 — Money / precision (M-series)** | Multi-week, careful migration | High | M1 (pg.types — breaking), M2 (float→numeric duration cols) |
-| **5 — Systemic patterns (A-series)** | Refactor with flags | Medium | A1 (subscriber dispatch), A2 (idempotency), A3 (json→jsonb), A5 (manager SQL), A6 (template SQL), A7 (fail-closed), A8 (no swallow), A10 (FK orphans), A12 (crypto), A14 (subscriber decorator), A15 (constants), A16 (two-phase migration), A17 (cached property), A18 (PII), A20 (falsy/null), A22 (tests) |
-| **6 — Architecture (E-series)** | Long horizon; incremental | Low | E1, E2, E3 (sandboxed eval — blocks A4/S1), E11, E12, E13 (pg.types), E14 (json→jsonb), E15 (refresh tokens), E17, E18, E19 |
-
-**Suggested kickoff (recommended):** Do **B1** as the trial fix end-to-end (one-line: `Auth.id` → `Auth.id()`, add a spec, ship). Establishes the per-change template: ID-tagged PR title, regression test, Linear issue closed. Then take the rest of phase 2 in any order — they're independent.
-
-**Critical blockers if shipping to a new consumer that handles money or real PII:** S1/A4 (eval), S2/S3/S4 (auth), S5 (SSRF), S10/S11 (mass-assignment + upload XSS), S13/S14 (crypto), M1 (precision), A1 (subscriber dispatch), A2 (idempotency).
-
----
-
-## Per-module grades
-
-| Module | Files | LOC | Grade | Headline |
-|---|---:|---:|:---:|---|
-| `common/` | 81 | 9,198 | **C+** | Solid breadth, but `Auth.id` ref bug, PBKDF2 fixed-salt, plaintext-fallback decrypt, `Math.random` for tokens, falsy-as-null systemic |
-| `auth/` | 39 | 2,550 | **C+** | Constant-time compare ✓, bcrypt-12 ✓, but social-login trust, JWT-alg-not-pinned, plaintext refresh tokens, InternalMiddleware writable key |
-| `platformUtility/` | 85 | 8,179 | **C−** | `isWorkerInstance()||true`, `removeRuntimeLock=true`, shared `jobInstance` mutation, SSRF, retry-amplified failed-job rows, no idempotency |
-| `system/` services + controllers + libraries | 61 | 8,400 | **D+** | 6 `eval()` RCE sites, mass-assignment, fail-open security, stored-XSS via originalname; storage subsystem is B+ |
-| `system/` data layer + jobs + subscribers | ~178 | ~6,600 | **C+** | Subscriber-dispatch-in-tx hazard × 27, idempotency gaps × 6, json-not-jsonb × 25, `'raed'` typo |
-| migrations + config + bootstrap | ~163 | ~3,800 | **B−** | `pg.types` precision coercion, default-int PKs, no concurrent-index DSL, real-PII seeded; bootstrap is mostly hardened |
-
-**Overall: C−.** Localized fixes can lift to **B** within a focused 4-6 week effort; reaching **A** requires the eval-sandbox migration (E3) and the pg.types-precision change (M1/E13), both multi-month projects with downstream impact.