@tuturuuu/utils 0.33.3 → 0.35.0

package/src/seo.test.ts

@@ -0,0 +1,168 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { tryToParsePath } from 'next/dist/lib/try-to-parse-path';
+import { describe, expect, it } from 'vitest';
+import { createTuturuuuNextConfig } from './next-config';
+import { APP_SEO_POLICY, createSeoHeaders, type SeoApp } from './seo';
+
+function blocked(
+  app: SeoApp,
+  pathname: string,
+  patterns?: string[],
+  preview = false
+) {
+  return createSeoHeaders(app, patterns, {
+    VERCEL_ENV: preview ? 'preview' : 'production',
+  }).some((rule) => {
+    const parsed = tryToParsePath(rule.source);
+    expect(parsed.error, rule.source).toBeUndefined();
+    return new RegExp(parsed.regexStr ?? '').test(pathname);
+  });
+}
+
+describe('app indexing boundaries', () => {
+  it.each(Object.keys(APP_SEO_POLICY) as SeoApp[])(
+    'protects auth and API paths in %s',
+    (app) => {
+      for (const path of [
+        '/login',
+        '/vi/login',
+        '/en/verify-token',
+        '/api/v1/users',
+        '/dashboard',
+        '/invite/token',
+      ]) {
+        expect(blocked(app, path), `${app}: ${path}`).toBe(true);
+      }
+    }
+  );
+
+  it('keeps private apps, shared task links, meeting codes and embeds unindexed', () => {
+    for (const app of [
+      'tasks',
+      'meet',
+      'parley',
+      'chat',
+      'ai',
+      'infrastructure',
+    ] as const) {
+      for (const path of [
+        '/',
+        '/personal',
+        '/vi/workspace-id',
+        '/shared/task/secret',
+        '/r/secret',
+      ]) {
+        expect(blocked(app, path), `${app}: ${path}`).toBe(true);
+      }
+    }
+    expect(blocked('forms', '/embed/share-code')).toBe(true);
+    expect(blocked('forms', '/')).toBe(false);
+    expect(blocked('forms', '/f/share-code')).toBe(false);
+    expect(blocked('forms', '/f/share-code/responses')).toBe(true);
+  });
+
+  it('allows public shops and products but protects buyer transactions', () => {
+    for (const prefix of ['', '/vi', '/en']) {
+      expect(blocked('storefront', `${prefix}/my-store`)).toBe(false);
+      expect(blocked('storefront', `${prefix}/my-store/products/item`)).toBe(
+        false
+      );
+      for (const suffix of [
+        'cart',
+        'checkout',
+        'checkout/success',
+        'orders',
+        'orders/bearer-token',
+      ]) {
+        expect(blocked('storefront', `${prefix}/my-store/${suffix}`)).toBe(
+          true
+        );
+      }
+    }
+  });
+
+  it('limits public education and tool surfaces to their declared pages', () => {
+    expect(blocked('learn', '/')).toBe(false);
+    expect(blocked('learn', '/personal/reports')).toBe(true);
+    expect(blocked('teach', '/personal/attendance')).toBe(true);
+    expect(blocked('tools', '/qr')).toBe(false);
+    expect(blocked('tools', '/qr/unknown')).toBe(true);
+    expect(blocked('nova', '/vi/learn/basic-techniques')).toBe(false);
+    expect(blocked('nova', '/vi/challenges')).toBe(true);
+    expect(blocked('git', '/-/personal/repositories')).toBe(true);
+    expect(blocked('git', '/tutur3u/platform/issues')).toBe(false);
+    expect(blocked('lettin', '/worlds/published-world')).toBe(false);
+    expect(blocked('lettin', '/personal/wiki/world')).toBe(true);
+  });
+
+  it('uses the generated platform allowlist and matches exact route boundaries', () => {
+    const paths: string[] = JSON.parse(
+      readFileSync(
+        resolve(
+          __dirname,
+          '../../../apps/web/src/lib/seo/public-routes.generated.json'
+        ),
+        'utf8'
+      )
+    );
+    const patterns = [...paths.map((path) => path.slice(1)), 'changelog/[^/]+'];
+    for (const path of paths) {
+      expect(blocked('web', path, patterns), path).toBe(false);
+      expect(blocked('web', `/vi${path === '/' ? '' : path}`, patterns)).toBe(
+        false
+      );
+    }
+    for (const path of [
+      '/personal/tasks',
+      '/workspace-id',
+      '/documents/private-id',
+      '/share/document/secret',
+      '/ai/chats/private',
+      '/pricing/unknown',
+    ]) {
+      expect(blocked('web', path, patterns), path).toBe(true);
+    }
+    expect(blocked('web', '/changelog/released', patterns)).toBe(false);
+  });
+
+  it('noindexes all preview URLs and preserves the policy after app headers', async () => {
+    expect(blocked('tools', '/qr', undefined, true)).toBe(true);
+    const config = createTuturuuuNextConfig({
+      seoApp: 'learn',
+      headers: async () => [
+        {
+          source: '/login',
+          headers: [{ key: 'X-Robots-Tag', value: 'index' }],
+        },
+      ],
+    });
+    const rules = await config.headers?.();
+    expect(rules?.at(-1)?.headers[0]?.value).toBe(
+      'noindex, nofollow, nosnippet'
+    );
+    expect(config).not.toHaveProperty('seoApp');
+  });
+
+  it('registers every Next app and prevents static/metadata route conflicts', () => {
+    const root = resolve(__dirname, '../../..');
+    for (const app of Object.keys(APP_SEO_POLICY)) {
+      const config = readFileSync(
+        resolve(root, `apps/${app}/next.config.ts`),
+        'utf8'
+      );
+      expect(config).toContain(`seoApp: '${app}'`);
+      for (const file of ['robots', 'sitemap']) {
+        expect(
+          existsSync(resolve(root, `apps/${app}/src/app/${file}.ts`)) &&
+            existsSync(
+              resolve(
+                root,
+                `apps/${app}/public/${file === 'robots' ? 'robots.txt' : 'sitemap.xml'}`
+              )
+            )
+        ).toBe(false);
+      }
+    }
+  });
+});

package/src/seo.ts

@@ -0,0 +1,49 @@
+import policy from './seo-policy.json';
+
+export type SeoApp = keyof typeof policy;
+export const APP_SEO_POLICY = policy;
+export const PRIVATE_ROBOTS_HEADER = 'noindex, nofollow, nosnippet';
+
+// These remain private even where a public dynamic slug pattern could match.
+const PRIVATE_PATH_PATTERN =
+  '(?:api|auth|login|logout|signup|verify-token|auth-error|add-account|dashboard|onboarding|invite|shared|share|embed|orders|cart|checkout|account|no-access|access-denied|not-whitelisted|not-available|-)(?:/|$)';
+
+function escapeRegex(value: string) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Next path-to-regexp fragments; every public pattern must match a whole URL. */
+export function createSeoHeaders(
+  app: SeoApp,
+  publicPathPatterns?: readonly string[],
+  env: Record<string, string | undefined> = process.env
+) {
+  const appPolicy = policy[app];
+  const publicPatterns = publicPathPatterns ?? [
+    ...appPolicy.publicPaths.map(escapeRegex),
+    ...appPolicy.publicPatterns,
+  ];
+  const isPreview =
+    env.VERCEL_ENV === 'preview' ||
+    env.VERCEL_ENV === 'development' ||
+    env.NODE_ENV === 'development' ||
+    env.TUTURUUU_NOINDEX === '1';
+  const publicPattern = `(?:${publicPatterns.join('|')})/?$`;
+  const localePrefix = '(?:(?:en|vi)/)?';
+
+  return [
+    {
+      // A header reaches redirects, errors, API responses and non-HTML files.
+      // Preview builds and apps with no explicit public content fail closed.
+      source:
+        isPreview || publicPatterns.length === 0
+          ? '/:path*'
+          : `/:path((?!(?:(?:en|vi)(?:/|$))?${publicPattern}).*)`,
+      headers: [{ key: 'X-Robots-Tag', value: PRIVATE_ROBOTS_HEADER }],
+    },
+    {
+      source: `/:path(${localePrefix}${PRIVATE_PATH_PATTERN}.*)`,
+      headers: [{ key: 'X-Robots-Tag', value: PRIVATE_ROBOTS_HEADER }],
+    },
+  ];
+}

package/src/tutoring-teacher-hours.ts

@@ -0,0 +1,220 @@
+import { Temporal } from '@js-temporal/polyfill';
+
+export type Weekday = 1 | 2 | 3 | 4 | 5 | 6 | 7;
+export type HoursInterval = Readonly<{ start: string; end: string }>;
+/** Missing weekday means unknown for staff defaults and inheritance for overrides. */
+export type HoursWeek = Partial<Record<Weekday, readonly HoursInterval[]>>;
+/** Opaque storage receipt. Never parse through Number or Date. */
+export type HoursRevision = string;
+export type ConfirmedHoursFrame = Readonly<{
+  timeZone: string;
+  confirmed: true;
+}>;
+export type StaffHours = Readonly<{
+  revision: HoursRevision;
+  frame: ConfirmedHoursFrame;
+  week: HoursWeek;
+}>;
+export type TeacherHoursOverride = Readonly<{
+  revision: HoursRevision;
+  week: HoursWeek;
+}>;
+export type EffectiveHoursDay = Readonly<{
+  day: Weekday;
+  source: 'default' | 'override' | 'unknown';
+  state: 'hours' | 'closed' | 'unknown';
+  intervals: readonly HoursInterval[];
+}>;
+const weekdays: readonly Weekday[] = [1, 2, 3, 4, 5, 6, 7];
+
+function minute(value: string, end = false): number {
+  if (end && value === '24:00') return 1440;
+  if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(value)) {
+    throw new Error('Invalid teacher-hours clock');
+  }
+  const [hour, minutes] = value.split(':').map(Number);
+  return hour! * 60 + minutes!;
+}
+
+export function validateHoursRevision(revision: HoursRevision): void {
+  if (
+    typeof revision !== 'string' ||
+    !revision.trim() ||
+    revision.length > 512
+  ) {
+    throw new Error('Invalid teacher-hours revision');
+  }
+}
+
+export function validateHoursFrame(frame: ConfirmedHoursFrame): void {
+  if (
+    frame?.confirmed !== true ||
+    typeof frame.timeZone !== 'string' ||
+    frame.timeZone === 'auto' ||
+    /^[+-]/.test(frame.timeZone)
+  ) {
+    throw new Error('Teacher-hours timezone must be explicitly confirmed');
+  }
+  // Intl rejects non-IANA identifiers; UTC and recognized IANA aliases are valid.
+  new Intl.DateTimeFormat('en', { timeZone: frame.timeZone }).format(0);
+}
+
+export function validateHoursWeek(week: HoursWeek): void {
+  if (!week || typeof week !== 'object' || Array.isArray(week)) {
+    throw new Error('Invalid teacher-hours week');
+  }
+  for (const [key, intervals] of Object.entries(week)) {
+    if (
+      !/^[1-7]$/.test(key) ||
+      !Array.isArray(intervals) ||
+      intervals.length > 24
+    ) {
+      throw new Error('Invalid teacher-hours weekday');
+    }
+    let previousEnd = -1;
+    for (const interval of intervals) {
+      const start = minute(interval.start);
+      const end = minute(interval.end, true);
+      if (end <= start || start < previousEnd) {
+        throw new Error('Teacher-hours intervals must be sorted and disjoint');
+      }
+      previousEnd = end;
+    }
+  }
+}
+
+export function resolveTeacherHours(
+  defaults: StaffHours | null,
+  override: TeacherHoursOverride | null
+): readonly EffectiveHoursDay[] {
+  if (defaults) {
+    validateHoursRevision(defaults.revision);
+    validateHoursFrame(defaults.frame);
+    validateHoursWeek(defaults.week);
+  }
+  if (override) {
+    validateHoursRevision(override.revision);
+    validateHoursWeek(override.week);
+  }
+  return weekdays.map((day) => {
+    const own = override?.week[day];
+    const inherited = defaults?.week[day];
+    // An override cannot establish an unconfirmed/missing staff timezone frame.
+    const intervals = defaults ? (own ?? inherited) : undefined;
+    return {
+      day,
+      source:
+        intervals === undefined ? 'unknown' : own ? 'override' : 'default',
+      state:
+        intervals === undefined
+          ? 'unknown'
+          : intervals.length
+            ? 'hours'
+            : 'closed',
+      intervals: intervals?.map((interval) => ({ ...interval })) ?? [],
+    };
+  });
+}
+
+/** Pure receipt validation, not a database CAS or authorization implementation. */
+export function validateHoursWriteReceipt(
+  expectedRevision: HoursRevision | null,
+  returnedRevision: HoursRevision
+): void {
+  if (expectedRevision !== null) validateHoursRevision(expectedRevision);
+  validateHoursRevision(returnedRevision);
+  if (expectedRevision === returnedRevision) {
+    throw new Error('Teacher-hours write did not advance its revision');
+  }
+}
+
+/** Reset is a revisioned empty override, never deletion back to an absent row. */
+export function resetTeacherHoursOverride(
+  expectedRevision: HoursRevision | null,
+  returnedRevision: HoursRevision
+): TeacherHoursOverride {
+  validateHoursWriteReceipt(expectedRevision, returnedRevision);
+  return { revision: returnedRevision, week: {} };
+}
+
+export type HoursSlot = Readonly<{
+  date: string;
+  start: string;
+  endDate: string;
+  end: string;
+}>;
+export type HoursSlotDecision =
+  | Readonly<{ state: 'allowed'; startInstant: string; endInstant: string }>
+  | Readonly<{ state: 'closed' | 'unknown' | 'invalid' }>;
+
+/**
+ * Staff-clock slot only: callers must convert other source frames explicitly.
+ * Reject DST gaps/folds and transition-crossing slots rather than choosing offsets.
+ * Overnight hours are represented explicitly on both weekdays; no inferred widening.
+ */
+export function assessTeacherHoursSlot(
+  defaults: StaffHours | null,
+  override: TeacherHoursOverride | null,
+  slot: HoursSlot
+): HoursSlotDecision {
+  if (!defaults) return { state: 'unknown' };
+  try {
+    const week = resolveTeacherHours(defaults, override);
+    if (
+      !/^\d{4}-\d{2}-\d{2}$/.test(slot.date) ||
+      !/^\d{4}-\d{2}-\d{2}$/.test(slot.endDate)
+    ) {
+      return { state: 'invalid' };
+    }
+    minute(slot.start);
+    minute(slot.end);
+    const start = Temporal.PlainDateTime.from(`${slot.date}T${slot.start}`);
+    const end = Temporal.PlainDateTime.from(`${slot.endDate}T${slot.end}`);
+    const civilMinutes = start.until(end, { largestUnit: 'minutes' }).minutes;
+    if (civilMinutes <= 0 || civilMinutes > 7 * 1440)
+      return { state: 'invalid' };
+    const zone = defaults.frame.timeZone;
+    const startZoned = start.toZonedDateTime(zone, {
+      disambiguation: 'reject',
+    });
+    const endZoned = end.toZonedDateTime(zone, { disambiguation: 'reject' });
+    if (
+      endZoned.epochMilliseconds - startZoned.epochMilliseconds !==
+      civilMinutes * 60_000
+    ) {
+      return { state: 'invalid' };
+    }
+    let date = start.toPlainDate();
+    let unknown = false;
+    let closed = false;
+    while (Temporal.PlainDate.compare(date, end.toPlainDate()) <= 0) {
+      const sameStart =
+        Temporal.PlainDate.compare(date, start.toPlainDate()) === 0;
+      const sameEnd = Temporal.PlainDate.compare(date, end.toPlainDate()) === 0;
+      const from = sameStart ? minute(slot.start) : 0;
+      const to = sameEnd ? minute(slot.end) : 1440;
+      if (from < to) {
+        const day = week[date.dayOfWeek - 1]!;
+        if (day.state === 'unknown') unknown = true;
+        else {
+          let covered = from;
+          for (const interval of day.intervals) {
+            if (minute(interval.start) > covered) break;
+            covered = Math.max(covered, minute(interval.end, true));
+          }
+          if (covered < to) closed = true;
+        }
+      }
+      date = date.add({ days: 1 });
+    }
+    if (closed) return { state: 'closed' };
+    if (unknown) return { state: 'unknown' };
+    return {
+      state: 'allowed',
+      startInstant: startZoned.toInstant().toString(),
+      endInstant: endZoned.toInstant().toString(),
+    };
+  } catch {
+    return { state: 'invalid' };
+  }
+}

package/src/username-policy.json

@@ -0,0 +1,87 @@
+{
+  "common": [
+    "admin",
+    "administrator",
+    "anonymous",
+    "account",
+    "accounts",
+    "artist",
+    "artists",
+    "creator",
+    "creators",
+    "dashboard",
+    "default",
+    "everyone",
+    "example",
+    "guest",
+    "help",
+    "home",
+    "login",
+    "logout",
+    "moderator",
+    "moderation",
+    "official",
+    "owner",
+    "personal",
+    "privacy",
+    "profile",
+    "public",
+    "root",
+    "security",
+    "settings",
+    "staff",
+    "support",
+    "system",
+    "terms",
+    "test",
+    "testing",
+    "unknown",
+    "user",
+    "username",
+    "users",
+    "website",
+    "webmaster"
+  ],
+  "brands": [
+    "adobe",
+    "amazon",
+    "android",
+    "apple",
+    "chatgpt",
+    "claude",
+    "cloudflare",
+    "discord",
+    "exocorpse",
+    "facebook",
+    "github",
+    "gmail",
+    "google",
+    "instagram",
+    "linkedin",
+    "meta",
+    "microsoft",
+    "netflix",
+    "nintendo",
+    "nvidia",
+    "openai",
+    "paypal",
+    "samsung",
+    "slack",
+    "snapchat",
+    "sony",
+    "spotify",
+    "stripe",
+    "telegram",
+    "tesla",
+    "tiktok",
+    "tulletin",
+    "tulettin",
+    "tuturuuu",
+    "twitch",
+    "twitter",
+    "vercel",
+    "whatsapp",
+    "windows",
+    "youtube"
+  ]
+}

package/src/username-policy.ts

@@ -0,0 +1,18 @@
+import reserved from './username-policy.json';
+
+export const USERNAME_MIN_LENGTH = 5;
+export const USERNAME_MAX_LENGTH = 32;
+export const USERNAME_CHANGE_INTERVAL_DAYS = 14;
+export const DISPLAY_NAME_CHANGE_LIMIT = 2;
+export const DISPLAY_NAME_CHANGE_WINDOW_DAYS = 7;
+const reservedPatterns = [...reserved.common, ...reserved.brands].map(
+  (brand) =>
+    new RegExp(`^(official)?${brand}(official|support|admin|team|[0-9]+)?$`)
+);
+export function isReservedUsername(value: string) {
+  const normalized = value.toLowerCase().replaceAll('_', '');
+  return reservedPatterns.some((pattern) => pattern.test(normalized));
+}
+export function isValidNewUsername(value: string) {
+  return /^[a-z0-9][a-z0-9_]{4,31}$/.test(value) && !isReservedUsername(value);
+}

package/vitest.config.ts

@@ -16,6 +16,13 @@ export default defineConfig({
   resolve: {
     alias: [
       { find: '@', replacement: resolve(__dirname, './src') },
+      {
+        find: '@tuturuuu/types/primitives/playgrounds',
+        replacement: resolve(
+          __dirname,
+          '../types/src/primitives/playgrounds.ts'
+        ),
+      },
       {
         find: '@tuturuuu/internal-api/tasks',
         replacement: resolve(__dirname, '../internal-api/src/tasks.ts'),