@tuturuuu/utils 0.33.2 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## [0.34.0](https://github.com/tutur3u/platform/compare/utils-v0.33.3...utils-v0.34.0) (2026-10-04)
+
+
+### Features
+
+* **calendar:** support full Google color choices and scoped edits ([#5661](https://github.com/tutur3u/platform/issues/5661)) ([8cafac5](https://github.com/tutur3u/platform/commit/8cafac53438b504eafa8bcc8213d18448e4a17bc))
+* **identity:** enforce creator identity and media policies ([1078119](https://github.com/tutur3u/platform/commit/1078119eb4871568f76e4bc31005ba9f1b1ddd76)) ([e71e94f](https://github.com/tutur3u/platform/commit/e71e94fd1a643c5ee76979ba9444976ad4798906))
+* **identity:** protect creator usernames and profile media ([#5740](https://github.com/tutur3u/platform/issues/5740)) ([f8e18a4](https://github.com/tutur3u/platform/commit/f8e18a4c39d5bb65acfc5a680ccb9b2557ae4bed))
+* **mobile:** support offline data, cached images, and safe inventory checkout ([a45d634](https://github.com/tutur3u/platform/commit/a45d63498cc1e686d1d070f5861cf938c4e9a9ef)) ([#5734](https://github.com/tutur3u/platform/issues/5734)) ([2f0f397](https://github.com/tutur3u/platform/commit/2f0f39763daea56f1029fcc3e99e0be53c60e106))
+
+
+### Bug Fixes
+
+* **calendar:** fence metadata reads and retain recurrence during imports ([3895d28](https://github.com/tutur3u/platform/commit/3895d28fb4acd0164f6f021ad15df4c39a83938e))
+* **identity:** align live support validation and profile parity ([7d5e1b0](https://github.com/tutur3u/platform/commit/7d5e1b056d34d316177c21b178f201edf7680651))
+* **identity:** close profile policy and upload bypasses ([6f5aae5](https://github.com/tutur3u/platform/commit/6f5aae52c2ba3e633b4f24dd3f683d4b564a952f))
+* **identity:** enforce verified upload budgets and canonical profile validation ([8138fb5](https://github.com/tutur3u/platform/commit/8138fb59276191508416031f69195de291b2b06a))
+* **identity:** integrate main and order unapplied creator migrations ([5512e24](https://github.com/tutur3u/platform/commit/5512e2414abaa0c78b68cbdd3186a1d4bab861e7))
+* **identity:** preserve budgeted avatar tickets and atomic handle claims ([b18092f](https://github.com/tutur3u/platform/commit/b18092fb7bf8632f6ba5f99ab8a61308d09544b9))
+* **mobile:** harden offline inventory and scoped cache replay ([d9c0b13](https://github.com/tutur3u/platform/commit/d9c0b13b386287fb874be62a8b8ec794deeb6407))
+* **release:** gate critical app promotion on staged API probes ([f39cea3](https://github.com/tutur3u/platform/commit/f39cea3621b504a9320b6d79675aa42b905b0476)) ([#5761](https://github.com/tutur3u/platform/issues/5761)) ([391397f](https://github.com/tutur3u/platform/commit/391397f90f651d041d8f0e9ae566f8c3eab60dd7))
+* **release:** preserve manual test notes and share filtering policy ([ff312ca](https://github.com/tutur3u/platform/commit/ff312ca8b16e36bdc7f65484cded768de3073c17))
+* **releases:** omit merge bookkeeping from release summaries ([c66e0b1](https://github.com/tutur3u/platform/commit/c66e0b139c89706db32ec70c3e87fcc9c4018b6c)) ([#5741](https://github.com/tutur3u/platform/issues/5741)) ([552cd5a](https://github.com/tutur3u/platform/commit/552cd5ae85d19d9147f1367475f5f6b3bf522a63))
+* **sdk:** bound mixed judge jobs and validate playground exports ([c5efff9](https://github.com/tutur3u/platform/commit/c5efff9427dc36cae6c4212871a335f9cd4bde03))
+* **security:** isolate bulk limits from ordinary web operations ([b3a9add](https://github.com/tutur3u/platform/commit/b3a9addf90271c7e28319a2138bbd52aaa294bc1))
+* **security:** isolate offline bulk protection from daily web operations ([#5752](https://github.com/tutur3u/platform/issues/5752)) ([fd32aca](https://github.com/tutur3u/platform/commit/fd32aca3319c67d82149975e8c3a7615dfbca275))
+* **security:** stage offline download protection activation ([018f6ab](https://github.com/tutur3u/platform/commit/018f6ab2ada3fef843d66789dee6ec45fba905d3))
+
+
+### Performance Improvements
+
+* **devboxes:** parallelize bounded execution and retain warm playgrounds ([#5746](https://github.com/tutur3u/platform/issues/5746)) ([efd8ac4](https://github.com/tutur3u/platform/commit/efd8ac44b5c9f8cbf2ab5d64fbe89e1f7afe4f96))
+* **devboxes:** parallelize bounded runner execution and retain warm playgrounds ([c31cbf3](https://github.com/tutur3u/platform/commit/c31cbf3a2a7cb5214d75183896791366affdc7e6))
+
+## [0.33.3](https://github.com/tutur3u/platform/compare/utils-v0.33.2...utils-v0.33.3) (2026-10-02)
+
+
+### Bug Fixes
+
+* **calendar:** preserve opaque rendering cues and hydrate source colors ([33847dd](https://github.com/tutur3u/platform/commit/33847ddcd8a3cf2b5cef8ebf50ca4c1700424a27))
+* **calendar:** render opaque readable event colors ([#5694](https://github.com/tutur3u/platform/issues/5694)) ([6e3d81d](https://github.com/tutur3u/platform/commit/6e3d81d6fdd6f8155f12e36ede58d31fde0ac362))
+* **mobile:** harden timezone retry recovery ([264b4b8](https://github.com/tutur3u/platform/commit/264b4b89ab9e1cb4194374a3714b46832c5e486a))
+* **mobile:** resolve timezone settings with verified native sessions ([#5720](https://github.com/tutur3u/platform/issues/5720)) ([5640ca2](https://github.com/tutur3u/platform/commit/5640ca22bcbfda6cd0470f39171ffa2366af779e))
+* **mobile:** restore verified timezone resolution ([462c68b](https://github.com/tutur3u/platform/commit/462c68bf22b2b412dd1825c12c3558b10b028a40))
+* **mobile:** retain timezone snapshots during overlapping loads ([eff42e2](https://github.com/tutur3u/platform/commit/eff42e2cf9d3159ee6fc68be1079df5f50fd92e2))
+
 ## [0.33.2](https://github.com/tutur3u/platform/compare/utils-v0.33.1...utils-v0.33.2) (2026-10-01)
 
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tuturuuu/utils",
   "license": "MIT",
-  "version": "0.33.2",
+  "version": "0.34.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/tutur3u/platform",
@@ -24,8 +24,9 @@
     "@tiptap/react": "3.31.3",
     "@tuturuuu/google": "0.1.1",
     "@tuturuuu/icons": "0.1.1",
-    "@tuturuuu/internal-api": "0.48.0",
+    "@tuturuuu/internal-api": "0.49.0",
     "@tuturuuu/supabase": "0.5.2",
+    "@tuturuuu/turnstile": "0.1.3",
     "@upstash/ratelimit": "^2.0.8",
     "@upstash/redis": "^1.38.4",
     "cn": "^0.3.0",
@@ -41,11 +42,11 @@
     "server-only": "^0.0.1",
     "uuid": "^14.0.2",
     "y-prosemirror": "^1.3.7",
-    "yjs": "^13.6.32",
+    "yjs": "^13.6.33",
     "zod": "^4.6.2"
   },
   "devDependencies": {
-    "@tuturuuu/types": "0.33.1",
+    "@tuturuuu/types": "0.34.0",
     "@tuturuuu/typescript-config": "0.1.2",
     "@types/diff": "^8.0.0",
     "@types/node": "^26.5.1",

package/src/__tests__/api-proxy-bearer-trust.test.ts

@@ -7,6 +7,9 @@ const mocks = vi.hoisted(() => ({
   blocked: vi.fn(),
   prefixes: [] as string[],
 }));
+vi.mock('../offline-download-guard', () => ({
+  guardOfflineDownloadRequest: async () => null,
+}));
 vi.mock('../required-mfa-runtime', () => ({
   enforceRequiredMfaRequest: async () => null,
 }));

package/src/__tests__/api-proxy-guard.test.ts

@@ -3,6 +3,12 @@ vi.mock('../required-mfa-runtime', () => ({
 }));
 
 import { NextRequest } from 'next/server';
+import { makeRequest } from './api-proxy-test-request';
+
+vi.mock('../offline-download-guard', () => ({
+  guardOfflineDownloadRequest: async () => null,
+}));
+
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mocks = vi.hoisted(() => ({
@@ -74,19 +80,6 @@ vi.mock('../request-emoji-limit', () => ({
   ) => mocks.validateEmoji(req, options),
 }));
 
-function makeRequest(
-  pathname = '/api/test',
-  method = 'POST',
-  headers?: Record<string, string>,
-  body = '{}'
-) {
-  return new NextRequest(`http://localhost${pathname}`, {
-    method,
-    headers,
-    body: method === 'GET' || method === 'HEAD' ? undefined : body,
-  });
-}
-
 function singleReadRoutePolicies() {
   return [
     {

package/src/__tests__/api-proxy-offline-response.test.ts

@@ -0,0 +1,48 @@
+import { NextRequest } from 'next/server';
+import { describe, expect, it, vi } from 'vitest';
+
+const guard = vi.hoisted(() => vi.fn());
+vi.mock('../required-mfa-runtime', () => ({
+  enforceRequiredMfaRequest: async () => null,
+}));
+vi.mock('../offline-download-guard', () => ({
+  guardOfflineDownloadRequest: guard,
+}));
+
+import { guardApiProxyRequest } from '../api-proxy-guard';
+import { isFinanceInvoiceCreateSupportRead } from '../api-proxy-read-policy';
+
+describe('offline guard proxy integration', () => {
+  it('propagates a download challenge without continuing the request', async () => {
+    const challenge = Response.json(
+      { message: 'Verify download' },
+      { status: 403 }
+    );
+    guard.mockResolvedValueOnce(challenge);
+    const request = new NextRequest(
+      'https://example.test/api/v1/workspaces/ws/tasks'
+    );
+    expect(
+      await guardApiProxyRequest(request, { prefixBase: 'test:offline' })
+    ).toBe(challenge);
+    expect(guard).toHaveBeenCalledWith(request);
+  });
+  it.each(['permissions', 'members'])(
+    'excludes static settings/%s from invoice reads',
+    (name) => {
+      const request = new NextRequest(
+        `https://example.test/api/v1/workspaces/ws/settings/${name}`
+      );
+      expect(isFinanceInvoiceCreateSupportRead(request)).toBe(false);
+    }
+  );
+  it.each(['configs', 'custom-config'])(
+    'retains supported settings/%s invoice reads',
+    (name) => {
+      const request = new NextRequest(
+        `https://example.test/api/v1/workspaces/ws/settings/${name}`
+      );
+      expect(isFinanceInvoiceCreateSupportRead(request)).toBe(true);
+    }
+  );
+});

package/src/__tests__/api-proxy-test-request.ts

@@ -0,0 +1,19 @@
+import { NextRequest } from 'next/server';
+
+export function makeRequest(
+  pathname = '/api/test',
+  method = 'POST',
+  headers?: Record<string, string>,
+  body = '{}'
+) {
+  return new NextRequest(`http://localhost${pathname}`, {
+    method,
+    headers: {
+      ...(method !== 'GET' && method !== 'HEAD'
+        ? { 'content-type': 'application/json' }
+        : {}),
+      ...headers,
+    },
+    body: method === 'GET' || method === 'HEAD' ? undefined : body,
+  });
+}

package/src/__tests__/daily-operation-download-isolation.test.ts

@@ -0,0 +1,137 @@
+import { NextRequest, NextResponse } from 'next/server';
+import { afterEach, beforeEach, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  rest: vi.fn(),
+  limiter: vi.fn(),
+  limit: vi.fn(),
+  verify: vi.fn(),
+  mfa: vi.fn(),
+  block: vi.fn(),
+}));
+vi.mock('../required-mfa-runtime', () => ({
+  enforceRequiredMfaRequest: mocks.mfa,
+}));
+vi.mock('../abuse-protection/edge', () => ({
+  extractIPFromRequest: () => '192.0.2.1',
+  isIPBlockedEdge: mocks.block,
+  readEdgeAbuseProtectionControls: async () => ({
+    ipBlockingEnabled: true,
+    rateLimitsEnabled: false,
+  }),
+}));
+vi.mock('../abuse-protection/edge-trust', () => ({
+  getCachedTrustEntries: async () => new Map(),
+  hasCachedIpBlockAppealRelief: async () => false,
+}));
+vi.mock('../upstash-rest', () => ({
+  getUpstashRestRedisClient: mocks.rest,
+  getUpstashRatelimitRedisClient: mocks.limiter,
+}));
+vi.mock('@tuturuuu/turnstile/server', () => ({
+  verifyTurnstileToken: mocks.verify,
+}));
+vi.mock('@upstash/ratelimit', () => ({
+  Ratelimit: class {
+    static slidingWindow() {
+      return {};
+    }
+    limit(key: string) {
+      return mocks.limit(key);
+    }
+  },
+}));
+vi.mock('../request-emoji-limit', () => ({
+  validateRequestEmojiLimit: async () => null,
+}));
+
+let guardApiProxyRequest: typeof import('../api-proxy-guard')['guardApiProxyRequest'];
+
+import { OFFLINE_DOWNLOAD_HEADER } from '../offline-download-guard';
+
+const paths = [
+  ['finance', '/api/workspaces/ws/wallets/infinite'],
+  ['inventory', '/api/v1/workspaces/ws/inventory/products'],
+  ['contacts', '/api/v1/workspaces/ws/users/database'],
+  ['cms', '/api/v1/workspaces/ws/external-projects'],
+  ['contacts', '/api/v1/workspaces/ws/members'],
+  ['cms', '/api/v1/workspaces/ws/members'],
+  ['tasks', '/api/v1/workspaces/ws/tasks'],
+] as const;
+beforeEach(async () => {
+  vi.clearAllMocks();
+  vi.resetModules();
+  vi.stubEnv('NODE_ENV', 'production');
+  ({ guardApiProxyRequest } = await import('../api-proxy-guard.js'));
+  mocks.mfa.mockResolvedValue(null);
+  mocks.block.mockResolvedValue(null);
+  mocks.rest.mockRejectedValue(new Error('offline Redis unavailable'));
+  mocks.limiter.mockResolvedValue(null);
+  mocks.limit.mockResolvedValue({ success: false, reset: Date.now() + 1000 });
+  mocks.verify.mockRejectedValue(new Error('Turnstile unavailable'));
+});
+afterEach(() => vi.unstubAllEnvs());
+it.each(paths)(
+  'keeps %s ordinary reads independent of optional providers through the real proxy',
+  async (app, path) => {
+    for (const enabled of ['', 'false', 'true']) {
+      vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', enabled);
+      for (const method of ['GET', 'HEAD']) {
+        for (const headers of [
+          new Headers(),
+          new Headers({ authorization: 'Bearer synthetic-session' }),
+          new Headers({ cookie: 'tuturuuu_app_session=ttr_app_synthetic' }),
+        ]) {
+          const request = new NextRequest(
+            `https://${app}.tuturuuu.com${path}`,
+            {
+              method,
+              headers,
+            }
+          );
+          expect(
+            await guardApiProxyRequest(request, {
+              prefixBase: `proxy:${app}:api`,
+            })
+          ).toBeNull();
+        }
+      }
+    }
+    expect(mocks.rest).not.toHaveBeenCalled();
+    expect(mocks.limiter).not.toHaveBeenCalled();
+    expect(mocks.limit).not.toHaveBeenCalled();
+    expect(mocks.verify).not.toHaveBeenCalled();
+  }
+);
+it('keeps explicit bulk downloads unavailable when the optional provider fails', async () => {
+  vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', 'true');
+  const request = new NextRequest(
+    'https://inventory.tuturuuu.com/api/v1/workspaces/ws/inventory/products',
+    { headers: { [OFFLINE_DOWNLOAD_HEADER]: '1' } }
+  );
+  const result = await guardApiProxyRequest(request, {
+    prefixBase: 'proxy:inventory:api',
+  });
+  expect(result?.status).toBe(503);
+  expect(result?.headers.get('Retry-After')).toBe('30');
+});
+it('keeps baseline required MFA and IP blocks effective during offline-provider outages', async () => {
+  vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', 'true');
+  const request = new NextRequest(
+    'https://finance.tuturuuu.com/api/workspaces/ws/wallets/infinite'
+  );
+  mocks.mfa.mockResolvedValue(
+    NextResponse.json({ error: 'Required MFA' }, { status: 403 })
+  );
+  expect(
+    (await guardApiProxyRequest(request, { prefixBase: 'proxy:finance:api' }))
+      ?.status
+  ).toBe(403);
+  mocks.mfa.mockResolvedValue(null);
+  mocks.block.mockResolvedValue({ expiresAt: new Date(Date.now() + 30000) });
+  expect(
+    (await guardApiProxyRequest(request, { prefixBase: 'proxy:finance:api' }))
+      ?.status
+  ).toBe(429);
+  expect(mocks.rest).not.toHaveBeenCalled();
+});

package/src/__tests__/offline-download-guard.test.ts

@@ -0,0 +1,340 @@
+import { createHash } from 'node:crypto';
+import { NextRequest } from 'next/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const mocks = vi.hoisted(() => ({
+  limit: vi.fn(),
+  verify: vi.fn(),
+  trust: vi.fn(),
+  get: vi.fn(),
+  set: vi.fn(),
+  redis: vi.fn(),
+  limiterRedis: vi.fn(),
+  ip: vi.fn(() => '192.0.2.1'),
+}));
+vi.mock('@upstash/ratelimit', () => ({
+  Ratelimit: class {
+    static slidingWindow() {
+      return {};
+    }
+    limit(key: string) {
+      return mocks.limit(key);
+    }
+  },
+}));
+vi.mock('@tuturuuu/turnstile/server', () => ({
+  verifyTurnstileToken: mocks.verify,
+}));
+vi.mock('../abuse-protection/edge', () => ({
+  extractIPFromRequest: mocks.ip,
+}));
+vi.mock('../abuse-protection/edge-trust', () => ({
+  getCachedTrustEntries: mocks.trust,
+}));
+vi.mock('../upstash-rest', () => ({
+  getUpstashRestRedisClient: mocks.redis,
+  getUpstashRatelimitRedisClient: mocks.limiterRedis,
+}));
+vi.mock('../api-proxy-guard', () => ({
+  buildProxySessionSubjectKey: (name: string, value: string) =>
+    `session:${createHash('sha256').update(`${name}:${value}`).digest('hex').slice(0, 24)}`,
+  getProxySessionSubjectKeyFromCookieHeader: async () => null,
+}));
+
+import {
+  guardOfflineDownloadRequest,
+  isOfflineCapableRead,
+  OFFLINE_DOWNLOAD_HEADER,
+} from '../offline-download-guard';
+
+const path = '/api/v1/workspaces/workspace/inventory/products';
+function request({
+  bulk = false,
+  token,
+  bearer = 'synthetic-session',
+  pathname = path,
+  method = 'GET',
+}: {
+  bulk?: boolean;
+  token?: string;
+  bearer?: string | null;
+  pathname?: string;
+  method?: string;
+} = {}) {
+  return new NextRequest(`https://example.test${pathname}`, {
+    method,
+    headers: {
+      ...(bearer ? { authorization: `Bearer ${bearer}` } : {}),
+      ...(bulk ? { [OFFLINE_DOWNLOAD_HEADER]: '1' } : {}),
+      ...(token ? { 'x-tuturuuu-turnstile-token': token } : {}),
+    },
+  });
+}
+
+describe('offline download guards', () => {
+  beforeEach(() => {
+    vi.stubEnv('NODE_ENV', 'production');
+    vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', 'true');
+    vi.clearAllMocks();
+    mocks.redis.mockResolvedValue({ get: mocks.get, set: mocks.set });
+    mocks.limiterRedis.mockResolvedValue({});
+    mocks.limit.mockResolvedValue({ success: true, reset: Date.now() + 1000 });
+    mocks.verify.mockResolvedValue(undefined);
+    mocks.trust.mockResolvedValue(new Map());
+    mocks.get.mockResolvedValue(null);
+    mocks.set.mockResolvedValue('OK');
+  });
+  afterEach(() => vi.unstubAllEnvs());
+
+  it.each([
+    '/api/v1/workspaces/ws/wallets',
+    '/api/v1/workspaces/ws/inventory/products',
+    '/api/v1/workspaces/ws/members',
+    '/api/v1/workspaces/ws/task-boards/board/lists',
+  ])(
+    'leaves daily operations outside activated offline protection: %s',
+    async (pathname) => {
+      mocks.limit.mockRejectedValue(new Error('quota service unavailable'));
+      for (const method of ['GET', 'HEAD']) {
+        const input = request({ pathname, method, token: 'captcha' });
+        expect(isOfflineCapableRead(input)).toBe(true);
+        expect(await guardOfflineDownloadRequest(input)).toBeNull();
+      }
+      expect(mocks.redis).not.toHaveBeenCalled();
+      expect(mocks.limiterRedis).not.toHaveBeenCalled();
+      expect(mocks.limit).not.toHaveBeenCalled();
+      expect(mocks.trust).not.toHaveBeenCalled();
+      expect(mocks.verify).not.toHaveBeenCalled();
+    }
+  );
+
+  it.each(['0', 'true', ''])(
+    'requires the explicit bulk marker value 1: %s',
+    async (marker) => {
+      const input = request();
+      input.headers.set(OFFLINE_DOWNLOAD_HEADER, marker);
+      expect(isOfflineCapableRead(input)).toBe(true);
+      expect(await guardOfflineDownloadRequest(input)).toBeNull();
+      expect(mocks.redis).not.toHaveBeenCalled();
+    }
+  );
+
+  it.each([
+    '/api/v1/workspaces/ws/wallets',
+    '/api/workspaces/ws/transactions/infinite',
+    '/api/v1/workspaces/ws/members',
+    '/api/v1/users/calendar-settings',
+  ])(
+    'preserves ordinary reads before protection activation: %s',
+    async (pathname) => {
+      vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', '');
+      mocks.redis.mockResolvedValue(null);
+      mocks.limiterRedis.mockResolvedValue(null);
+      for (const method of ['GET', 'HEAD']) {
+        const input = request({ pathname, method });
+        expect(isOfflineCapableRead(input)).toBe(true);
+        expect(await guardOfflineDownloadRequest(input)).toBeNull();
+      }
+      expect(mocks.redis).not.toHaveBeenCalled();
+      expect(mocks.limiterRedis).not.toHaveBeenCalled();
+      expect(mocks.limit).not.toHaveBeenCalled();
+    }
+  );
+  it.each(['', 'false', 'TRUE', '1'])(
+    'blocks marked bulk downloads until explicit activation: %s',
+    async (enabled) => {
+      vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', enabled);
+      const response = await guardOfflineDownloadRequest(
+        request({ bulk: true, token: 'captcha' })
+      );
+      expect(response?.status).toBe(503);
+      expect(response?.headers.get('Cache-Control')).toBe('no-store');
+      expect(response?.headers.get('Retry-After')).toBe('30');
+      expect(mocks.redis).not.toHaveBeenCalled();
+      expect(mocks.limit).not.toHaveBeenCalled();
+      expect(mocks.verify).not.toHaveBeenCalled();
+    }
+  );
+  it('does not infer activation from available Redis or account trust', async () => {
+    vi.stubEnv('OFFLINE_DOWNLOAD_PROTECTION_ENABLED', 'false');
+    mocks.trust.mockImplementation(
+      async ([key]) => new Map([[key, { m: 2, verified: true }]])
+    );
+    expect(
+      (await guardOfflineDownloadRequest(request({ bulk: true })))?.status
+    ).toBe(503);
+    expect(mocks.redis).not.toHaveBeenCalled();
+    expect(mocks.trust).not.toHaveBeenCalled();
+  });
+
+  for (const pathname of [
+    path,
+    '/api/workspaces/ws/transactions/infinite',
+    '/api/v1/workspaces/ws/task-boards/board/lists',
+    '/api/v1/users/me/tasks',
+    '/api/v1/workspaces/ws/calendar/events',
+    '/api/v1/mobile-calendar/api/v1/workspaces/ws/calendar/events',
+    '/api/v1/mobile-calendar/api/v1/users/calendar-settings',
+    '/api/v1/workspaces/ws/products',
+    '/api/v1/workspaces/ws/habits',
+  ]) {
+    it(`recognizes protected reads without requiring a client marker: ${pathname}`, () => {
+      expect(isOfflineCapableRead(request({ pathname }))).toBe(true);
+      expect(isOfflineCapableRead(request({ pathname, method: 'POST' }))).toBe(
+        false
+      );
+    });
+  }
+  it('leaves unrelated APIs outside the new guard', async () => {
+    expect(
+      await guardOfflineDownloadRequest(
+        request({ pathname: '/api/v1/auth/login', bulk: true })
+      )
+    ).toBeNull();
+    expect(mocks.limit).not.toHaveBeenCalled();
+  });
+  it('enforces IP and session budgets for explicitly marked bulk reads', async () => {
+    expect(
+      await guardOfflineDownloadRequest(
+        request({ bulk: true, token: 'captcha' })
+      )
+    ).toBeNull();
+    expect(mocks.limit.mock.calls.map(([key]) => key)).toEqual([
+      'ip:192.0.2.1',
+      'ip:192.0.2.1',
+      expect.stringMatching(/^session:/),
+      expect.stringMatching(/^session:/),
+    ]);
+    expect(JSON.stringify(mocks.limit.mock.calls)).not.toContain(
+      'synthetic-session'
+    );
+  });
+  it('rate limits marked bulk reads before attempting CAPTCHA', async () => {
+    mocks.limit.mockResolvedValue({
+      success: false,
+      reset: Date.now() + 2000,
+    });
+    const response = await guardOfflineDownloadRequest(
+      request({ bulk: true, token: 'captcha' })
+    );
+    expect(response?.status).toBe(429);
+    expect(Number(response?.headers.get('Retry-After'))).toBeGreaterThan(0);
+    expect(mocks.verify).not.toHaveBeenCalled();
+  });
+  it('issues an explicit challenge, not a permission denial', async () => {
+    const response = await guardOfflineDownloadRequest(request({ bulk: true }));
+    expect(response?.status).toBe(403);
+    expect(response?.headers.get('X-Abuse-Challenge')).toBe('turnstile');
+    expect(mocks.set).not.toHaveBeenCalled();
+  });
+  it('verifies once and shares session clearance across gateway and owner', async () => {
+    const storage = new Map<string, unknown>();
+    mocks.get.mockImplementation(async (key) => storage.get(key));
+    mocks.set.mockImplementation(async (key, value) => {
+      storage.set(key, value);
+      return 'OK';
+    });
+    expect(
+      await guardOfflineDownloadRequest(
+        request({
+          bulk: true,
+          token: 'one-use',
+          pathname: `/api/v1/mobile-calendar/api/v1/workspaces/ws/calendar/events`,
+        })
+      )
+    ).toBeNull();
+    expect(
+      await guardOfflineDownloadRequest(
+        request({
+          bulk: true,
+          token: 'one-use',
+          pathname: '/api/v1/workspaces/ws/calendar/events',
+        })
+      )
+    ).toBeNull();
+    expect(mocks.verify).toHaveBeenCalledTimes(1);
+    expect(mocks.set).toHaveBeenCalledWith(
+      expect.stringMatching(/^offline:clearance:session:/),
+      'passed',
+      { ex: 900 }
+    );
+    expect(
+      await guardOfflineDownloadRequest(
+        request({ bulk: true, bearer: 'another-session' })
+      )?.then((value) => value?.status)
+    ).toBe(403);
+  });
+  it('does not treat a presented header or neutral verified session as elevated trust', async () => {
+    mocks.trust.mockImplementation(
+      async ([key]) => new Map([[key, { m: 1, verified: true }]])
+    );
+    expect(
+      (await guardOfflineDownloadRequest(request({ bulk: true })))?.status
+    ).toBe(403);
+  });
+  it('uses existing verified elevated trust without changing quotas', async () => {
+    mocks.trust.mockImplementation(
+      async ([key]) => new Map([[key, { m: 2, verified: true }]])
+    );
+    expect(
+      await guardOfflineDownloadRequest(request({ bulk: true }))
+    ).toBeNull();
+    expect(mocks.limit).toHaveBeenCalledTimes(4);
+    expect(mocks.set).not.toHaveBeenCalled();
+    expect(mocks.verify).not.toHaveBeenCalled();
+  });
+  it('retains the challenge when Turnstile rejects the token', async () => {
+    mocks.verify.mockRejectedValue(new Error('invalid'));
+    expect(
+      (
+        await guardOfflineDownloadRequest(
+          request({ bulk: true, token: 'invalid' })
+        )
+      )?.status
+    ).toBe(403);
+    expect(mocks.set).not.toHaveBeenCalled();
+  });
+  it('fails closed for marked bulk when distributed storage is missing', async () => {
+    mocks.redis.mockResolvedValue(null);
+    expect(
+      (await guardOfflineDownloadRequest(request({ bulk: true })))?.status
+    ).toBe(503);
+  });
+  it('fails closed on limiter/store errors', async () => {
+    mocks.limit.mockRejectedValue(new Error('unavailable'));
+    expect(
+      (await guardOfflineDownloadRequest(request({ bulk: true })))?.status
+    ).toBe(503);
+  });
+  it('keeps authenticated gateway sessions separate when the client IP is absent', async () => {
+    mocks.ip.mockReturnValueOnce('unknown');
+    expect(
+      await guardOfflineDownloadRequest(
+        request({ bulk: true, token: 'captcha' })
+      )
+    ).toBeNull();
+    expect(mocks.limit).toHaveBeenCalledTimes(2);
+    expect(
+      mocks.limit.mock.calls.every(([key]) =>
+        String(key).startsWith('session:')
+      )
+    ).toBe(true);
+  });
+  it('fails closed for an unknown anonymous address', async () => {
+    mocks.ip.mockReturnValueOnce('unknown');
+    expect(
+      (await guardOfflineDownloadRequest(request({ bearer: null, bulk: true })))
+        ?.status
+    ).toBe(503);
+    expect(mocks.limit).not.toHaveBeenCalled();
+  });
+  it('guards global exchange rates and accepts Bearer separator whitespace', async () => {
+    expect(
+      isOfflineCapableRead(request({ pathname: '/api/v1/exchange-rates' }))
+    ).toBe(true);
+    const input = request({ bulk: true, token: 'captcha' });
+    input.headers.set('authorization', 'Bearer   synthetic-session');
+    expect(await guardOfflineDownloadRequest(input)).toBeNull();
+    expect(mocks.limit).toHaveBeenCalledTimes(4);
+  });
+});