@tuturuuu/utils 0.33.3 → 0.34.0

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/constants.ts

@@ -79,6 +79,9 @@ export const MAX_TASK_NAME_LENGTH = 1024;
 export const MAX_TASK_DESCRIPTION_LENGTH = 100000;
 export const MAX_CHAT_MESSAGE_LENGTH = 10000;
 export const MAX_SUPPORT_INQUIRY_LENGTH = 5000;
+export const MAX_SUPPORT_INQUIRY_MESSAGE_LENGTH = 512;
+export const MAX_SUPPORT_INQUIRY_NAME_LENGTH = 64;
+export const MAX_SUPPORT_INQUIRY_SUBJECT_LENGTH = 128;
 export const MAX_CALENDAR_EVENT_TITLE_LENGTH = 255;
 export const MAX_CALENDAR_EVENT_DESCRIPTION_LENGTH = 10000;
 export const MAX_NOTE_TITLE_LENGTH = 255;

package/src/google-calendar-import-fence.test.ts

@@ -0,0 +1,182 @@
+import type { calendar_v3 } from '@tuturuuu/google';
+import type { SupabaseClient } from '@tuturuuu/supabase';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  applyGoogleImport,
+  captureGoogleImport,
+  GoogleImportFenceError,
+  replayDeferredGoogleImports,
+} from './google-calendar-import-fence';
+
+const scope = {
+  wsId: 'aaaaaaaa-aaaa-4aaa-aaaa-aaaaaaaaaaaa',
+  calendarId: 'calendar',
+  authTokenId: 'bbbbbbbb-bbbb-4bbb-bbbb-bbbbbbbbbbbb',
+};
+const capture = { ...scope, id: 'cccccccc-cccc-4ccc-cccc-cccccccccccc' };
+const result = { inserted: 0, updated: 1, deleted: 0, deferred: 0 };
+
+function fixture(providerEvent: unknown = { id: 'event', summary: 'fresh' }) {
+  const order: string[] = [];
+  const rpc = vi.fn(
+    async (
+      name: string,
+      _args: Record<string, unknown>
+    ): Promise<{ data: unknown; error: null }> => {
+      order.push(name);
+      return {
+        data:
+          name === 'list_deferred_calendar_google_imports'
+            ? ['event']
+            : name === 'capture_calendar_google_import'
+              ? capture
+              : result,
+        error: null,
+      };
+    }
+  );
+  const get = vi.fn(async () => {
+    order.push('get');
+    return { data: providerEvent };
+  });
+  const format = vi.fn(async (events: unknown[]) => events as object[]);
+  const client = { rpc } as unknown as SupabaseClient;
+  const calendarGet = vi.fn(async () => {
+    order.push('calendar-get');
+    return { data: { id: scope.calendarId, accessRole: 'reader' } };
+  });
+  const calendar = {
+    events: { get },
+    calendarList: { get: calendarGet },
+  } as unknown as calendar_v3.Calendar;
+  return { client, calendar, scope, format, order, rpc, get, calendarGet };
+}
+
+describe('guarded Google import boundaries', () => {
+  it('captures before the fresh provider read and persists before returning', async () => {
+    const f = fixture();
+    await replayDeferredGoogleImports(f);
+    expect(f.order).toEqual([
+      'list_deferred_calendar_google_imports',
+      'capture_calendar_google_import',
+      'get',
+      'apply_calendar_google_import',
+    ]);
+    expect(f.rpc.mock.calls[2]?.[1]).toEqual({
+      p_capture_id: capture.id,
+      p_events: [{ id: 'event', summary: 'fresh' }],
+      p_tombstones: [],
+    });
+  });
+  it('rejects a capture scoped to another account before any provider read', async () => {
+    const f = fixture();
+    f.rpc.mockImplementation(async (name) => ({
+      data:
+        name === 'list_deferred_calendar_google_imports'
+          ? ['event']
+          : { ...capture, authTokenId: null },
+      error: null,
+    }));
+    await expect(replayDeferredGoogleImports(f)).rejects.toBeInstanceOf(
+      GoogleImportFenceError
+    );
+    expect(f.get).not.toHaveBeenCalled();
+  });
+  it('does not apply an unexpected provider event identity', async () => {
+    const f = fixture({ id: 'another-event' });
+    await expect(replayDeferredGoogleImports(f)).rejects.toBeInstanceOf(
+      GoogleImportFenceError
+    );
+    expect(f.format).not.toHaveBeenCalled();
+    expect(f.rpc).toHaveBeenCalledTimes(2);
+  });
+  it.each([404, 410])(
+    'confirms calendar access before treating %s as a tombstone',
+    async (status) => {
+      const f = fixture();
+      f.get.mockRejectedValue({ response: { status } });
+      await replayDeferredGoogleImports(f);
+      expect(f.rpc.mock.calls[2]?.[1]).toEqual({
+        p_capture_id: capture.id,
+        p_events: [],
+        p_tombstones: ['event'],
+      });
+      expect(f.format).not.toHaveBeenCalled();
+      expect(f.calendarGet).toHaveBeenCalledWith({
+        calendarId: scope.calendarId,
+      });
+      expect(f.order).toEqual([
+        'list_deferred_calendar_google_imports',
+        'capture_calendar_google_import',
+        'calendar-get',
+        'apply_calendar_google_import',
+      ]);
+    }
+  );
+  it.each([403, 404, 410, 503])(
+    'keeps a missing event deferred when calendar access fails with %s',
+    async (status) => {
+      const f = fixture();
+      f.get.mockRejectedValue({ response: { status: 404 } });
+      f.calendarGet.mockRejectedValue({ response: { status } });
+      await expect(replayDeferredGoogleImports(f)).resolves.toEqual({
+        deferred: 1,
+      });
+      expect(f.rpc).toHaveBeenCalledTimes(2);
+      expect(f.format).not.toHaveBeenCalled();
+    }
+  );
+  it.each(['freeBusyReader', 'none', ''])(
+    'does not mistake %s metadata access for event access',
+    async (accessRole) => {
+      const f = fixture();
+      f.get.mockRejectedValue({ response: { status: 404 } });
+      f.calendarGet.mockResolvedValue({
+        data: { id: scope.calendarId, accessRole },
+      });
+      await expect(replayDeferredGoogleImports(f)).resolves.toEqual({
+        deferred: 1,
+      });
+      expect(f.rpc).toHaveBeenCalledTimes(2);
+    }
+  );
+  it('keeps deferred entries when calendar metadata has a different identity', async () => {
+    const f = fixture();
+    f.get.mockRejectedValue({ response: { status: 404 } });
+    f.calendarGet.mockResolvedValue({
+      data: { id: 'another-calendar', accessRole: 'reader' },
+    });
+    await expect(replayDeferredGoogleImports(f)).resolves.toEqual({
+      deferred: 1,
+    });
+    expect(f.rpc).toHaveBeenCalledTimes(2);
+  });
+  it('leaves deletion-disabled entries queued without an apply', async () => {
+    const f = fixture({ id: 'event', status: 'cancelled' });
+    expect(
+      await replayDeferredGoogleImports({ ...f, syncDeletes: false })
+    ).toEqual({ deferred: 1 });
+    expect(f.rpc).toHaveBeenCalledTimes(2);
+  });
+  it('propagates provider failure without tombstones or persistence', async () => {
+    const f = fixture();
+    const failure = new Error('provider unavailable');
+    f.get.mockRejectedValue(failure);
+    await expect(replayDeferredGoogleImports(f)).rejects.toBe(failure);
+    expect(f.rpc).toHaveBeenCalledTimes(2);
+  });
+  it('fails on optional-looking malformed persistence rather than advancing sync', async () => {
+    const f = fixture();
+    f.rpc.mockResolvedValue({ data: { ...result, deferred: -1 }, error: null });
+    await expect(
+      applyGoogleImport(f.client, capture, [])
+    ).rejects.toBeInstanceOf(GoogleImportFenceError);
+  });
+  it('rejects malformed capture state', async () => {
+    const f = fixture();
+    f.rpc.mockResolvedValue({ data: {}, error: null });
+    await expect(captureGoogleImport(f.client, scope)).rejects.toBeInstanceOf(
+      GoogleImportFenceError
+    );
+  });
+});

package/src/google-calendar-import-fence.ts

@@ -0,0 +1,166 @@
+import type { calendar_v3 } from '@tuturuuu/google';
+import type { SupabaseClient } from '@tuturuuu/supabase';
+import type { Json } from '@tuturuuu/types/db';
+import { z } from 'zod';
+
+const CaptureSchema = z
+  .object({
+    id: z.guid(),
+    wsId: z.guid(),
+    calendarId: z.string().min(1),
+    authTokenId: z.guid().nullable(),
+  })
+  .strict();
+const ResultSchema = z
+  .object({
+    inserted: z.number().int().nonnegative(),
+    updated: z.number().int().nonnegative(),
+    deleted: z.number().int().nonnegative(),
+    deferred: z.number().int().nonnegative(),
+  })
+  .strict();
+export type GoogleImportCapture = z.infer<typeof CaptureSchema>;
+export type GoogleImportResult = z.infer<typeof ResultSchema>;
+export type GoogleImportScope = Omit<GoogleImportCapture, 'id'>;
+
+export class GoogleImportFenceError extends Error {
+  constructor() {
+    super('Google import guard is unavailable; retry sync');
+  }
+}
+
+/** Must run before any provider GET/list, including deferred replay reads. */
+export async function captureGoogleImport(
+  client: SupabaseClient,
+  scope: GoogleImportScope
+) {
+  const { data, error } = await client.rpc('capture_calendar_google_import', {
+    p_ws_id: scope.wsId,
+    p_calendar_id: scope.calendarId,
+    p_auth_token_id: scope.authTokenId,
+  });
+  const parsed = CaptureSchema.safeParse(data);
+  if (
+    error ||
+    !parsed.success ||
+    parsed.data.wsId !== scope.wsId ||
+    parsed.data.calendarId !== scope.calendarId ||
+    parsed.data.authTokenId !== scope.authTokenId
+  )
+    throw new GoogleImportFenceError();
+  return parsed.data;
+}
+
+/** RPC commits applied rows and deferred identities together before token advance. */
+export async function applyGoogleImport(
+  client: SupabaseClient,
+  capture: GoogleImportCapture,
+  events: object[],
+  tombstones: string[] = []
+) {
+  const { data, error } = await client.rpc('apply_calendar_google_import', {
+    p_capture_id: capture.id,
+    p_events: events as Json[],
+    p_tombstones: tombstones,
+  });
+  const parsed = ResultSchema.safeParse(data);
+  if (error || !parsed.success) throw new GoogleImportFenceError();
+  return parsed.data;
+}
+
+function missingProviderEvent(error: unknown) {
+  if (!error || typeof error !== 'object') return false;
+  const value = error as { code?: unknown; response?: { status?: unknown } };
+  return [404, 410].includes(Number(value.response?.status ?? value.code));
+}
+
+/** Only exact verified token-row scope may replay protected entries. Unknown
+ * legacy account scope remains deferred; it never borrows a guessed account. */
+export async function replayDeferredGoogleImports(args: {
+  client: SupabaseClient;
+  calendar: calendar_v3.Calendar;
+  scope: GoogleImportScope;
+  format: (events: calendar_v3.Schema$Event[]) => Promise<object[]>;
+  syncDeletes?: boolean;
+}) {
+  const { data, error } = await args.client.rpc(
+    'list_deferred_calendar_google_imports',
+    {
+      p_ws_id: args.scope.wsId,
+      p_calendar_id: args.scope.calendarId,
+      p_auth_token_id: args.scope.authTokenId,
+    }
+  );
+  const parsed = z.array(z.string().min(1)).max(100).safeParse(data);
+  if (error || !parsed.success) throw new GoogleImportFenceError();
+  let deferred = 0;
+  for (const id of parsed.data) {
+    // Never apply the stored old snapshot. The queue stores identity only.
+    const capture = await captureGoogleImport(args.client, args.scope);
+    let providerEvent: calendar_v3.Schema$Event | null;
+    try {
+      const result = await args.calendar.events.get({
+        calendarId: args.scope.calendarId,
+        eventId: id,
+      });
+      if (result.data.id !== id) throw new GoogleImportFenceError();
+      providerEvent = result.data.status === 'cancelled' ? null : result.data;
+    } catch (failure) {
+      if (!missingProviderEvent(failure)) throw failure;
+      // Missing events and inaccessible/deleted calendars share 404/410. Only
+      // confirmed access to this exact calendar can justify a local tombstone.
+      try {
+        const access = await args.calendar.calendarList.get({
+          calendarId: args.scope.calendarId,
+        });
+        if (
+          !['reader', 'writer', 'owner'].includes(
+            access.data.accessRole ?? ''
+          ) ||
+          !access.data.id ||
+          (args.scope.calendarId !== 'primary' &&
+            access.data.id !== args.scope.calendarId)
+        ) {
+          deferred++;
+          continue;
+        }
+      } catch {
+        deferred++;
+        continue;
+      }
+      providerEvent = null;
+    }
+    if (!providerEvent && args.syncDeletes === false) {
+      deferred++;
+      continue;
+    }
+    const result = await applyGoogleImport(
+      args.client,
+      capture,
+      providerEvent ? await args.format([providerEvent]) : [],
+      providerEvent ? [] : [id]
+    );
+    deferred += result.deferred;
+  }
+  return { deferred };
+}
+
+/** Resolve a background caller's exact stored token row from its supplied
+ * credential, without persisting or logging that credential. Ambiguity is null. */
+export async function verifiedGoogleImportToken(
+  client: SupabaseClient,
+  wsId: string,
+  accessToken: string
+) {
+  const { data, error } = await client
+    .from('calendar_auth_tokens')
+    .select('id')
+    .eq('ws_id', wsId)
+    .eq('provider', 'google')
+    .eq('is_active', true)
+    .eq('access_token', accessToken)
+    .limit(2);
+  if (error) throw new GoogleImportFenceError();
+  const token = data?.length === 1 ? data[0] : undefined;
+  return token ? z.guid().parse(token.id) : null;
+}