@tuturuuu/utils 0.33.3 → 0.35.0

package/src/__tests__/tutoring-teacher-hours.test.ts

@@ -0,0 +1,274 @@
+import { Temporal } from '@js-temporal/polyfill';
+import { describe, expect, it } from 'vitest';
+import {
+  assessTeacherHoursSlot,
+  type HoursSlot,
+  resetTeacherHoursOverride,
+  resolveTeacherHours,
+  type StaffHours,
+  validateHoursFrame,
+  validateHoursWeek,
+  validateHoursWriteReceipt,
+} from '../tutoring-teacher-hours';
+
+const defaults: StaffHours = {
+  revision: '900719925474099312345',
+  frame: { timeZone: 'Asia/Ho_Chi_Minh', confirmed: true },
+  week: { 1: [{ start: '09:00', end: '17:00' }], 2: [] },
+};
+const monday: HoursSlot = {
+  date: '2026-10-05',
+  start: '09:00',
+  endDate: '2026-10-05',
+  end: '10:00',
+};
+const decide = (slot: HoursSlot, hours = defaults) =>
+  assessTeacherHoursSlot(hours, null, slot).state;
+
+describe('teacher-hours authority and per-day inheritance', () => {
+  it('keeps teacher availability unknown without confirmed staff hours', () => {
+    expect(
+      resolveTeacherHours(null, null).every((day) => day.state === 'unknown')
+    ).toBe(true);
+    expect(assessTeacherHoursSlot(null, null, monday)).toEqual({
+      state: 'unknown',
+    });
+  });
+
+  it('distinguishes missing staff day from explicitly closed day', () => {
+    const week = resolveTeacherHours(defaults, null);
+    expect(week[0]).toMatchObject({ state: 'hours', source: 'default' });
+    expect(week[1]).toMatchObject({ state: 'closed', source: 'default' });
+    expect(week[2]).toMatchObject({ state: 'unknown', source: 'unknown' });
+  });
+
+  it('replaces, never unions, one overridden day and inherits absent weekdays', () => {
+    const week = resolveTeacherHours(defaults, {
+      revision: 'override:1',
+      week: { 1: [{ start: '18:00', end: '20:00' }] },
+    });
+    expect(week[0]?.intervals).toEqual([{ start: '18:00', end: '20:00' }]);
+    expect(week[0]?.source).toBe('override');
+    expect(week[1]?.state).toBe('closed');
+  });
+
+  it('explicit empty override closes the day; removing it inherits latest default', () => {
+    expect(
+      resolveTeacherHours(defaults, { revision: 'a', week: { 1: [] } })[0]
+        ?.state
+    ).toBe('closed');
+    const reset = resetTeacherHoursOverride('a', 'b');
+    expect(reset).toEqual({ revision: 'b', week: {} });
+    expect(
+      resolveTeacherHours({ ...defaults, week: { 1: [] } }, reset)[0]?.state
+    ).toBe('closed');
+    expect(resolveTeacherHours(defaults, reset)[0]?.state).toBe('hours');
+  });
+
+  it('cannot use custom overrides without a confirmed staff timezone', () => {
+    expect(
+      resolveTeacherHours(null, {
+        revision: 'a',
+        week: { 1: [{ start: '09:00', end: '17:00' }] },
+      })[0]?.state
+    ).toBe('unknown');
+  });
+
+  it('returns defensive interval copies', () => {
+    const week = resolveTeacherHours(defaults, null);
+    expect(week[0]?.intervals[0]).not.toBe(defaults.week[1]?.[0]);
+  });
+});
+
+describe('lossless receipt and reset contract', () => {
+  it('retains opaque revisions above JS safe precision and tombstone after reset', () => {
+    const before = '900719925474099312345';
+    const after = '900719925474099312346';
+    expect(Number(before)).toBe(Number(after));
+    const reset = resetTeacherHoursOverride(before, after);
+    expect(reset.revision).toBe(after);
+    expect(reset.week).toEqual({});
+    expect(resetTeacherHoursOverride(null, before).revision).toBe(before);
+  });
+
+  it('rejects reused same-content receipt revisions and malformed revisions', () => {
+    expect(() => validateHoursWriteReceipt('a', 'a')).toThrow();
+    expect(() => validateHoursWriteReceipt('a', '')).toThrow();
+    expect(() => validateHoursWriteReceipt(' ', 'b')).toThrow();
+    expect(() => validateHoursWriteReceipt(null, 'b')).not.toThrow();
+    // No pure helper claims to enforce storage CAS: stale/reset ABA needs atomic DB proof.
+  });
+});
+
+describe('strict frame and weekly window validation', () => {
+  it.each(['auto', '', '+07:00', 'Not/AZone'])(
+    'rejects nonconfirmed IANA frame %s',
+    (timeZone) => {
+      expect(() => validateHoursFrame({ timeZone, confirmed: true })).toThrow();
+    }
+  );
+  it('rejects unconfirmed valid timezone', () => {
+    expect(() =>
+      validateHoursFrame({ timeZone: 'UTC', confirmed: false } as never)
+    ).toThrow();
+  });
+  it.each([
+    { 0: [] },
+    { 8: [] },
+    { 1: [{ start: '9:00', end: '10:00' }] },
+    { 1: [{ start: '24:00', end: '24:00' }] },
+    { 1: [{ start: '10:00', end: '09:00' }] },
+    {
+      1: [
+        { start: '09:00', end: '11:00' },
+        { start: '10:00', end: '12:00' },
+      ],
+    },
+    {
+      1: [
+        { start: '12:00', end: '13:00' },
+        { start: '09:00', end: '10:00' },
+      ],
+    },
+  ])('rejects malformed/overlapping/unsorted week %j', (week) => {
+    expect(() => validateHoursWeek(week)).toThrow();
+  });
+  it('allows half-open adjacency and explicit midnight end', () => {
+    expect(() =>
+      validateHoursWeek({
+        1: [
+          { start: '00:00', end: '12:00' },
+          { start: '12:00', end: '24:00' },
+        ],
+      })
+    ).not.toThrow();
+  });
+});
+
+describe('candidate coverage and actual Temporal boundary', () => {
+  it('allows exact boundaries and rejects outside hours', () => {
+    expect(decide({ ...monday, end: '17:00' })).toBe('allowed');
+    expect(decide({ ...monday, start: '08:59' })).toBe('closed');
+    expect(decide({ ...monday, end: '17:01' })).toBe('closed');
+    expect(
+      decide({ ...monday, date: '2026-10-07', endDate: '2026-10-07' })
+    ).toBe('unknown');
+  });
+  it('covers adjacent intervals continuously without bridging a gap', () => {
+    const week = {
+      1: [
+        { start: '09:00', end: '10:00' },
+        { start: '10:00', end: '11:00' },
+      ],
+    };
+    expect(decide({ ...monday, end: '11:00' }, { ...defaults, week })).toBe(
+      'allowed'
+    );
+    week[1][1] = { start: '10:01', end: '11:00' };
+    expect(decide({ ...monday, end: '11:00' }, { ...defaults, week })).toBe(
+      'closed'
+    );
+  });
+  it('requires explicit coverage on both days for overnight and Sunday wrap', () => {
+    const slot = {
+      date: '2026-10-11',
+      start: '23:00',
+      endDate: '2026-10-12',
+      end: '01:00',
+    };
+    const hours = {
+      ...defaults,
+      week: {
+        7: [{ start: '22:00', end: '24:00' }],
+        1: [{ start: '00:00', end: '02:00' }],
+      },
+    };
+    expect(decide(slot, hours)).toBe('allowed');
+    expect(decide(slot, { ...hours, week: { 7: hours.week[7] } })).toBe(
+      'unknown'
+    );
+    expect(decide(slot, { ...hours, week: { ...hours.week, 1: [] } })).toBe(
+      'closed'
+    );
+    expect(
+      decide(
+        { ...slot, end: '00:00' },
+        { ...hours, week: { 7: hours.week[7] } }
+      )
+    ).toBe('allowed');
+  });
+  it('rejects zero/negative/unbounded slots and invalid civil dates', () => {
+    for (const slot of [
+      { ...monday, end: '09:00' },
+      { ...monday, end: '08:00' },
+      { ...monday, endDate: '2026-10-13' },
+      { ...monday, date: '2026-02-30' },
+      { ...monday, start: '9:00' },
+    ])
+      expect(decide(slot)).toBe('invalid');
+  });
+  it('proves compatible Temporal conversion would move a nonexistent clock time', () => {
+    const local = Temporal.PlainDateTime.from('2026-03-08T02:30');
+    expect(local.toZonedDateTime('America/New_York').hour).toBe(3);
+    const hours = {
+      ...defaults,
+      frame: { timeZone: 'America/New_York', confirmed: true as const },
+      week: { 7: [{ start: '00:00', end: '24:00' }] },
+    };
+    expect(
+      decide(
+        {
+          date: '2026-03-08',
+          start: '02:30',
+          endDate: '2026-03-08',
+          end: '04:00',
+        },
+        hours
+      )
+    ).toBe('invalid');
+    expect(
+      decide(
+        {
+          date: '2026-11-01',
+          start: '01:30',
+          endDate: '2026-11-01',
+          end: '03:00',
+        },
+        hours
+      )
+    ).toBe('invalid');
+    expect(
+      decide(
+        {
+          date: '2026-03-08',
+          start: '01:00',
+          endDate: '2026-03-08',
+          end: '04:00',
+        },
+        hours
+      )
+    ).toBe('invalid');
+    expect(
+      decide(
+        {
+          date: '2026-11-01',
+          start: '00:30',
+          endDate: '2026-11-01',
+          end: '03:00',
+        },
+        hours
+      )
+    ).toBe('invalid');
+    expect(
+      decide(
+        {
+          date: '2026-03-09',
+          start: '09:00',
+          endDate: '2026-03-09',
+          end: '10:00',
+        },
+        { ...hours, week: defaults.week }
+      )
+    ).toBe('allowed');
+  });
+});

package/src/__tests__/username-policy.test.ts

@@ -0,0 +1,70 @@
+// @vitest-environment node
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+import { isReservedUsername, isValidNewUsername } from '../username-policy';
+import reserved from '../username-policy.json';
+
+describe('Canonical username policy', () => {
+  it.each([
+    'four',
+    'abc',
+    '_invalid',
+    'Uppercase',
+    'has-hyphen',
+    'a'.repeat(33),
+  ])('rejects invalid new usernames %s', (value) => {
+    expect(isValidNewUsername(value)).toBe(false);
+  });
+  it.each([
+    'apple',
+    'google',
+    'microsoft',
+    'support',
+    'admin',
+    'admin123',
+    'supportteam',
+    'official_admin',
+    's_u_p_p_o_r_t123',
+    'g_o_o_g_l_e',
+    'apple123',
+    'official_microsoft',
+    'google_support',
+  ])('reserves common and branded identities %s', (value) => {
+    expect(isReservedUsername(value)).toBe(true);
+    expect(isValidNewUsername(value)).toBe(false);
+  });
+  it.each([
+    'quiet_artist',
+    'my_world',
+    'pineapple',
+    'my_supportteam',
+    'river123',
+    'abcde',
+    'a'.repeat(32),
+  ])('accepts a distinct creative username %s', (value) => {
+    expect(isValidNewUsername(value)).toBe(true);
+  });
+  it('keeps every canonical reserved name enforced in the database migration', () => {
+    const sql = readFileSync(
+      resolve(
+        __dirname,
+        '../../../../apps/database/supabase/migrations/20261004004000_public_creator_identity.sql'
+      ),
+      'utf8'
+    );
+    const seeds = [
+      ...sql.matchAll(
+        /jsonb_array_elements_text\('([^']+)'::jsonb\),'(common|brand)'/g
+      ),
+    ];
+    expect(seeds).toHaveLength(2);
+    for (const [category, values] of [
+      ['common', reserved.common],
+      ['brand', reserved.brands],
+    ] as const) {
+      const seed = seeds.find((match) => match[2] === category);
+      expect(JSON.parse(seed![1]!)).toEqual(values);
+    }
+  });
+});

package/src/account-benefits-server.ts

@@ -0,0 +1,43 @@
+import 'server-only';
+import { createAdminClient } from '@tuturuuu/supabase/next/server';
+export class AccountServiceError extends Error {
+  constructor(
+    readonly status: number,
+    message = 'Account request failed'
+  ) {
+    super(message);
+  }
+}
+export interface AccountPrivateTransport {
+  rpc<T>(
+    name: string,
+    args: Record<string, unknown>
+  ): Promise<{ data: T | null; error: { code?: string } | null }>;
+}
+export async function accountPrivateRpc<T>(
+  name: string,
+  args: Record<string, unknown>
+): Promise<T> {
+  const admin = await createAdminClient({ noCookie: true });
+  const client = (
+    admin as unknown as { schema(name: string): AccountPrivateTransport }
+  ).schema('private');
+  const result = await client.rpc<T>(name, args);
+  if (result.error || result.data === null) {
+    const code = result.error?.code;
+    throw new AccountServiceError(
+      code === '42501'
+        ? 403
+        : (result.data === null && !result.error) || code === 'P0002'
+          ? 404
+          : code === '40001' || code === '23505'
+            ? 409
+            : code === '22023'
+              ? 400
+              : code === '53300'
+                ? 503
+                : 500
+    );
+  }
+  return result.data;
+}

package/src/account-benefits.ts

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export const AccountBenefitKey = z
+  .string()
+  .regex(/^(feature|early_access)\.[a-z][a-z0-9_.-]{0,79}$/)
+  .or(z.literal('ai_credits'));
+export const AccountBenefitGrant = z
+  .object({
+    userId: z.guid(),
+    key: AccountBenefitKey,
+    amount: z.number().int().min(1).max(1_000_000),
+    reason: z.string().trim().min(3).max(500),
+    expiresAt: z.iso.datetime({ offset: true }).nullable(),
+    requestId: z.guid(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.key !== 'ai_credits' && value.amount !== 1)
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Feature grants have amount one',
+      });
+    if (value.key === 'ai_credits' && value.expiresAt !== null)
+      ctx.addIssue({
+        code: 'custom',
+        message: 'Credits use the billing period expiry',
+      });
+  });
+export function hasAccountBenefit(
+  grants: {
+    benefit_key: string;
+    starts_at: string;
+    expires_at: string | null;
+    revoked_at: string | null;
+  }[],
+  key: string,
+  now = Date.now()
+) {
+  return grants.some(
+    (grant) =>
+      grant.benefit_key === key &&
+      !grant.revoked_at &&
+      Date.parse(grant.starts_at) <= now &&
+      (!grant.expires_at || Date.parse(grant.expires_at) > now)
+  );
+}

package/src/api-proxy-guard.ts

@@ -11,7 +11,12 @@ import {
   getCachedTrustEntries,
   hasCachedIpBlockAppealRelief,
 } from './abuse-protection/edge-trust';
+import {
+  isFinanceInvoiceCreateSupportRead,
+  isFinanceRead,
+} from './api-proxy-read-policy';
 import { DEV_MODE, MAX_PAYLOAD_SIZE } from './constants';
+import { guardOfflineDownloadRequest } from './offline-download-guard';
 import { validateRequestEmojiLimit } from './request-emoji-limit';
 import { enforceRequiredMfaRequest } from './required-mfa-runtime';
 import {
@@ -112,23 +117,6 @@ type RateLimiter = {
 const limiterCache = new Map<string, Limiters>();
 const GENERIC_SUPABASE_AUTH_COOKIE_NAME_PATTERN =
   /^sb-[a-z0-9-]+-auth-token(?:\.\d+)?$/i;
-const UUID_PATH_SEGMENT =
-  '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';
-const FINANCE_INVOICE_CREATE_SUPPORT_READ_PATH_PATTERN = new RegExp(
-  `^/api/v1/workspaces/[^/]+/(?:finance/invoices(?:/subscription/context)?|inventory/products|promotions|settings/(?:configs|[^/]+)|user-groups(?:/linked-products|/${UUID_PATH_SEGMENT}/linked-products)|users(?:/${UUID_PATH_SEGMENT}(?:/(?:linked-promotions|referral-discounts|user-groups))?)?|wallets)/?$`,
-  'u'
-);
-const FINANCE_INVOICE_TRANSACTION_CATEGORIES_PATH_PATTERN =
-  /^\/api\/workspaces\/[^/]+\/transactions\/categories\/?$/u;
-const FINANCE_READ_PATH_PATTERNS = [
-  /^\/api\/workspaces\/[^/]+\/finance(?:\/|$)/u,
-  /^\/api\/workspaces\/[^/]+\/transactions(?:\/|$)/u,
-  /^\/api\/workspaces\/[^/]+\/wallets(?:\/|$)/u,
-  /^\/api\/workspaces\/[^/]+\/tags(?:\/|$)/u,
-  /^\/api\/v1\/workspaces\/[^/]+\/finance(?:\/|$)/u,
-  /^\/api\/v1\/workspaces\/[^/]+\/wallets(?:\/|$)/u,
-] as const;
-
 const NO_READ_RATE_LIMITS: RateLimitConfig[] = [];
 
 function parsePositiveIntEnv(
@@ -391,31 +379,6 @@ const FINANCE_READ_RATE_LIMITS: RateLimitProfile = {
   mutate: DEFAULT_MUTATE_RATE_LIMITS,
 };
 
-function isFinanceInvoiceCreateSupportRead(req: NextRequest) {
-  if (req.method !== 'GET' && req.method !== 'HEAD') {
-    return false;
-  }
-
-  return (
-    FINANCE_INVOICE_CREATE_SUPPORT_READ_PATH_PATTERN.test(
-      req.nextUrl.pathname
-    ) ||
-    FINANCE_INVOICE_TRANSACTION_CATEGORIES_PATH_PATTERN.test(
-      req.nextUrl.pathname
-    )
-  );
-}
-
-function isFinanceRead(req: NextRequest) {
-  if (req.method !== 'GET' && req.method !== 'HEAD') {
-    return false;
-  }
-
-  return FINANCE_READ_PATH_PATTERNS.some((pattern) =>
-    pattern.test(req.nextUrl.pathname)
-  );
-}
-
 function isUsersDatabaseReadOverPost(req: NextRequest) {
   if (req.method !== 'POST') {
     return false;
@@ -1352,6 +1315,9 @@ export async function guardApiProxyRequest(
     }
   }
 
+  const offlineResponse = await guardOfflineDownloadRequest(req);
+  if (offlineResponse) return offlineResponse;
+
   const allowDescriptionYjsState =
     /\/api\/v1\/workspaces\/[^/]+\/tasks\/[^/]+\/description$/.test(
       req.nextUrl.pathname

package/src/api-proxy-read-policy.ts

@@ -0,0 +1,43 @@
+import type { NextRequest } from 'next/server';
+
+const UUID_PATH_SEGMENT =
+  '[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}';
+const FINANCE_INVOICE_CREATE_SUPPORT_READ_PATH_PATTERN = new RegExp(
+  `^/api/v1/workspaces/[^/]+/(?:finance/invoices(?:/subscription/context)?|inventory/products|promotions|settings/(?:configs|(?!permissions(?:/|$)|members(?:/|$))[^/]+)|user-groups(?:/linked-products|/${UUID_PATH_SEGMENT}/linked-products)|users(?:/${UUID_PATH_SEGMENT}(?:/(?:linked-promotions|referral-discounts|user-groups))?)?|wallets)/?$`,
+  'u'
+);
+const FINANCE_INVOICE_TRANSACTION_CATEGORIES_PATH_PATTERN =
+  /^\/api\/workspaces\/[^/]+\/transactions\/categories\/?$/u;
+const FINANCE_READ_PATH_PATTERNS = [
+  /^\/api\/workspaces\/[^/]+\/finance(?:\/|$)/u,
+  /^\/api\/workspaces\/[^/]+\/transactions(?:\/|$)/u,
+  /^\/api\/workspaces\/[^/]+\/wallets(?:\/|$)/u,
+  /^\/api\/workspaces\/[^/]+\/tags(?:\/|$)/u,
+  /^\/api\/v1\/workspaces\/[^/]+\/finance(?:\/|$)/u,
+  /^\/api\/v1\/workspaces\/[^/]+\/wallets(?:\/|$)/u,
+] as const;
+
+export function isFinanceInvoiceCreateSupportRead(req: NextRequest) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    return false;
+  }
+
+  return (
+    FINANCE_INVOICE_CREATE_SUPPORT_READ_PATH_PATTERN.test(
+      req.nextUrl.pathname
+    ) ||
+    FINANCE_INVOICE_TRANSACTION_CATEGORIES_PATH_PATTERN.test(
+      req.nextUrl.pathname
+    )
+  );
+}
+
+export function isFinanceRead(req: NextRequest) {
+  if (req.method !== 'GET' && req.method !== 'HEAD') {
+    return false;
+  }
+
+  return FINANCE_READ_PATH_PATTERNS.some((pattern) =>
+    pattern.test(req.nextUrl.pathname)
+  );
+}

package/src/calendar-provider-readonly.ts

@@ -0,0 +1,49 @@
+/** Internal-only transport marker; never written back to a provider. */
+const marker = '__tuturuuuProviderReadonlyRecurrence';
+export type ProviderReadonlyRecurrence = {
+  state: 'unsupported';
+  master_id: string;
+  provider: 'google' | 'microsoft';
+};
+export function markProviderRecurrenceReadonly<T extends object>(
+  event: T,
+  provider: ProviderReadonlyRecurrence['provider'],
+  masterId: string
+): T {
+  return {
+    ...event,
+    [marker]: { state: 'unsupported', master_id: masterId, provider },
+  };
+}
+export function providerReadonlyProjection(event: unknown): {
+  locked?: true;
+  scheduling_metadata?: { provider_recurrence: ProviderReadonlyRecurrence };
+} {
+  if (!event || typeof event !== 'object') return {};
+  const value = (event as Record<string, unknown>)[marker];
+  if (!value || typeof value !== 'object') return {};
+  const entry = value as Partial<ProviderReadonlyRecurrence>;
+  if (
+    entry.state !== 'unsupported' ||
+    typeof entry.master_id !== 'string' ||
+    !entry.master_id ||
+    !['google', 'microsoft'].includes(entry.provider ?? '')
+  )
+    return {};
+  return {
+    locked: true,
+    scheduling_metadata: {
+      provider_recurrence: entry as ProviderReadonlyRecurrence,
+    },
+  };
+}
+export function isProviderRecurrenceReadonly(event: unknown): boolean {
+  if (!event || typeof event !== 'object') return false;
+  const metadata = (event as { scheduling_metadata?: unknown })
+    .scheduling_metadata;
+  if (!metadata || typeof metadata !== 'object') return false;
+  return (
+    (metadata as { provider_recurrence?: { state?: unknown } })
+      .provider_recurrence?.state === 'unsupported'
+  );
+}