@tuturuuu/utils 0.29.0 → 0.30.0

package/src/__tests__/required-mfa-request.test.ts

@@ -0,0 +1,342 @@
+// @vitest-environment node
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createAppCoordinationToken } from '../app-coordination-token';
+import { checkRequiredAccountMfa } from '../required-mfa-request';
+
+const now = Math.floor(Date.now() / 1000);
+const policy = {
+  tuturuuu_required_mfa: { required: true, verifiedAfter: now - 30 },
+};
+const user = { id: 'actor', app_metadata: policy };
+function fixture() {
+  const query: Record<string, ReturnType<typeof vi.fn>> = {};
+  for (const method of ['select', 'eq', 'not', 'order', 'limit'])
+    query[method] = vi.fn(() => query);
+  query.maybeSingle = vi.fn().mockResolvedValue({ data: null, error: null });
+  const getUser = vi.fn().mockResolvedValue({ data: { user }, error: null });
+  const getClaims = vi.fn().mockResolvedValue({
+    data: {
+      claims: {
+        sub: 'actor',
+        aal: 'aal2',
+        session_id: 'session',
+        amr: [{ method: 'totp', timestamp: now - 10 }],
+      },
+    },
+    error: null,
+  });
+  const getUserById = vi
+    .fn()
+    .mockResolvedValue({ data: { user }, error: null });
+  const from = vi.fn(() => query);
+  const dependencies = {
+    createUserClient: vi.fn().mockResolvedValue({
+      auth: { getUser, getClaims },
+    } as unknown as TypedSupabaseClient),
+    createAdminClient: vi.fn().mockResolvedValue({
+      auth: { admin: { getUserById } },
+      from,
+      rpc: vi.fn().mockResolvedValue({ data: 'factor', error: null }),
+    } as unknown as TypedSupabaseClient),
+    nowSeconds: () => now,
+  };
+  const request = new Request('https://tuturuuu.com/api/v1/workspaces', {
+    headers: { authorization: 'Bearer supabase-session' },
+  });
+  return {
+    dependencies,
+    request,
+    getUser,
+    getClaims,
+    getUserById,
+    query,
+    from,
+  };
+}
+
+beforeEach(() =>
+  vi.stubEnv('TUTURUUU_APP_COORDINATION_SECRET', 'required-mfa-test-secret')
+);
+
+describe('fresh account assurance', () => {
+  it('allows current provider-verified MFA', async () => {
+    const f = fixture();
+    expect(
+      await checkRequiredAccountMfa(f.request, f.dependencies, {
+        userId: 'actor',
+      })
+    ).toEqual({
+      status: 'allowed',
+      userId: 'actor',
+      proof: { sessionId: 'session', verifiedAt: now - 10, factorId: 'factor' },
+    });
+    expect(f.dependencies.createAdminClient).toHaveBeenCalled();
+  });
+
+  it('rejects assurance for a different resolved route principal', async () => {
+    const f = fixture();
+    expect(
+      await checkRequiredAccountMfa(f.request, f.dependencies, {
+        userId: 'another-actor',
+      })
+    ).toEqual({ status: 'invalid' });
+  });
+
+  it('does not fetch claims for an account without the policy', async () => {
+    const f = fixture();
+    f.getUser.mockResolvedValue({
+      data: { user: { ...user, app_metadata: {} } },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('allowed');
+    expect(f.getClaims).not.toHaveBeenCalled();
+  });
+
+  it('ignores user-controlled metadata', async () => {
+    const f = fixture();
+    f.getUser.mockResolvedValue({
+      data: {
+        user: {
+          ...user,
+          user_metadata: { tuturuuu_required_mfa: { required: false } },
+        },
+      },
+      error: null,
+    });
+    f.getClaims.mockResolvedValue({
+      data: { claims: { sub: 'actor', aal: 'aal1', session_id: 'session' } },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('required');
+  });
+
+  it.each([
+    { aal: 'aal1', amr: [{ method: 'password', timestamp: now }] },
+    { aal: 'aal2', amr: [{ method: 'totp', timestamp: now - 30 }] },
+    { aal: 'aal2', amr: [{ method: 'totp', timestamp: now + 10 }] },
+    { aal: 'aal2', amr: [{ method: 'totp', timestamp: now - 100 }], iat: now },
+  ])('rejects stale, absent and future proof %j', async (claims) => {
+    const f = fixture();
+    f.getClaims.mockResolvedValue({
+      data: { claims: { sub: 'actor', session_id: 'session', ...claims } },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('required');
+  });
+
+  it('rejects claims for a different actor', async () => {
+    const f = fixture();
+    f.getClaims.mockResolvedValue({
+      data: { claims: { sub: 'another-user' } },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('invalid');
+  });
+
+  it('fails closed when fresh identity lookup throws', async () => {
+    const f = fixture();
+    f.getUser.mockRejectedValue(new Error('offline'));
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('unavailable');
+  });
+
+  it('rechecks changed policy for an already signed app token', async () => {
+    const f = fixture();
+    const { token } = createAppCoordinationToken({
+      userId: 'actor',
+      targetApp: 'mail',
+      mfa: { factorId: 'factor', sessionId: 'session', verifiedAt: now - 10 },
+    });
+    const request = new Request(f.request.url, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(request, f.dependencies, {
+          userId: 'actor',
+          appToken: token,
+        })
+      ).status
+    ).toBe('allowed');
+    f.getUserById.mockResolvedValue({
+      data: {
+        user: {
+          ...user,
+          app_metadata: {
+            tuturuuu_required_mfa: { required: true, verifiedAfter: now },
+          },
+        },
+      },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(request, f.dependencies, {
+          userId: 'actor',
+          appToken: token,
+        })
+      ).status
+    ).toBe('required');
+    expect(f.getUserById).toHaveBeenCalledTimes(2);
+    expect(f.from).not.toHaveBeenCalled();
+    expect(f.dependencies.createUserClient).not.toHaveBeenCalled();
+  });
+
+  it('does not accept an app token with no MFA evidence', async () => {
+    const f = fixture();
+    const { token } = createAppCoordinationToken({
+      userId: 'actor',
+      targetApp: 'mail',
+    });
+    const request = new Request(f.request.url, {
+      headers: { cookie: `tuturuuu_app_session=${token}` },
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(request, f.dependencies, {
+          userId: 'actor',
+          appToken: token,
+        })
+      ).status
+    ).toBe('required');
+  });
+
+  it('does not trust an invalid app token', async () => {
+    const f = fixture();
+    const token = 'ttr_app_invalid';
+    const request = new Request(f.request.url, {
+      headers: { authorization: `Bearer ${token}` },
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(request, f.dependencies, {
+          userId: 'actor',
+          appToken: token,
+        })
+      ).status
+    ).toBe('invalid');
+    expect(f.dependencies.createAdminClient).not.toHaveBeenCalled();
+  });
+
+  it('scopes mobile approval lookup to the exact actor and session', async () => {
+    const f = fixture();
+    f.getClaims.mockResolvedValue({
+      data: { claims: { sub: 'actor', aal: 'aal1', session_id: 'session' } },
+      error: null,
+    });
+    f.query.maybeSingle!.mockResolvedValue({
+      data: {
+        approved_at: new Date((now - 5) * 1000).toISOString(),
+        approval_metadata: {
+          requiredMfaProof: {
+            sessionId: 'source-session',
+            factorId: 'factor',
+            verifiedAt: now - 5,
+          },
+          mobileMfaValidUntil: new Date((now + 60) * 1000).toISOString(),
+        },
+      },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('allowed');
+    expect(f.query.eq).toHaveBeenCalledWith('approver_user_id', 'actor');
+    expect(f.query.eq).toHaveBeenCalledWith(
+      'request_metadata->>requesterSessionId',
+      'session'
+    );
+    expect(f.query.eq).toHaveBeenCalledWith(
+      'approval_metadata->>approverSessionId',
+      'session'
+    );
+    expect(f.query.not).toHaveBeenCalledWith('consumed_at', 'is', null);
+  });
+
+  it.each(['invalid', new Date((now - 1) * 1000).toISOString()])(
+    'rejects unusable mobile approval expiry %s',
+    async (expiry) => {
+      const f = fixture();
+      f.getClaims.mockResolvedValue({
+        data: { claims: { sub: 'actor', aal: 'aal1', session_id: 'session' } },
+        error: null,
+      });
+      f.query.maybeSingle!.mockResolvedValue({
+        data: {
+          approved_at: new Date((now - 5) * 1000).toISOString(),
+          approval_metadata: { mobileMfaValidUntil: expiry },
+        },
+        error: null,
+      });
+      expect(
+        (
+          await checkRequiredAccountMfa(f.request, f.dependencies, {
+            userId: 'actor',
+          })
+        ).status
+      ).toBe('required');
+    }
+  );
+  it('keeps mobile proof precision consistent with signed integer timestamps', async () => {
+    const f = fixture();
+    f.getClaims.mockResolvedValue({
+      data: { claims: { sub: 'actor', aal: 'aal1', session_id: 'session' } },
+      error: null,
+    });
+    f.query.maybeSingle!.mockResolvedValue({
+      data: {
+        approved_at: new Date((now - 30) * 1000 + 500).toISOString(),
+        approval_metadata: {
+          requiredMfaProof: {
+            sessionId: 'source-session',
+            factorId: 'factor',
+            verifiedAt: now - 5,
+          },
+          mobileMfaValidUntil: new Date((now + 60) * 1000).toISOString(),
+        },
+      },
+      error: null,
+    });
+    expect(
+      (
+        await checkRequiredAccountMfa(f.request, f.dependencies, {
+          userId: 'actor',
+        })
+      ).status
+    ).toBe('required');
+  });
+});

package/src/__tests__/required-mfa-runtime.test.ts

@@ -0,0 +1,109 @@
+// @vitest-environment node
+import { NextRequest } from 'next/server';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createAppCoordinationToken } from '../app-coordination-token';
+import { enforceRequiredMfaRequest } from '../required-mfa-runtime';
+
+const mocks = vi.hoisted(() => ({ admin: vi.fn() }));
+vi.mock('@tuturuuu/supabase/next/server', () => ({
+  createAdminClient: mocks.admin,
+}));
+const now = Math.floor(Date.now() / 1000);
+function setup() {
+  const user = {
+    id: 'actor',
+    app_metadata: {
+      tuturuuu_required_mfa: { required: true, verifiedAfter: now - 30 },
+    },
+  };
+  const getUserById = vi.fn(async (id: string) => ({
+    data: { user: id === 'actor' ? user : { id, app_metadata: {} } },
+    error: null,
+  }));
+  const getUser = vi.fn(async () => ({ data: { user }, error: null }));
+  const getClaims = vi.fn(async () => ({
+    data: { claims: { sub: 'actor', aal: 'aal1' } },
+    error: null,
+  }));
+  mocks.admin.mockResolvedValue({
+    rpc: async () => ({ data: 'factor', error: null }),
+    auth: { getUser, getClaims, admin: { getUserById } },
+  });
+  return { getUser, getClaims, getUserById };
+}
+function request(headers: HeadersInit, path = '/api/v1/workspaces') {
+  return new NextRequest(`https://tuturuuu.com${path}`, { headers });
+}
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.stubEnv('TUTURUUU_APP_COORDINATION_SECRET', 'test-required-mfa-secret');
+});
+describe('connected required MFA request enforcement', () => {
+  it('denies provider-authenticated AAL1 sessions with fresh required policy', async () => {
+    setup();
+    const response = await enforceRequiredMfaRequest(
+      request({ authorization: 'Bearer eyJprovider' })
+    );
+    expect(response?.status).toBe(403);
+    expect(await response?.json()).toMatchObject({ code: 'MFA_REQUIRED' });
+  });
+  it('does not borrow assurance from another cookie identity', async () => {
+    setup();
+    const optional = createAppCoordinationToken({
+      userId: 'optional',
+      targetApp: 'web',
+    }).token;
+    const required = createAppCoordinationToken({
+      userId: 'actor',
+      targetApp: 'infra',
+    }).token;
+    const response = await enforceRequiredMfaRequest(
+      request({
+        cookie: `tuturuuu_web_app_session=${optional}; tuturuuu_app_session=${required}`,
+      })
+    );
+    expect(response?.status).toBe(403);
+  });
+  it('accepts a signed proof after the recovery boundary', async () => {
+    setup();
+    const token = createAppCoordinationToken({
+      userId: 'actor',
+      targetApp: 'infra',
+      mfa: { factorId: 'factor', sessionId: 'session', verifiedAt: now - 5 },
+    }).token;
+    expect(
+      await enforceRequiredMfaRequest(
+        request({ authorization: `Bearer ${token}` })
+      )
+    ).toBeNull();
+  });
+  it('fails closed when current policy is unavailable', async () => {
+    mocks.admin.mockRejectedValue(new Error('offline'));
+    expect(
+      (
+        await enforceRequiredMfaRequest(
+          request({ authorization: 'Bearer eyJprovider' })
+        )
+      )?.status
+    ).toBe(503);
+  });
+  it('leaves independently authenticated machine requests to their own authentication', async () => {
+    expect(
+      await enforceRequiredMfaRequest(
+        request({ authorization: 'Bearer machine-key' })
+      )
+    ).toBeNull();
+    expect(mocks.admin).not.toHaveBeenCalled();
+  });
+  it('leaves recovery requests reachable for their own challenge validation', async () => {
+    expect(
+      await enforceRequiredMfaRequest(
+        request(
+          { authorization: 'Bearer eyJprovider' },
+          '/api/v1/auth/mfa/devices'
+        )
+      )
+    ).toBeNull();
+    expect(mocks.admin).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/required-mfa-transfer.test.ts

@@ -0,0 +1,29 @@
+// @vitest-environment node
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createAppCoordinationToken } from '../app-coordination-token';
+import { createMfaTransfer, readMfaTransfer } from '../required-mfa-transfer';
+
+const proof = {
+  sessionId: 'session',
+  verifiedAt: Math.floor(Date.now() / 1000) - 5,
+};
+beforeEach(() =>
+  vi.stubEnv('TUTURUUU_APP_COORDINATION_SECRET', 'test-transfer-secret')
+);
+describe('MFA proof transfer through caller-controlled metadata', () => {
+  it('accepts only a signed proof for the exact user and target', () => {
+    const token = createMfaTransfer('actor', 'mail', proof);
+    expect(readMfaTransfer(token, 'actor', 'mail')).toEqual(proof);
+    expect(readMfaTransfer(token, 'victim', 'mail')).toBeNull();
+    expect(readMfaTransfer(token, 'actor', 'infra')).toBeNull();
+  });
+  it('rejects raw metadata and tokens without the transfer scope', () => {
+    expect(readMfaTransfer(proof, 'actor', 'mail')).toBeNull();
+    const token = createAppCoordinationToken({
+      userId: 'actor',
+      targetApp: 'mail',
+      mfa: proof,
+    }).token;
+    expect(readMfaTransfer(token, 'actor', 'mail')).toBeNull();
+  });
+});

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

@@ -1,8 +1,10 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 const mockRpc = vi.fn();
+const mockFrom = vi.fn();
 const mockCreateAdminClient = vi.fn(() => ({
   rpc: mockRpc,
+  from: mockFrom,
 }));
 
 vi.mock('@tuturuuu/supabase/next/server', () => ({
@@ -28,6 +30,111 @@ describe('adaptive abuse reputation', () => {
     mockRpc.mockResolvedValue({ data: [], error: null });
   });
 
+  it('binds native subjects to authenticated bearer credentials, never a raw token or an anonymous caller', () => {
+    const subjects = (token: string, userId?: string) =>
+      buildAbuseRiskSubjects({
+        headers: { authorization: `Bearer ${token}` },
+        userId,
+      });
+    expect(subjects('secret', 'caller')).toContainEqual(
+      expect.objectContaining({ subject_type: 'session' })
+    );
+    expect(JSON.stringify(subjects('secret', 'caller'))).not.toContain(
+      'secret'
+    );
+    expect(subjects('secret', 'caller')).not.toEqual(
+      subjects('rotated', 'caller')
+    );
+    expect(subjects('secret')).toEqual([]);
+  });
+
+  it.each([true, false])(
+    'reuses only a recent passed challenge for this authenticated session: %s',
+    async (passed) => {
+      const lookup = {
+        select: vi.fn().mockReturnThis(),
+        eq: vi.fn().mockReturnThis(),
+        gt: vi.fn().mockReturnThis(),
+        gte: vi.fn().mockReturnThis(),
+        order: vi.fn().mockReturnThis(),
+        limit: vi.fn().mockResolvedValue({
+          data: passed ? [{ id: 'proof' }] : [],
+          error: null,
+        }),
+      };
+      mockFrom.mockReturnValue(lookup);
+      const decision = await resolveAbuseRiskDecision({
+        authKind: 'session',
+        headers: {
+          authorization: 'Bearer session-token',
+          'user-agent': 'Dart/3.9 (dart:io)',
+        },
+        isRead: false,
+        method: 'POST',
+        route: '/tasks',
+        userId: 'caller',
+      });
+      expect(decision.tier).toBe(passed ? 'standard' : 'challenge_required');
+      expect(decision.trustMultiplier).toBe(1);
+      expect(lookup.eq).toHaveBeenCalledWith('user_id', 'caller');
+      expect(lookup.eq).toHaveBeenCalledWith(
+        'subject_key',
+        decision.subjects.find((subject) => subject.subject_type === 'session')
+          ?.subject_key
+      );
+      expect(lookup.eq).toHaveBeenCalledWith('status', 'passed');
+      expect(lookup.gt).toHaveBeenCalledWith(
+        'expires_at',
+        '2026-05-17T00:00:00.000Z'
+      );
+      expect(lookup.gte).toHaveBeenCalledWith(
+        'completed_at',
+        '2026-05-16T23:45:00.000Z'
+      );
+    }
+  );
+
+  it.each(['restricted', 'challenge_required'])(
+    'never overrides explicit server policy: %s',
+    async (tier) => {
+      mockRpc.mockResolvedValue({
+        data: [{ tier, trust_multiplier: 1, decision_source: 'override' }],
+        error: null,
+      });
+      const decision = await resolveAbuseRiskDecision({
+        authKind: 'session',
+        headers: {
+          authorization: 'Bearer session-token',
+          'user-agent': 'Dart/3.9 (dart:io)',
+        },
+        isRead: false,
+        method: 'POST',
+        route: '/tasks',
+        userId: 'caller',
+      });
+      expect(decision.tier).toBe(tier);
+      expect(mockFrom).not.toHaveBeenCalled();
+    }
+  );
+
+  it('fails closed when challenge storage is unavailable', async () => {
+    mockFrom.mockImplementation(() => {
+      throw new Error('offline');
+    });
+    const decision = await resolveAbuseRiskDecision({
+      authKind: 'session',
+      headers: {
+        authorization: 'Bearer session-token',
+        'user-agent': 'Dart/3.9 (dart:io)',
+      },
+      isRead: false,
+      method: 'POST',
+      route: '/tasks',
+      userId: 'caller',
+    });
+    expect(decision.tier).toBe('challenge_required');
+  });
+
   it('does not earn trust from old account and browser shape alone', async () => {
     const decision = await resolveAbuseRiskDecision({
       authKind: 'session',

package/src/abuse-protection/reputation.ts

@@ -192,6 +192,9 @@ function readHeader(
 function getSessionSubjectKey(
   headers: Headers | Map<string, string> | Record<string, string | null>
 ) {
+  const authorization = readHeader(headers, 'authorization');
+  const bearer = authorization?.match(/^Bearer ([^\s]+)$/i)?.[1];
+  if (bearer) return `session:${hashStableSubject(`bearer:${bearer}`)}`;
   const cookies = parseCookieHeader(readHeader(headers, 'cookie'));
   const authCookie = cookies.find(
     (cookie) =>
@@ -304,7 +307,7 @@ export function buildAbuseRiskSubjects({
     subjects.push({ subject_type: 'user', subject_key: `user:${userId}` });
   }
 
-  if (sessionKey) {
+  if (sessionKey && userId && !apiKeyId) {
     subjects.push({ subject_type: 'session', subject_key: sessionKey });
   }
 
@@ -365,6 +368,34 @@ async function loadServerTrustDecision({
   }
 }
 
+async function hasRecentSessionChallenge(
+  userId: string | null | undefined,
+  subjects: AbuseRiskSubject[]
+) {
+  const session = subjects.find(
+    (subject) => subject.subject_type === 'session'
+  );
+  if (!userId || !session) return false;
+  const supabase = await getSupabaseAdmin();
+  if (!supabase) return false;
+  try {
+    const now = new Date();
+    const { data, error } = await supabase
+      .from('abuse_step_up_challenges')
+      .select('id')
+      .eq('user_id', userId)
+      .eq('subject_key', session.subject_key)
+      .eq('status', 'passed')
+      .gt('expires_at', now.toISOString())
+      .gte('completed_at', new Date(now.getTime() - 15 * 60_000).toISOString())
+      .order('completed_at', { ascending: false })
+      .limit(1);
+    return !error && Boolean(data?.length);
+  } catch {
+    return false;
+  }
+}
+
 export async function resolveAbuseRiskDecision(
   input: ResolveAbuseRiskDecisionInput
 ): Promise<AbuseRiskDecision> {
@@ -432,11 +463,19 @@ export async function resolveAbuseRiskDecision(
     (!likelyBrowser || userAgentClassification.riskLevel === 'block');
 
   if (suspiciousBrowserMutation && tier !== 'restricted') {
-    tier = 'challenge_required';
+    // A completed session-bound challenge satisfies the browser-shape
+    // heuristic only. Server restrictions and explicit challenges still win.
+    const cleared =
+      serverDecision?.tier !== 'challenge_required' &&
+      (input.authKind === 'session' || input.authKind === 'app-session') &&
+      (await hasRecentSessionChallenge(input.userId, subjects));
+    tier = cleared ? 'standard' : 'challenge_required';
     trustMultiplier = 1;
     decisionSource = 'heuristic';
     subjectKey ??= subjects[0]?.subject_key ?? null;
-    reasons.push('suspicious_browser_mutation');
+    reasons.push(
+      cleared ? 'session_challenge_passed' : 'suspicious_browser_mutation'
+    );
   } else if (
     tier === 'trusted' &&
     userAgentClassification.riskLevel === 'block'