@tuturuuu/utils 0.8.0 → 0.10.0

package/src/__tests__/app-url.test.ts

@@ -264,6 +264,7 @@ describe('Portless app origin registry', () => {
       'https://finance.tuturuuu.localhost',
       'https://hive.tuturuuu.localhost',
       'https://realtime.hive.tuturuuu.localhost',
+      'https://infra.tuturuuu.localhost',
       'https://inventory.tuturuuu.localhost',
       'https://learn.tuturuuu.localhost',
       'https://mail.tuturuuu.localhost',
@@ -276,6 +277,7 @@ describe('Portless app origin registry', () => {
       'https://rewise.tuturuuu.localhost',
       'https://shortener.tuturuuu.localhost',
       'https://storefront.tuturuuu.localhost',
+      'https://tanstack.tuturuuu.localhost',
       'https://tasks.tuturuuu.localhost',
       'https://teach.tuturuuu.localhost',
       'https://track.tuturuuu.localhost',

package/src/__tests__/task-description-codec.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest';
+import {
+  createTaskDescriptionPayload,
+  decodeTaskDescriptionYjsState,
+  encodeTaskDescriptionYjsState,
+  parseMarkdownTaskDescriptionContent,
+  parsePersistedTaskDescriptionContent,
+  parseTaskDescriptionInput,
+  parseTaskDescriptionJson,
+  taskDescriptionPlainText,
+  taskDescriptionYjsStateFromBase64,
+  taskDescriptionYjsStateFromBytesJson,
+  taskDescriptionYjsStateToBase64,
+} from '../task-description-codec';
+
+describe('task description codec', () => {
+  it('creates storage payloads from plain text', () => {
+    const payload = createTaskDescriptionPayload(
+      'First paragraph\n\nSecond paragraph'
+    );
+
+    expect(payload.description).toContain('First paragraph');
+    expect(payload.description_yjs_state?.length ?? 0).toBeGreaterThan(0);
+    expect(taskDescriptionPlainText(payload.content)).toContain(
+      'Second paragraph'
+    );
+  });
+
+  it('parses common markdown blocks into TipTap content', () => {
+    const content = parseMarkdownTaskDescriptionContent(
+      [
+        '# Release notes',
+        '',
+        '- [x] Confirm CLI auth',
+        '- [ ] Ship task descriptions',
+        '',
+        '> Keep this scoped',
+        '',
+        'Visit [Tuturuuu](https://tuturuuu.com) with **bold** text.',
+        '',
+        '```ts',
+        'const shipped = true;',
+        '```',
+      ].join('\n')
+    );
+
+    const plainText = taskDescriptionPlainText(content);
+
+    expect(plainText).toContain('# Release notes');
+    expect(plainText).toContain('[x] Confirm CLI auth');
+    expect(plainText).toContain('> Keep this scoped');
+    expect(plainText).toContain('const shipped = true;');
+  });
+
+  it('round-trips TipTap content through Yjs base64', () => {
+    const content = parseTaskDescriptionInput(
+      JSON.stringify({
+        content: [
+          {
+            attrs: { level: 2 },
+            content: [{ text: 'Task heading', type: 'text' }],
+            type: 'heading',
+          },
+        ],
+        type: 'doc',
+      }),
+      'json'
+    );
+    const yjsState = encodeTaskDescriptionYjsState(content);
+    const encoded = taskDescriptionYjsStateToBase64(yjsState);
+    const decoded = decodeTaskDescriptionYjsState(
+      taskDescriptionYjsStateFromBase64(encoded ?? '')
+    );
+
+    expect(taskDescriptionPlainText(decoded)).toContain('Task heading');
+  });
+
+  it('rejects explicit non-doc JSON input', () => {
+    expect(() => parseTaskDescriptionJson('{"text":"not a doc"}')).toThrow(
+      /TipTap doc/
+    );
+  });
+
+  it('validates bytes JSON input', () => {
+    expect(taskDescriptionYjsStateFromBytesJson('[1,2,255]')).toEqual([
+      1, 2, 255,
+    ]);
+    expect(() => taskDescriptionYjsStateFromBytesJson('[1,999]')).toThrow(
+      /array of byte/
+    );
+  });
+
+  it('prefers persisted Yjs state over stale description JSON', () => {
+    const fresh = createTaskDescriptionPayload('Fresh state');
+    const content = parsePersistedTaskDescriptionContent({
+      description: JSON.stringify({
+        content: [
+          {
+            content: [{ text: 'Stale projection', type: 'text' }],
+            type: 'paragraph',
+          },
+        ],
+        type: 'doc',
+      }),
+      description_yjs_state: fresh.description_yjs_state,
+    });
+
+    expect(taskDescriptionPlainText(content)).toContain('Fresh state');
+  });
+});

package/src/abuse-protection/__tests__/backend-rate-limit.test.ts

@@ -2,8 +2,6 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
   blockIPEdge: vi.fn(),
-  checkUserSuspension: vi.fn(),
-  suspendUser: vi.fn(),
 }));
 
 vi.mock('../edge', () => ({
@@ -11,14 +9,6 @@ vi.mock('../edge', () => ({
     mocks.blockIPEdge(...args),
 }));
 
-vi.mock('../user-suspension', () => ({
-  checkUserSuspension: (
-    ...args: Parameters<typeof mocks.checkUserSuspension>
-  ) => mocks.checkUserSuspension(...args),
-  suspendUser: (...args: Parameters<typeof mocks.suspendUser>) =>
-    mocks.suspendUser(...args),
-}));
-
 import {
   cascadeBackendRateLimitToProxyBan,
   isBackendRateLimitError,
@@ -28,8 +18,6 @@ describe('backend-rate-limit', () => {
   beforeEach(() => {
     vi.clearAllMocks();
     mocks.blockIPEdge.mockResolvedValue(null);
-    mocks.checkUserSuspension.mockResolvedValue({ suspended: false });
-    mocks.suspendUser.mockResolvedValue(true);
   });
 
   describe('isBackendRateLimitError', () => {
@@ -51,16 +39,7 @@ describe('backend-rate-limit', () => {
   });
 
   describe('cascadeBackendRateLimitToProxyBan', () => {
-    it('blocks the IP without suspending an identified user', async () => {
-      const blockInfo = {
-        id: 'block-1',
-        blockLevel: 1,
-        reason: 'api_abuse',
-        blockedAt: new Date(),
-        expiresAt: new Date(Date.now() + 300_000),
-      };
-      mocks.blockIPEdge.mockResolvedValue(blockInfo);
-
+    it('does not hard-ban a known client IP for a backend rate-limit signal', async () => {
       const result = await cascadeBackendRateLimitToProxyBan({
         endpoint: '/api/ai/chat/new',
         ipAddress: '203.0.113.10',
@@ -68,46 +47,32 @@ describe('backend-rate-limit', () => {
         userId: 'user-1',
       });
 
-      expect(result).toBe(blockInfo);
-      expect(mocks.blockIPEdge).toHaveBeenCalledWith(
-        '203.0.113.10',
-        'api_abuse'
-      );
-      expect(mocks.checkUserSuspension).not.toHaveBeenCalled();
-      expect(mocks.suspendUser).not.toHaveBeenCalled();
+      expect(result).toBeNull();
+      expect(mocks.blockIPEdge).not.toHaveBeenCalled();
     });
 
-    it('does not inspect existing user suspensions', async () => {
-      mocks.checkUserSuspension.mockResolvedValue({
-        suspended: true,
-        reason: 'already suspended',
-      });
-
-      await cascadeBackendRateLimitToProxyBan({
+    it('does not hard-ban auth backend rate-limit signals', async () => {
+      const result = await cascadeBackendRateLimitToProxyBan({
         endpoint: '/api/ai/chat/new',
         ipAddress: '203.0.113.10',
         source: 'auth',
         userId: 'user-1',
       });
 
-      expect(mocks.suspendUser).not.toHaveBeenCalled();
-      expect(mocks.blockIPEdge).toHaveBeenCalledWith(
-        '203.0.113.10',
-        'api_abuse'
-      );
-      expect(mocks.checkUserSuspension).not.toHaveBeenCalled();
+      expect(result).toBeNull();
+      expect(mocks.blockIPEdge).not.toHaveBeenCalled();
     });
 
-    it('does not suspend the user when the client IP is unavailable', async () => {
-      await cascadeBackendRateLimitToProxyBan({
+    it('returns null when the client IP is unavailable', async () => {
+      const result = await cascadeBackendRateLimitToProxyBan({
         endpoint: '/api/ai/chat/new',
         ipAddress: 'unknown',
         source: 'database',
         userId: 'user-1',
       });
 
+      expect(result).toBeNull();
       expect(mocks.blockIPEdge).not.toHaveBeenCalled();
-      expect(mocks.suspendUser).not.toHaveBeenCalled();
     });
   });
 });

package/src/abuse-protection/__tests__/edge-trust.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
   getClient: vi.fn(),
+  get: vi.fn(),
   mget: vi.fn(),
   set: vi.fn(),
 }));
@@ -13,6 +14,7 @@ vi.mock('../../upstash-rest', () => ({
 function mockRedisClient() {
   mocks.getClient.mockResolvedValue({
     mget: (...keys: string[]) => mocks.mget(...keys),
+    get: (key: string) => mocks.get(key),
     set: (key: string, value: unknown, options?: unknown) =>
       mocks.set(key, value, options),
   });
@@ -22,6 +24,7 @@ describe('edge-trust cache', () => {
   beforeEach(() => {
     vi.resetModules();
     mocks.getClient.mockReset();
+    mocks.get.mockReset();
     mocks.mget.mockReset();
     mocks.set.mockReset();
   });
@@ -80,6 +83,17 @@ describe('edge-trust cache', () => {
     expect(await getCachedTrustMultiplier(['session:aaa'])).toBe(2.5);
   });
 
+  it('returns neutral verified session entries without treating plain neutral entries as active', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue([{ m: 1, verified: true }, 1]);
+
+    const { getCachedTrustEntries } = await import('../edge-trust.js');
+    const entries = await getCachedTrustEntries(['session:aaa', 'session:bbb']);
+
+    expect(entries.get('session:aaa')).toEqual({ m: 1, verified: true });
+    expect(entries.has('session:bbb')).toBe(false);
+  });
+
   it('fails open to a neutral multiplier when Redis errors', async () => {
     mockRedisClient();
     mocks.mget.mockRejectedValue(new Error('redis down'));
@@ -139,6 +153,53 @@ describe('edge-trust cache', () => {
     });
   });
 
+  it('writes neutral verified session markers without writing non-session subjects', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue([null]);
+    mocks.set.mockResolvedValue('OK');
+
+    const { writeVerifiedSessionCacheForSubjects } = await import(
+      '../edge-trust.js'
+    );
+    await writeVerifiedSessionCacheForSubjects(
+      ['session:aaa', 'cidr:1.2.3.0/24'],
+      600
+    );
+
+    expect(mocks.set).toHaveBeenCalledTimes(1);
+    expect(mocks.set).toHaveBeenCalledWith(
+      'trust:mult:session:aaa',
+      { m: 1, verified: true },
+      { ex: 600 }
+    );
+  });
+
+  it('does not downgrade elevated trust entries when writing verified session markers', async () => {
+    mockRedisClient();
+    mocks.mget.mockResolvedValue([3, null]);
+    mocks.set.mockResolvedValue('OK');
+
+    const { writeVerifiedSessionCacheForSubjects } = await import(
+      '../edge-trust.js'
+    );
+    await writeVerifiedSessionCacheForSubjects(
+      ['session:elevated', 'session:neutral'],
+      600
+    );
+
+    expect(mocks.set).toHaveBeenCalledTimes(1);
+    expect(mocks.set).toHaveBeenCalledWith(
+      'trust:mult:session:neutral',
+      { m: 1, verified: true },
+      { ex: 600 }
+    );
+    expect(mocks.set).not.toHaveBeenCalledWith(
+      'trust:mult:session:elevated',
+      expect.anything(),
+      expect.anything()
+    );
+  });
+
   it('parses legacy plain numbers and rich JSON entries together', async () => {
     mockRedisClient();
     mocks.mget.mockResolvedValue([
@@ -197,4 +258,42 @@ describe('edge-trust cache', () => {
       ex: 900,
     });
   });
+
+  it('writes and reads a session plus IP scoped appeal relief key', async () => {
+    mockRedisClient();
+    mocks.set.mockResolvedValue('OK');
+    mocks.get.mockResolvedValue('1');
+
+    const {
+      buildIpBlockAppealReliefKey,
+      hasCachedIpBlockAppealRelief,
+      setCachedIpBlockAppealRelief,
+    } = await import('../edge-trust.js');
+
+    expect(buildIpBlockAppealReliefKey('session:abc', 'ip:203.0.113.10')).toBe(
+      'trust:appeal-relief:session:abc:ip:203.0.113.10'
+    );
+
+    await setCachedIpBlockAppealRelief('session:abc', 'ip:203.0.113.10', 600);
+    expect(mocks.set).toHaveBeenCalledWith(
+      'trust:appeal-relief:session:abc:ip:203.0.113.10',
+      '1',
+      { ex: 600 }
+    );
+
+    await expect(
+      hasCachedIpBlockAppealRelief('session:abc', 'ip:203.0.113.10')
+    ).resolves.toBe(true);
+  });
+
+  it('fails closed for appeal relief when Redis is unavailable', async () => {
+    mockRedisClient();
+    mocks.get.mockRejectedValue(new Error('redis down'));
+
+    const { hasCachedIpBlockAppealRelief } = await import('../edge-trust.js');
+
+    await expect(
+      hasCachedIpBlockAppealRelief('session:abc', 'ip:203.0.113.10')
+    ).resolves.toBe(false);
+  });
 });

package/src/abuse-protection/__tests__/index.test.ts

@@ -3,19 +3,27 @@
  */
 
 import { afterEach, describe, expect, it, vi } from 'vitest';
+
 import {
   ABUSE_THRESHOLDS,
   BLOCK_DURATIONS,
+  checkMFAVerifyLimit,
   checkOTPSendAllowed,
+  checkOTPVerifyLimit,
   checkPasswordLoginLimit,
+  checkReauthVerifyLimit,
   classifyPotentialSpamUserAgent,
   clearPasswordLoginFailures,
   extractIPFromHeaders,
   hashEmail,
+  isSharedIpThrottleOnlyBlockReason,
   MAX_BLOCK_LEVEL,
   REDIS_KEYS,
+  recordMFAVerifyFailure,
   recordOTPSendSuccess,
+  recordOTPVerifyFailure,
   recordPasswordLoginFailure,
+  recordReauthVerifyFailure,
   resetOtpLimitsForEmail,
   WINDOW_MS,
 } from '../index';
@@ -251,6 +259,23 @@ describe('abuse-protection', () => {
     });
   });
 
+  describe('shared-IP hard block suppression', () => {
+    it('keeps human-auth failure reasons throttle-only', () => {
+      expect(isSharedIpThrottleOnlyBlockReason('otp_send')).toBe(true);
+      expect(isSharedIpThrottleOnlyBlockReason('otp_verify_failed')).toBe(true);
+      expect(isSharedIpThrottleOnlyBlockReason('mfa_verify_failed')).toBe(true);
+      expect(isSharedIpThrottleOnlyBlockReason('reauth_verify_failed')).toBe(
+        true
+      );
+      expect(isSharedIpThrottleOnlyBlockReason('password_login_failed')).toBe(
+        true
+      );
+      expect(isSharedIpThrottleOnlyBlockReason('api_auth_failed')).toBe(false);
+      expect(isSharedIpThrottleOnlyBlockReason('api_abuse')).toBe(false);
+      expect(isSharedIpThrottleOnlyBlockReason('manual')).toBe(false);
+    });
+  });
+
   describe('password login failure limits', () => {
     it('keeps the IP-wide failure counter after another account succeeds', async () => {
       const ipAddress = '203.0.113.41';
@@ -293,6 +318,33 @@ describe('abuse-protection', () => {
         remainingAttempts: 10,
       });
     });
+
+    it('throttles shared-IP password failures without writing a hard IP block', async () => {
+      const ipAddress = '203.0.113.42';
+
+      for (
+        let attempt = 0;
+        attempt < ABUSE_THRESHOLDS.PASSWORD_LOGIN_FAILED_MAX;
+        attempt += 1
+      ) {
+        await recordPasswordLoginFailure(
+          ipAddress,
+          `password-shared-ip-${attempt}@example.com`
+        );
+      }
+
+      const result = await checkPasswordLoginLimit(
+        ipAddress,
+        'another-user@example.com'
+      );
+
+      expect(result).toMatchObject({
+        allowed: false,
+        reason: 'Too many failed login attempts',
+        remainingAttempts: 0,
+      });
+      expect(result.blocked).not.toBe(true);
+    });
   });
 
   describe('BLOCK_DURATIONS constants', () => {
@@ -469,6 +521,90 @@ describe('abuse-protection', () => {
       expect(blockedAttempt.retryAfter).toBeGreaterThan(0);
     });
 
+    it('throttles aggressive shared-IP OTP sends without writing a hard IP block', async () => {
+      vi.stubEnv('ABUSE_OTP_SEND_IP_LIMIT_MINUTE', '1');
+      const ipAddress = '198.51.100.12';
+
+      await expect(
+        checkOTPSendAllowed(ipAddress, 'otp-shared-ip-1@example.com')
+      ).resolves.toMatchObject({ allowed: true });
+
+      const blockedAttempt = await checkOTPSendAllowed(
+        ipAddress,
+        'otp-shared-ip-2@example.com'
+      );
+
+      expect(blockedAttempt).toMatchObject({
+        allowed: false,
+        remainingAttempts: 0,
+      });
+      expect(blockedAttempt.blocked).not.toBe(true);
+    });
+
+    it('throttles shared-IP OTP verify failures without writing a hard IP block', async () => {
+      const ipAddress = '198.51.100.13';
+
+      for (
+        let attempt = 0;
+        attempt < ABUSE_THRESHOLDS.OTP_VERIFY_FAILED_MAX;
+        attempt += 1
+      ) {
+        await recordOTPVerifyFailure(
+          ipAddress,
+          `otp-verify-shared-ip-${attempt}@example.com`
+        );
+      }
+
+      const result = await checkOTPVerifyLimit(
+        ipAddress,
+        'legit-teacher@example.com'
+      );
+
+      expect(result).toMatchObject({
+        allowed: false,
+        reason: 'Too many failed verification attempts from this IP',
+        remainingAttempts: 0,
+      });
+      expect(result.blocked).not.toBe(true);
+    });
+
+    it('throttles shared-IP MFA and reauth failures without writing a hard IP block', async () => {
+      const mfaIpAddress = '198.51.100.14';
+      const reauthIpAddress = '198.51.100.15';
+
+      for (
+        let attempt = 0;
+        attempt < ABUSE_THRESHOLDS.MFA_VERIFY_FAILED_MAX;
+        attempt += 1
+      ) {
+        await recordMFAVerifyFailure(mfaIpAddress);
+      }
+
+      for (
+        let attempt = 0;
+        attempt < ABUSE_THRESHOLDS.REAUTH_VERIFY_FAILED_MAX;
+        attempt += 1
+      ) {
+        await recordReauthVerifyFailure(reauthIpAddress);
+      }
+
+      const mfaResult = await checkMFAVerifyLimit(mfaIpAddress);
+      const reauthResult = await checkReauthVerifyLimit(reauthIpAddress);
+
+      expect(mfaResult).toMatchObject({
+        allowed: false,
+        reason: 'Too many failed MFA verification attempts',
+        remainingAttempts: 0,
+      });
+      expect(reauthResult).toMatchObject({
+        allowed: false,
+        reason: 'Too many failed reauthentication attempts',
+        remainingAttempts: 0,
+      });
+      expect(mfaResult.blocked).not.toBe(true);
+      expect(reauthResult.blocked).not.toBe(true);
+    });
+
     it('caps successful sends for the same email across distributed IPs within an hour', async () => {
       vi.useFakeTimers();
       vi.setSystemTime(new Date('2026-03-12T00:00:00.000Z'));

package/src/abuse-protection/backend-rate-limit.ts

@@ -1,4 +1,3 @@
-import { blockIPEdge } from './edge';
 import type { BlockInfo } from './types';
 
 type BackendRateLimitSource = 'auth' | 'database';
@@ -37,8 +36,10 @@ export function isBackendRateLimitError(
 }
 
 export async function cascadeBackendRateLimitToProxyBan({
-  ipAddress,
+  ipAddress: _ipAddress,
 }: BackendRateLimitEscalationOptions): Promise<BlockInfo | null> {
-  const shouldBlockIp = ipAddress && ipAddress !== 'unknown';
-  return shouldBlockIp ? blockIPEdge(ipAddress, 'api_abuse') : null;
+  // A backend 429 is an availability/backpressure signal. It is not enough
+  // evidence to hard-ban a public NAT IP that may represent a classroom,
+  // university, or enterprise office.
+  return null;
 }