chore(utils): migrate to shared random/ID utilities and add enforcement linting

Author: waleedlatif1

.cursor/rules/global.mdc

@@ -37,6 +37,18 @@ const shortId = generateShortId()
 const tiny = generateShortId(8)
 ```
 
+## Randomness
+Never use `Math.random()`, `crypto.randomBytes()`, or one-off random helpers. Use `@sim/utils/random`:
+
+- `generateRandomBytes(size)` — secure bytes
+- `generateRandomHex(byteLength)` — lowercase hex for salts, object keys, and trace/span IDs
+- `generateRandomString(size?, alphabet?)` — URL-safe or custom-alphabet suffixes
+- `randomFloat()` — sampling and jitter in `[0, 1)`
+- `randomInt(maxExclusive)` — unbiased integer ranges
+- `randomItem(items)` — unbiased array selection
+
+Use these for IDs, suffixes, MIME boundaries, storage keys, salts, tokens, retry jitter, telemetry sampling, and random UI palette/name selection. Do not add a `Math.random()` fallback; `crypto.getRandomValues()` is the standard CSPRNG primitive and works in insecure browser contexts. Only standalone published packages that cannot depend on `@sim/utils` may use Web Crypto directly, with a comment explaining why.
+
 ## Common Utilities
 Use shared helpers from `@sim/utils` instead of writing inline implementations:
 

0

@@ -9,6 +9,7 @@ You are a professional software engineer. All code must follow best practices: a
 - **Comments**: Use TSDoc for documentation. No `====` separators. No non-TSDoc comments
 - **Styling**: Never update global styles. Keep all styling local to components
 - **ID Generation**: Never use `crypto.randomUUID()`, `nanoid`, or `uuid` package. Use `generateId()` (UUID v4) or `generateShortId()` (compact) from `@sim/utils/id`
+- **Randomness**: Never use `Math.random()`, `crypto.randomBytes()`, or ad-hoc random helpers. Use `@sim/utils/random`: `generateRandomBytes`, `generateRandomHex`, `generateRandomString`, `randomFloat`, `randomInt`, or `randomItem`. Use `randomInt` / `randomItem` for unbiased selection, jitter, and sampling; use hex/string helpers for suffixes, object keys, boundaries, salts, and tokens. Do not add a `Math.random()` fallback — the shared util uses `crypto.getRandomValues()`, which is the standard CSPRNG primitive that also works in non-secure browser contexts. Only standalone published packages that cannot depend on `@sim/utils` may use Web Crypto directly, with a comment explaining why.
 - **Package Manager**: Use `bun` and `bunx`, not `npm` and `npx`
 
 ## Architecture

AGENTS.md

@@ -10,6 +10,7 @@ You are a professional software engineer. All code must follow best practices: a
 - **Comments**: Use TSDoc for documentation. No `====` separators. No non-TSDoc comments
 - **Styling**: Never update global styles. Keep all styling local to components
 - **ID Generation**: Never use `crypto.randomUUID()`, `nanoid`, or `uuid` package. Use `generateId()` (UUID v4) or `generateShortId()` (compact) from `@sim/utils/id`
+- **Randomness**: Never use `Math.random()`, `crypto.randomBytes()`, or ad-hoc random helpers. Use `@sim/utils/random`: `generateRandomBytes`, `generateRandomHex`, `generateRandomString`, `randomFloat`, `randomInt`, or `randomItem`. Use `randomInt` / `randomItem` for unbiased selection, jitter, and sampling; use hex/string helpers for suffixes, object keys, boundaries, salts, and tokens. Do not add a `Math.random()` fallback — the shared util uses `crypto.getRandomValues()`, which is the standard CSPRNG primitive that also works in non-secure browser contexts. Only standalone published packages that cannot depend on `@sim/utils` may use Web Crypto directly, with a comment explaining why.
 - **Common Utilities**: Use shared helpers from `@sim/utils` instead of inline implementations. `sleep(ms)` from `@sim/utils/helpers` for delays, `toError(e)` from `@sim/utils/errors` to normalize caught values.
 - **Package Manager**: Use `bun` and `bunx`, not `npm` and `npx`
 

CLAUDE.md

@@ -13,6 +13,7 @@ import {
   VARIABLE_OPERATIONS,
   WORKFLOW_OPERATIONS,
 } from '@sim/realtime-protocol/constants'
+import { randomFloat } from '@sim/utils/random'
 import { getActiveWorkflowContext } from '@sim/workflow-authz'
 import { loadWorkflowFromNormalizedTablesRaw } from '@sim/workflow-persistence/load'
 import { mergeSubBlockValues } from '@sim/workflow-persistence/subblocks'
@@ -204,7 +205,7 @@ export async function persistWorkflowOperation(workflowId: string, operation: an
       throw new Error(`Workflow ${workflowId} is archived or unavailable`)
     }
 
-    if (op === BLOCK_OPERATIONS.UPDATE_POSITION && Math.random() < 0.01) {
+    if (op === BLOCK_OPERATIONS.UPDATE_POSITION && randomFloat() < 0.01) {
       logger.debug('Socket DB operation sample:', {
         operation: op,
         target,

apps/realtime/src/database/operations.ts

@@ -5,6 +5,7 @@
  */
 import { createServer, request as httpRequest } from 'http'
 import { createMockLogger } from '@sim/testing'
+import { randomInt } from '@sim/utils/random'
 import { afterEach, beforeAll, beforeEach, describe, expect, it, vi } from 'vitest'
 import { createSocketIOServer } from '@/config/socket'
 import { MemoryRoomManager } from '@/rooms'
@@ -95,7 +96,7 @@ describe('Socket Server Index Integration', () => {
   })
 
   beforeEach(async () => {
-    PORT = 3333 + Math.floor(Math.random() * 1000)
+    PORT = 3333 + randomInt(1000)
 
     httpServer = createServer()
 
@@ -120,7 +121,7 @@ describe('Socket Server Index Integration', () => {
       httpServer.on('error', (err: any) => {
         clearTimeout(timeout)
         if (err.code === 'EADDRINUSE') {
-          PORT = 3333 + Math.floor(Math.random() * 1000)
+          PORT = 3333 + randomInt(1000)
           httpServer.close(() => {
             httpServer.listen(PORT, '0.0.0.0', () => {
               resolve()

apps/realtime/src/index.test.ts

@@ -213,6 +213,7 @@ describe('Chat OTP API Route', () => {
 
     vi.stubGlobal('crypto', {
       ...crypto,
+      getRandomValues: crypto.getRandomValues.bind(crypto),
       randomUUID: vi.fn().mockReturnValue('test-uuid-1234'),
     })
 

apps/sim/app/api/chat/[identifier]/otp/route.test.ts

@@ -1,8 +1,8 @@
-import { randomInt } from 'crypto'
 import { db } from '@sim/db'
 import { chat, verification } from '@sim/db/schema'
 import { createLogger } from '@sim/logger'
 import { generateId } from '@sim/utils/id'
+import { randomInt } from '@sim/utils/random'
 import { and, eq, gt, isNull } from 'drizzle-orm'
 import type { NextRequest } from 'next/server'
 import { renderOTPEmail } from '@/components/emails'
@@ -36,7 +36,7 @@ const OTP_EMAIL_RATE_LIMIT: TokenBucketConfig = {
 }
 
 function generateOTP(): string {
-  return randomInt(100000, 1000000).toString()
+  return (randomInt(900000) + 100000).toString()
 }
 
 const OTP_EXPIRY = 15 * 60 // 15 minutes

apps/sim/app/api/chat/[identifier]/otp/route.ts

@@ -3,6 +3,7 @@ import { createHash } from 'crypto'
 import fsPromises, { readFile } from 'fs/promises'
 import path from 'path'
 import { createLogger } from '@sim/logger'
+import { generateRandomString, LOWERCASE_ALPHANUMERIC_ALPHABET } from '@sim/utils/random'
 import binaryExtensionsList from 'binary-extensions'
 import { type NextRequest, NextResponse } from 'next/server'
 import { fileParseContract } from '@/lib/api/contracts/storage-transfer'
@@ -552,7 +553,7 @@ async function handleCloudFile(
       // If file is already from execution context, create UserFile reference without re-uploading
       if (context === 'execution') {
         userFile = {
-          id: `file_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+          id: `file_${Date.now()}_${generateRandomString(7, LOWERCASE_ALPHANUMERIC_ALPHABET)}`,
           name: filename,
           url: normalizedFilePath,
           size: fileBuffer.length,

apps/sim/app/api/files/parse/route.ts

@@ -1,4 +1,5 @@
 import { createLogger } from '@sim/logger'
+import { generateRandomString, LOWERCASE_ALPHANUMERIC_ALPHABET } from '@sim/utils/random'
 import { type NextRequest, NextResponse } from 'next/server'
 import { fileManageContract } from '@/lib/api/contracts/tools/file'
 import { parseRequest } from '@/lib/api/server'
@@ -314,7 +315,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
         }
 
         const lockKey = `file-append:${workspaceId}:${existing.id}`
-        const lockValue = `${Date.now()}-${Math.random().toString(36).slice(2)}`
+        const lockValue = `${Date.now()}-${generateRandomString(10, LOWERCASE_ALPHANUMERIC_ALPHABET)}`
         const acquired = await acquireLock(lockKey, lockValue, 30)
         if (!acquired) {
           return NextResponse.json(