@tuturuuu/utils 0.29.1 → 0.31.0

package/src/required-mfa-policy.ts

@@ -0,0 +1,188 @@
+/** Server-owned app metadata; never read this policy from user_metadata. */
+export const REQUIRED_MFA_POLICY_KEY = 'tuturuuu_required_mfa';
+
+export type RequiredMfaPolicy = {
+  required: boolean;
+  /** A new policy or recovery reset invalidates earlier MFA proofs. */
+  verifiedAfter: number;
+  primaryVerifiedAfter?: number;
+};
+
+export type MfaSessionProof = {
+  sessionId: string;
+  verifiedAt: number;
+  factorId?: string;
+  verificationSessionId?: string;
+  primaryVerifiedAt?: number;
+  /** Mobile approval remains time-bounded across access/refresh tokens. */
+  expiresAt?: number;
+};
+
+/** Validate proof carried by a verified, server-signed app session. */
+export function isMfaSessionProof(value: unknown): value is MfaSessionProof {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proof = value as Record<string, unknown>;
+  return (
+    typeof proof.sessionId === 'string' &&
+    proof.sessionId.length > 0 &&
+    typeof proof.verifiedAt === 'number' &&
+    Number.isSafeInteger(proof.verifiedAt) &&
+    proof.verifiedAt >= 0 &&
+    (proof.factorId === undefined || typeof proof.factorId === 'string') &&
+    (proof.verificationSessionId === undefined ||
+      typeof proof.verificationSessionId === 'string') &&
+    (proof.primaryVerifiedAt === undefined ||
+      (typeof proof.primaryVerifiedAt === 'number' &&
+        Number.isSafeInteger(proof.primaryVerifiedAt) &&
+        proof.primaryVerifiedAt >= 0)) &&
+    (proof.expiresAt === undefined ||
+      (typeof proof.expiresAt === 'number' &&
+        Number.isSafeInteger(proof.expiresAt) &&
+        proof.expiresAt > proof.verifiedAt))
+  );
+}
+
+/** Missing policy preserves existing accounts; malformed policy fails closed. */
+export function readRequiredMfaPolicy(
+  appMetadata: Record<string, unknown> | null | undefined
+): RequiredMfaPolicy {
+  if (!appMetadata || !Object.hasOwn(appMetadata, REQUIRED_MFA_POLICY_KEY)) {
+    return { required: false, verifiedAfter: 0 };
+  }
+  const raw = appMetadata[REQUIRED_MFA_POLICY_KEY];
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    return { required: true, verifiedAfter: Number.POSITIVE_INFINITY };
+  }
+  const policy = raw as Record<string, unknown>;
+  if (policy.required === false) return { required: false, verifiedAfter: 0 };
+  const verifiedAfter =
+    Object.hasOwn(policy, 'recoveryInProgress') &&
+    policy.recoveryInProgress !== false
+      ? null
+      : policy.verifiedAfter;
+  const primary = policy.primaryVerifiedAfter;
+  return {
+    required: true,
+    ...(primary === undefined
+      ? {}
+      : {
+          primaryVerifiedAfter:
+            typeof primary === 'number' &&
+            Number.isSafeInteger(primary) &&
+            primary >= 0
+              ? primary
+              : Number.POSITIVE_INFINITY,
+        }),
+    verifiedAfter:
+      policy.required === true &&
+      typeof verifiedAfter === 'number' &&
+      Number.isSafeInteger(verifiedAfter) &&
+      verifiedAfter >= 0
+        ? verifiedAfter
+        : Number.POSITIVE_INFINITY,
+  };
+}
+
+/** Call only with cryptographically verified Supabase claims. Token iat alone
+ * is not MFA evidence: a refresh must not turn an old proof into a new one. */
+export function mfaProofFromVerifiedClaims(
+  claims: Record<string, unknown>,
+  nowSeconds = Math.floor(Date.now() / 1000)
+): MfaSessionProof | null {
+  if (
+    claims.aal !== 'aal2' ||
+    typeof claims.session_id !== 'string' ||
+    !claims.session_id ||
+    !Array.isArray(claims.amr)
+  ) {
+    return null;
+  }
+  const verifiedAt = claims.amr.reduce<number>((latest, raw) => {
+    if (!raw || typeof raw !== 'object') return latest;
+    const entry = raw as Record<string, unknown>;
+    const timestamp = entry.timestamp;
+    if (
+      !['totp', 'mfa/phone', 'mfa/webauthn', 'mfa/recovery_code'].includes(
+        typeof entry.method === 'string' ? entry.method : ''
+      ) ||
+      typeof timestamp !== 'number' ||
+      !Number.isSafeInteger(timestamp) ||
+      timestamp < 0 ||
+      timestamp > nowSeconds
+    ) {
+      return latest;
+    }
+    return Math.max(latest, timestamp);
+  }, -1);
+  const primaryVerifiedAt = primaryProofTime(claims, nowSeconds);
+  return verifiedAt < 0
+    ? null
+    : {
+        sessionId: claims.session_id,
+        verifiedAt,
+        ...(primaryVerifiedAt === null ? {} : { primaryVerifiedAt }),
+      };
+}
+
+export function satisfiesRequiredMfaPolicy(
+  policy: RequiredMfaPolicy,
+  proof: MfaSessionProof | null,
+  nowSeconds = Math.floor(Date.now() / 1000)
+): boolean {
+  if (!policy.required) return true;
+  return Boolean(
+    isMfaSessionProof(proof) &&
+      proof.verifiedAt > policy.verifiedAfter &&
+      proof.verifiedAt <= nowSeconds &&
+      (policy.primaryVerifiedAfter === undefined ||
+        (proof.primaryVerifiedAt !== undefined &&
+          proof.primaryVerifiedAt > policy.primaryVerifiedAfter &&
+          proof.primaryVerifiedAt <= nowSeconds)) &&
+      (proof.expiresAt === undefined || proof.expiresAt > nowSeconds)
+  );
+}
+
+/** Refresh is never a new primary authentication. */
+export function primaryProofTime(
+  claims: Record<string, unknown>,
+  now = Math.floor(Date.now() / 1000)
+): number | null {
+  if (!Array.isArray(claims.amr)) return null;
+  const methods = new Set([
+    'password',
+    'otp',
+    'oauth',
+    'sso/saml',
+    'sso',
+    'magiclink',
+    'recovery',
+    'invite',
+    'passkey',
+    'web3',
+    'email/signup',
+    'phone/signup',
+  ]);
+  const times = claims.amr.flatMap((entry: unknown) => {
+    if (!entry || typeof entry !== 'object') return [];
+    const value = entry as Record<string, unknown>;
+    return methods.has(String(value.method)) &&
+      typeof value.timestamp === 'number' &&
+      Number.isSafeInteger(value.timestamp) &&
+      value.timestamp >= 0 &&
+      value.timestamp <= now
+      ? [value.timestamp]
+      : [];
+  });
+  return times.length ? Math.max(...times) : null;
+}
+export function requiresFreshPrimaryForMfa(
+  metadata: Record<string, unknown> | null | undefined,
+  claims: Record<string, unknown>
+) {
+  const policy = readRequiredMfaPolicy(metadata);
+  return (
+    policy.required &&
+    policy.primaryVerifiedAfter !== undefined &&
+    (primaryProofTime(claims) ?? -1) <= policy.primaryVerifiedAfter
+  );
+}

package/src/required-mfa-proxy.ts

@@ -0,0 +1,87 @@
+import { type NextRequest, NextResponse } from 'next/server';
+import {
+  type AccountAssuranceDependencies,
+  checkRequiredAccountMfa,
+} from './required-mfa-request';
+
+// These endpoints establish/recover assurance and still perform their own
+// authentication, challenge validation and rate limiting. Never exempt general
+// user, workspace, or administrative APIs from the account policy.
+const RECOVERY_PATHS = new Set([
+  // These exact handoff handlers enforce current policy on the verified body
+  // token. Expired ambient cookies must not prevent obtaining a new session.
+  '/api/auth/verify-app-token',
+  '/api/auth/refresh-app-session',
+  '/api/v1/auth/cross-app-token/verify',
+  '/api/v1/auth/cross-app-session/refresh',
+  '/api/cli/auth/refresh',
+  '/api/v1/auth/mfa/devices',
+  '/api/v1/auth/mfa/mobile/challenges',
+  '/api/v1/auth/mfa/mobile/approvals',
+  '/api/v1/auth/accounts/logout',
+  '/api/v1/auth/accounts/logout-all',
+]);
+
+export function isAccountAssuranceRecoveryPath(pathname: string): boolean {
+  return (
+    RECOVERY_PATHS.has(pathname) ||
+    /^\/api\/v1\/auth\/mfa\/mobile\/challenges\/[0-9a-f-]{36}(?:\/approve)?$/i.test(
+      pathname
+    )
+  );
+}
+
+/** Additional interactive-session assurance check; the caller must first
+ * distinguish independently authenticated machine/webhook credentials and
+ * supply a request-bound auth client appropriate for its runtime. The proxy
+ * must not use next/headers or rotate refresh cookies without propagating them.
+ */
+export async function guardRequiredAccountMfa(
+  request: NextRequest,
+  dependencies: AccountAssuranceDependencies,
+  principal: { userId: string; appToken?: string }
+): Promise<NextResponse | null> {
+  if (
+    request.method === 'OPTIONS' ||
+    isAccountAssuranceRecoveryPath(request.nextUrl.pathname)
+  )
+    return null;
+  const authorization = request.headers.get('authorization');
+  const cookies = request.headers.get('cookie') ?? '';
+  const hasInteractiveCredential = Boolean(
+    authorization?.match(/^Bearer\s+(?:eyJ|ttr_app_)/i) ||
+      /(?:^|;\s*)(?:sb-[^=]+-auth-token(?:\.\d+)?|tuturuuu_(?:web_)?app_session)=/.test(
+        cookies
+      )
+  );
+  if (!hasInteractiveCredential) return null;
+  const result = await checkRequiredAccountMfa(
+    request,
+    dependencies,
+    principal
+  );
+  if (result.status === 'allowed') return null;
+  const status =
+    result.status === 'unavailable'
+      ? 503
+      : result.status === 'invalid'
+        ? 401
+        : 403;
+  return NextResponse.json(
+    {
+      code:
+        result.status === 'required'
+          ? 'MFA_REQUIRED'
+          : result.status === 'invalid'
+            ? 'UNAUTHENTICATED'
+            : 'AUTH_UNAVAILABLE',
+      error:
+        result.status === 'required'
+          ? 'MFA verification required'
+          : result.status === 'invalid'
+            ? 'Authentication required'
+            : 'Unable to verify account security',
+    },
+    { status, headers: { 'Cache-Control': 'no-store' } }
+  );
+}

package/src/required-mfa-request.ts

@@ -0,0 +1,147 @@
+import type { SupabaseUser } from '@tuturuuu/supabase/next/user';
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import { verifyAppCoordinationToken } from './app-coordination-token';
+import { bindCurrentMfaFactor } from './required-mfa-lineage';
+import {
+  isMfaSessionProof,
+  type MfaSessionProof,
+  mfaProofFromVerifiedClaims,
+  readRequiredMfaPolicy,
+  requiresFreshPrimaryForMfa,
+  satisfiesRequiredMfaPolicy,
+} from './required-mfa-policy';
+
+type RequestLike = Pick<Request, 'headers'> & Partial<Pick<Request, 'url'>>;
+export type AccountAssuranceResult =
+  | { status: 'allowed'; userId: string; proof: MfaSessionProof | null }
+  | { status: 'required'; userId: string }
+  | { status: 'unavailable' }
+  | { status: 'invalid' };
+
+export interface AccountAssuranceDependencies {
+  createUserClient(request: RequestLike): Promise<TypedSupabaseClient>;
+  createAdminClient(): Promise<TypedSupabaseClient>;
+  nowSeconds(): number;
+}
+
+/** Enforces fresh server-owned policy, never user metadata or unverified JWTs.
+ * Authentication/authorization remains the responsibility of each route.
+ * This helper intentionally has no policy cache: recovery takes effect on the
+ * next request, including for an already-issued app access/refresh token.
+ */
+export async function checkRequiredAccountMfa(
+  request: RequestLike,
+  dependencies: AccountAssuranceDependencies,
+  /** Bind to the principal resolved by the route, using its selected credential.
+   * Never approve one cookie while the route authorizes another identity. */
+  principal: { userId: string; appToken?: string }
+): Promise<AccountAssuranceResult> {
+  try {
+    const token = principal.appToken;
+    let user: SupabaseUser;
+    let proof: MfaSessionProof | null;
+    let sessionId: string | undefined;
+    let admin: TypedSupabaseClient | undefined;
+    const now = dependencies.nowSeconds();
+    if (token) {
+      const verification = verifyAppCoordinationToken(token);
+      if (!verification.ok) return { status: 'invalid' };
+      admin = await dependencies.createAdminClient();
+      const result = await admin.auth.admin.getUserById(
+        verification.claims.sub
+      );
+      if (result.error || !result.data.user) return { status: 'unavailable' };
+      user = result.data.user;
+      if (user.id !== verification.claims.sub || user.id !== principal.userId) {
+        return { status: 'invalid' };
+      }
+      proof = verification.claims.mfa ?? null;
+      sessionId = proof?.sessionId;
+    } else {
+      const client = await dependencies.createUserClient(request);
+      const result = await client.auth.getUser();
+      if (result.error || !result.data.user) return { status: 'invalid' };
+      user = result.data.user;
+      if (user.id !== principal.userId) return { status: 'invalid' };
+      if (user.banned_until && Date.parse(user.banned_until) / 1000 > now)
+        return { status: 'invalid' };
+      // No extra claims request is needed for accounts without the policy.
+      if (!readRequiredMfaPolicy(user.app_metadata).required) {
+        return { status: 'allowed', userId: user.id, proof: null };
+      }
+      const claims = await client.auth.getClaims();
+      if (claims.error || claims.data?.claims?.sub !== user.id) {
+        return { status: 'invalid' };
+      }
+      if (requiresFreshPrimaryForMfa(user.app_metadata, claims.data.claims))
+        return { status: 'required', userId: user.id };
+      proof = mfaProofFromVerifiedClaims(claims.data.claims, now);
+      sessionId =
+        typeof claims.data.claims.session_id === 'string'
+          ? claims.data.claims.session_id
+          : undefined;
+    }
+    if (user.banned_until && Date.parse(user.banned_until) / 1000 > now)
+      return { status: 'invalid' };
+    const policy = readRequiredMfaPolicy(user.app_metadata);
+    if (!policy.required) return { status: 'allowed', userId: user.id, proof };
+    if (proof && satisfiesRequiredMfaPolicy(policy, proof, now)) {
+      admin ??= await dependencies.createAdminClient();
+      const bound = await bindCurrentMfaFactor(admin, user.id, proof, !token);
+      if (bound) return { status: 'allowed', userId: user.id, proof: bound };
+    }
+    // A signed app proof is immutable: only its original provider requester
+    // may consume a new mobile approval and mint a replacement handoff.
+    if (!token && sessionId && Number.isFinite(policy.verifiedAfter)) {
+      admin ??= await dependencies.createAdminClient();
+      const result = await admin
+        .from('qr_login_challenges')
+        .select('approved_at, approval_metadata, request_metadata')
+        .eq('approver_user_id', user.id)
+        .eq('status', 'consumed')
+        .eq('request_metadata->>kind', 'mfa_mobile_approval')
+        .eq('request_metadata->>requesterSessionId', sessionId)
+        .eq('approval_metadata->>approverSessionId', sessionId)
+        .not('consumed_at', 'is', null)
+        .order('approved_at', { ascending: false })
+        .limit(1)
+        .maybeSingle();
+      if (result.error) return { status: 'unavailable' };
+      const row = result.data;
+      if (row) {
+        const approvedAt = Date.parse(row.approved_at ?? '') / 1000;
+        const metadata = row.approval_metadata as Record<
+          string,
+          unknown
+        > | null;
+        const until = metadata?.mobileMfaValidUntil;
+        if (
+          Math.floor(approvedAt) > policy.verifiedAfter &&
+          approvedAt <= now &&
+          typeof until === 'string' &&
+          Date.parse(until) / 1000 > now
+        ) {
+          const source = metadata?.requiredMfaProof;
+          if (
+            isMfaSessionProof(source) &&
+            satisfiesRequiredMfaPolicy(policy, source, now)
+          ) {
+            const bound = await bindCurrentMfaFactor(admin, user.id, source);
+            if (bound)
+              return {
+                status: 'allowed',
+                userId: user.id,
+                proof: {
+                  ...bound,
+                  expiresAt: Math.floor(Date.parse(until) / 1000),
+                },
+              };
+          }
+        }
+      }
+    }
+    return { status: 'required', userId: user.id };
+  } catch {
+    return { status: 'unavailable' };
+  }
+}

package/src/required-mfa-runtime.ts

@@ -0,0 +1,103 @@
+import { createAdminClient } from '@tuturuuu/supabase/next/server';
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import { type NextRequest, NextResponse } from 'next/server';
+import { verifyAppCoordinationToken } from './app-coordination-token';
+import { accountAssuranceCredentials } from './required-mfa-credentials';
+import { isAccountAssuranceRecoveryPath } from './required-mfa-proxy';
+import { checkRequiredAccountMfa } from './required-mfa-request';
+
+/** Check every usable cookie identity, so downstream target-app fallback cannot
+ * borrow another session's assurance. Cookie-only legacy handlers can ignore a
+ * Bearer header, so ambient credentials must be checked as well.
+ * Uses explicit access tokens and never rotates browser refresh cookies. */
+export async function enforceRequiredMfaRequest(request: NextRequest) {
+  if (
+    request.method === 'OPTIONS' ||
+    isAccountAssuranceRecoveryPath(request.nextUrl.pathname)
+  )
+    return null;
+  const credentials = accountAssuranceCredentials(request);
+  if (!credentials.length) return null;
+  try {
+    const admin = (await createAdminClient({
+      noCookie: true,
+    })) as TypedSupabaseClient;
+    for (const token of credentials) {
+      let userId: string;
+      const appToken = token.startsWith('ttr_app_');
+      if (appToken) {
+        const verified = verifyAppCoordinationToken(token);
+        if (!verified.ok) {
+          if (
+            request.headers
+              .get('authorization')
+              ?.match(/^Bearer\s+(\S+)$/i)?.[1] === token
+          )
+            return unauthenticated();
+          continue; // An expired ambient app cookie cannot authenticate a route.
+        }
+        userId = verified.claims.sub;
+      } else {
+        const result = await admin.auth.getUser(token);
+        if (result.error || !result.data.user) return unauthenticated();
+        userId = result.data.user.id;
+      }
+      const result = await checkRequiredAccountMfa(
+        request,
+        {
+          createAdminClient: async () => admin,
+          createUserClient: async () =>
+            ({
+              auth: {
+                getUser: () => admin.auth.getUser(token),
+                getClaims: () => admin.auth.getClaims(token),
+              },
+            }) as unknown as TypedSupabaseClient,
+          nowSeconds: () => Math.floor(Date.now() / 1000),
+        },
+        { userId, appToken: appToken ? token : undefined }
+      );
+      if (result.status === 'invalid') return unauthenticated();
+      if (result.status !== 'allowed') {
+        return NextResponse.json(
+          {
+            code:
+              result.status === 'required'
+                ? 'MFA_REQUIRED'
+                : 'AUTH_UNAVAILABLE',
+            error:
+              result.status === 'required'
+                ? 'MFA verification required'
+                : 'Unable to verify account security',
+          },
+          {
+            status: result.status === 'required' ? 403 : 503,
+            headers: {
+              'Cache-Control': 'no-store',
+              'X-Tuturuuu-Auth-Assurance': result.status,
+            },
+          }
+        );
+      }
+    }
+    return null;
+  } catch {
+    return NextResponse.json(
+      { code: 'AUTH_UNAVAILABLE', error: 'Unable to verify account security' },
+      {
+        status: 503,
+        headers: {
+          'Cache-Control': 'no-store',
+          'X-Tuturuuu-Auth-Assurance': 'unavailable',
+        },
+      }
+    );
+  }
+}
+
+function unauthenticated() {
+  return NextResponse.json(
+    { code: 'UNAUTHENTICATED', error: 'Authentication required' },
+    { status: 401, headers: { 'Cache-Control': 'no-store' } }
+  );
+}

package/src/required-mfa-supabase-session.ts

@@ -0,0 +1,33 @@
+import { createAdminClient } from '@tuturuuu/supabase/next/server';
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import { checkRequiredAccountMfa } from './required-mfa-request';
+
+/** Only call after the provider has cryptographically verified these claims.
+ * Retain a consumed mobile approval's original boundary and expiry in handoffs.
+ */
+export async function resolveVerifiedSupabaseMfa(
+  claims: Record<string, unknown>
+) {
+  if (typeof claims.sub !== 'string') throw new Error('Invalid session');
+  const admin = (await createAdminClient({
+    noCookie: true,
+  })) as TypedSupabaseClient;
+  const result = await checkRequiredAccountMfa(
+    { headers: new Headers() },
+    {
+      createAdminClient: async () => admin,
+      createUserClient: async () =>
+        ({
+          auth: {
+            getUser: () => admin.auth.admin.getUserById(claims.sub as string),
+            getClaims: async () => ({ data: { claims }, error: null }),
+          },
+        }) as unknown as TypedSupabaseClient,
+      nowSeconds: () => Math.floor(Date.now() / 1000),
+    },
+    { userId: claims.sub }
+  );
+  if (result.status === 'unavailable' || result.status === 'invalid')
+    throw new Error('Account assurance unavailable');
+  return result;
+}

package/src/required-mfa-transfer.ts

@@ -0,0 +1,41 @@
+import {
+  createAppCoordinationToken,
+  verifyAppCoordinationToken,
+} from './app-coordination-token';
+import type { MfaSessionProof } from './required-mfa-policy';
+
+const TRANSFER_SCOPE = 'mfa:transfer';
+/** session_data is caller writable. Carry only an independently signed, short
+ * lived proof bound to the handoff identity and target app. */
+export function createMfaTransfer(
+  userId: string,
+  targetApp: string,
+  mfa: MfaSessionProof | null
+) {
+  return mfa
+    ? createAppCoordinationToken({
+        userId,
+        targetApp,
+        mfa,
+        scopes: [TRANSFER_SCOPE],
+        expiresInSeconds: 300,
+      }).token
+    : undefined;
+}
+
+export function readMfaTransfer(
+  value: unknown,
+  userId: string,
+  targetApp: string
+): MfaSessionProof | null {
+  if (typeof value !== 'string') return null;
+  const verified = verifyAppCoordinationToken(value);
+  if (
+    !verified.ok ||
+    verified.claims.sub !== userId ||
+    verified.claims.target_app !== targetApp ||
+    !verified.claims.scopes.includes(TRANSFER_SCOPE)
+  )
+    return null;
+  return verified.claims.mfa ?? null;
+}