@tuturuuu/utils 0.29.1 → 0.31.0

package/src/app-coordination-token.ts

@@ -0,0 +1,247 @@
+import { createHmac, randomUUID, timingSafeEqual } from 'node:crypto';
+
+import { isMfaSessionProof, type MfaSessionProof } from './required-mfa-policy';
+
+const TOKEN_PREFIX = 'ttr_app_';
+const TOKEN_ISSUER = 'tuturuuu';
+const TOKEN_AUDIENCE = 'tuturuuu-api';
+const DEFAULT_EXPIRES_IN_SECONDS = 8 * 60 * 60;
+const LOCAL_DEVELOPMENT_SECRET =
+  'tuturuuu-local-development-app-coordination-secret';
+
+export type AppCoordinationTokenClaims = {
+  aud: typeof TOKEN_AUDIENCE;
+  email: string | null;
+  exp: number;
+  iat: number;
+  iss: typeof TOKEN_ISSUER;
+  jti: string;
+  mfa?: MfaSessionProof;
+  origin_app: string;
+  scopes: string[];
+  sub: string;
+  target_app: string;
+  typ: 'app_coordination';
+};
+
+export type AppCoordinationTokenPayload = {
+  email?: string | null;
+  expiresInSeconds?: number;
+  mfa?: MfaSessionProof;
+  originApp?: string;
+  scopes?: string[];
+  targetApp: string;
+  userId: string;
+};
+
+export type AppCoordinationTokenVerification =
+  | {
+      claims: AppCoordinationTokenClaims;
+      ok: true;
+    }
+  | {
+      error: string;
+      ok: false;
+    };
+
+function getSecretCandidates(explicitSecret?: string) {
+  const candidates = explicitSecret
+    ? [explicitSecret]
+    : [
+        process.env.TUTURUUU_APP_COORDINATION_SECRET,
+        process.env.APP_COORDINATION_TOKEN_SECRET,
+        process.env.SUPABASE_SECRET_KEY,
+        process.env.SUPABASE_SERVICE_ROLE_KEY,
+        process.env.SUPABASE_SERVICE_KEY,
+      ];
+
+  const secrets = candidates
+    .map((value) => value?.trim())
+    .filter((value): value is string => Boolean(value));
+
+  if (secrets.length === 0 && process.env.NODE_ENV !== 'production') {
+    return [LOCAL_DEVELOPMENT_SECRET];
+  }
+
+  if (secrets.length === 0) {
+    throw new Error(
+      'Missing TUTURUUU_APP_COORDINATION_SECRET or SUPABASE_SECRET_KEY'
+    );
+  }
+
+  return [...new Set(secrets)];
+}
+
+function getSigningSecret(explicitSecret?: string) {
+  return getSecretCandidates(explicitSecret)[0]!;
+}
+
+function getVerificationSecrets(explicitSecret?: string) {
+  return getSecretCandidates(explicitSecret);
+}
+
+function encodeBase64Url(value: string | Buffer) {
+  return Buffer.from(value).toString('base64url');
+}
+
+function decodeBase64Url(value: string) {
+  return Buffer.from(value, 'base64url').toString('utf8');
+}
+
+function signContent(content: string, secret: string) {
+  return createHmac('sha256', secret).update(content).digest('base64url');
+}
+
+function safeJsonParse(value: string): unknown {
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return null;
+  }
+}
+
+function isClaims(value: unknown): value is AppCoordinationTokenClaims {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+
+  const claims = value as Partial<AppCoordinationTokenClaims>;
+
+  return (
+    (claims.mfa === undefined || isMfaSessionProof(claims.mfa)) &&
+    claims.typ === 'app_coordination' &&
+    claims.iss === TOKEN_ISSUER &&
+    claims.aud === TOKEN_AUDIENCE &&
+    typeof claims.sub === 'string' &&
+    typeof claims.target_app === 'string' &&
+    typeof claims.origin_app === 'string' &&
+    typeof claims.iat === 'number' &&
+    typeof claims.exp === 'number' &&
+    typeof claims.jti === 'string' &&
+    Array.isArray(claims.scopes)
+  );
+}
+
+export function isAppCoordinationToken(token: string | null | undefined) {
+  return Boolean(token?.startsWith(TOKEN_PREFIX));
+}
+
+export function getBearerAppCoordinationToken(
+  request: Pick<Request, 'headers'>
+) {
+  const authorization =
+    request.headers.get('authorization') ??
+    request.headers.get('Authorization');
+
+  if (!authorization?.toLowerCase().startsWith('bearer ')) {
+    return null;
+  }
+
+  const token = authorization.slice(7).trim();
+
+  return isAppCoordinationToken(token) ? token : null;
+}
+
+export function createAppCoordinationToken(
+  payload: AppCoordinationTokenPayload,
+  options: {
+    now?: Date;
+    secret?: string;
+  } = {}
+) {
+  if (payload.mfa !== undefined && !isMfaSessionProof(payload.mfa)) {
+    throw new Error('Invalid MFA session proof');
+  }
+  const secret = getSigningSecret(options.secret);
+  const nowSeconds = Math.floor((options.now ?? new Date()).getTime() / 1000);
+  const expiresInSeconds =
+    payload.expiresInSeconds ?? DEFAULT_EXPIRES_IN_SECONDS;
+  const header = {
+    alg: 'HS256',
+    typ: 'JWT',
+  };
+  const claims: AppCoordinationTokenClaims = {
+    aud: TOKEN_AUDIENCE,
+    email: payload.email ?? null,
+    exp: nowSeconds + expiresInSeconds,
+    iat: nowSeconds,
+    iss: TOKEN_ISSUER,
+    jti: randomUUID(),
+    ...(payload.mfa ? { mfa: payload.mfa } : {}),
+    origin_app: payload.originApp ?? 'web',
+    scopes: payload.scopes ?? [],
+    sub: payload.userId,
+    target_app: payload.targetApp,
+    typ: 'app_coordination',
+  };
+  const unsigned = `${encodeBase64Url(JSON.stringify(header))}.${encodeBase64Url(
+    JSON.stringify(claims)
+  )}`;
+  const signature = signContent(unsigned, secret);
+
+  return {
+    claims,
+    expiresAt: new Date(claims.exp * 1000).toISOString(),
+    token: `${TOKEN_PREFIX}${unsigned}.${signature}`,
+  };
+}
+
+export function verifyAppCoordinationToken(
+  token: string,
+  options: {
+    now?: Date;
+    secret?: string;
+  } = {}
+): AppCoordinationTokenVerification {
+  if (!isAppCoordinationToken(token)) {
+    return { error: 'Invalid token type', ok: false };
+  }
+
+  const withoutPrefix = token.slice(TOKEN_PREFIX.length);
+  const parts = withoutPrefix.split('.');
+
+  if (parts.length !== 3) {
+    return { error: 'Invalid token format', ok: false };
+  }
+
+  const [encodedHeader, encodedPayload, signature] = parts;
+
+  if (!encodedHeader || !encodedPayload || !signature) {
+    return { error: 'Invalid token format', ok: false };
+  }
+
+  const unsigned = `${encodedHeader}.${encodedPayload}`;
+  const signatureBuffer = Buffer.from(signature);
+  const signatureMatches = getVerificationSecrets(options.secret).some(
+    (secret) => {
+      const expectedSignature = signContent(unsigned, secret);
+      const expectedSignatureBuffer = Buffer.from(expectedSignature);
+
+      return (
+        signatureBuffer.length === expectedSignatureBuffer.length &&
+        timingSafeEqual(signatureBuffer, expectedSignatureBuffer)
+      );
+    }
+  );
+
+  if (!signatureMatches) {
+    return { error: 'Invalid token signature', ok: false };
+  }
+
+  const claims = safeJsonParse(decodeBase64Url(encodedPayload));
+
+  if (!isClaims(claims)) {
+    return { error: 'Invalid token claims', ok: false };
+  }
+
+  const nowSeconds = Math.floor((options.now ?? new Date()).getTime() / 1000);
+
+  if (claims.exp <= nowSeconds) {
+    return { error: 'Token expired', ok: false };
+  }
+
+  return {
+    claims,
+    ok: true,
+  };
+}

package/src/commercial-comparison.ts

@@ -9,6 +9,13 @@ import { features2 } from './commercial-comparison-2';
 
 const gateOrder = ['FREE', 'PLUS', 'PRO', 'ENTERPRISE'];
 const advanced: ComparisonFeature[] = [
+  {
+    id: 'parley_0',
+    app: 'parley',
+    category: 'internal',
+    detail: 'standard',
+    values: ['internal', 'internal', 'internal', 'internal'],
+  },
   {
     id: 'prioritySupport',
     app: 'platform',

package/src/internal-domains.ts

@@ -4,6 +4,7 @@ import {
 } from './portless';
 
 export const PRODUCTION_INTERNAL_APP_DOMAINS = [
+  { name: 'parley', url: 'https://parley.tuturuuu.com' },
   { name: 'lettin', url: 'https://lettin.tuturuuu.com' },
   { name: 'colab', url: 'https://colab.tuturuuu.com' },
   {
@@ -133,6 +134,7 @@ export const PRODUCTION_INTERNAL_APP_DOMAINS = [
 ] as const;
 
 export const PORTLESS_INTERNAL_APP_DOMAINS = [
+  { name: 'parley', url: getTuturuuuPortlessAppOrigin('parley') },
   { name: 'lettin', url: getTuturuuuPortlessAppOrigin('lettin') },
   { name: 'colab', url: getTuturuuuPortlessAppOrigin('colab') },
   {
@@ -254,6 +256,7 @@ export const PORTLESS_INTERNAL_APP_DOMAINS = [
 ] as const;
 
 export const LOCALHOST_INTERNAL_APP_DOMAINS = [
+  { name: 'parley', url: 'http://localhost:7834' },
   { name: 'lettin', url: 'http://localhost:7833' },
   { name: 'colab', url: 'http://localhost:8795' },
   {

package/src/launchable-apps.ts

@@ -412,6 +412,18 @@ export const LAUNCHABLE_APPS = [
     title: '(Tu)lettin',
     workspacePathResolver: workspaceRootPath,
   },
+  {
+    aliases: ['Scenario training', 'Roleplay'],
+    appRoot: 'apps/parley',
+    category: 'ai',
+    defaultPath: '/',
+    localhostOrigin: 'http://localhost:7834',
+    packageName: '@tuturuuu/parley',
+    portlessApp: 'parley',
+    productionUrl: 'https://parley.tuturuuu.com',
+    slug: 'parley',
+    title: 'Parley',
+  },
 ] as const satisfies readonly LaunchableApp[];
 
 export type LaunchableAppSlug = (typeof LAUNCHABLE_APPS)[number]['slug'];

package/src/onboarding.ts

@@ -71,6 +71,12 @@ export const GOAL_RECOMMENDATIONS = {
 } as const satisfies Record<OnboardingGoal, readonly string[]>;
 
 const MISSIONS = [
+  [
+    'parley',
+    'learn',
+    'confirmation_required',
+    ['scenario', 'practice', 'reflect'],
+  ],
   ['colab', 'learn', 'reversible', ['prompt', 'simulate', 'review']],
   ['platform', 'focus', 'reversible', ['overview', 'apps', 'next_move']],
   ['calendar', 'focus', 'reversible', ['schedule', 'timebox', 'review']],

package/src/platform-release.test.ts

@@ -7,7 +7,7 @@ import {
 
 describe('platform release metadata', () => {
   it('uses the centralized shared browser app version', () => {
-    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.53.0'); // x-release-please-version
+    expect(TUTURUUU_PLATFORM_VERSION).toBe('0.55.0'); // x-release-please-version
   });
 
   it('preserves the source timestamp in builtAt and derives a short hash', () => {

package/src/platform-release.ts

@@ -1,6 +1,6 @@
 import { PLATFORM_BUILD_METADATA } from './generated/platform-build-metadata';
 
-export const TUTURUUU_PLATFORM_VERSION = '0.53.0'; // x-release-please-version
+export const TUTURUUU_PLATFORM_VERSION = '0.55.0'; // x-release-please-version
 
 export type PlatformBuildMetadataInput = {
   /** ISO timestamp of the source commit used for the build, not deployment time. */

package/src/portless.ts

@@ -6,6 +6,7 @@ export const TUTURUUU_PORTLESS_ALLOWED_DEV_ORIGINS = [
 ] as const;
 
 export const TUTURUUU_PORTLESS_APP_ORIGINS = {
+  parley: `https://parley.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   ai: `https://ai.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   apps: `https://apps.${TUTURUUU_PORTLESS_ROOT_HOST}`,
   calendar: `https://calendar.${TUTURUUU_PORTLESS_ROOT_HOST}`,

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

@@ -0,0 +1,30 @@
+import { updateSession } from '@tuturuuu/supabase/next/proxy';
+import { type NextRequest, NextResponse } from 'next/server';
+import { discardAppCookiesForVerifiedProvider } from './required-mfa-credentials';
+import { isAccountAssuranceRecoveryPath } from './required-mfa-proxy';
+
+/** Refresh browser provider cookies before checking assurance, and propagate
+ * rotated cookies even when policy redirects/rejects the subsequent request.
+ * Explicit credentials and refresh/handoff handlers retain their own lifecycle.
+ */
+export async function guardBrowserApiSession(
+  request: NextRequest,
+  guard: () => Promise<NextResponse | null>
+) {
+  const hasProviderCookie = request.cookies
+    .getAll()
+    .some(({ name }) => /^sb-[a-z0-9-]+-auth-token(?:\.\d+)?$/i.test(name));
+  const session =
+    !request.headers.has('authorization') &&
+    hasProviderCookie &&
+    !isAccountAssuranceRecoveryPath(request.nextUrl.pathname)
+      ? await updateSession(request)
+      : null;
+  if (session?.claims) discardAppCookiesForVerifiedProvider(request);
+  const response =
+    (await guard()) ??
+    NextResponse.next({ request: { headers: request.headers } });
+  for (const cookie of session?.res.headers.getSetCookie() ?? [])
+    response.headers.append('set-cookie', cookie);
+  return response;
+}

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

@@ -0,0 +1,34 @@
+import { createAdminClient } from '@tuturuuu/supabase/next/server';
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import type { AppCoordinationTokenClaims } from './app-coordination-token';
+import { bindCurrentMfaFactor } from './required-mfa-lineage';
+import {
+  type MfaSessionProof,
+  readRequiredMfaPolicy,
+  satisfiesRequiredMfaPolicy,
+} from './required-mfa-policy';
+
+/** Claims must already be signature/scope/target verified by the caller. */
+export async function isRequiredMfaAppSessionAllowed(
+  claims: AppCoordinationTokenClaims
+) {
+  return isRequiredMfaProofAllowed(claims.sub, claims.mfa ?? null);
+}
+
+export async function isRequiredMfaProofAllowed(
+  userId: string,
+  proof: MfaSessionProof | null
+) {
+  const admin = (await createAdminClient({
+    noCookie: true,
+  })) as TypedSupabaseClient;
+  const { data, error } = await admin.auth.admin.getUserById(userId);
+  if (error) throw new Error('Account security is unavailable');
+  if (!data.user || data.user.id !== userId) return false;
+  if (data.user.banned_until && Date.parse(data.user.banned_until) > Date.now())
+    return false;
+  const policy = readRequiredMfaPolicy(data.user.app_metadata);
+  if (!policy.required) return true;
+  if (!proof || !satisfiesRequiredMfaPolicy(policy, proof)) return false;
+  return Boolean(await bindCurrentMfaFactor(admin, userId, proof));
+}

package/src/required-mfa-browser.ts

@@ -0,0 +1,42 @@
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import {
+  mfaProofFromVerifiedClaims,
+  readRequiredMfaPolicy,
+  satisfiesRequiredMfaPolicy,
+} from './required-mfa-policy';
+
+/** UX routing only; server/database gates remain authoritative. */
+export async function requiresAccountMfa(
+  client: TypedSupabaseClient,
+  options: { acceptMobileApproval?: boolean } = {}
+) {
+  const user = await client.auth.getUser();
+  if (user.error || !user.data.user)
+    throw new Error('Unable to verify account security');
+  const policy = readRequiredMfaPolicy(user.data.user.app_metadata);
+  if (policy.required) {
+    const claims = await client.auth.getClaims();
+    if (claims.error || claims.data?.claims.sub !== user.data.user.id)
+      return true;
+    if (
+      !satisfiesRequiredMfaPolicy(
+        policy,
+        mfaProofFromVerifiedClaims(claims.data.claims)
+      )
+    ) {
+      if (options.acceptMobileApproval) {
+        // The database validates the consumed approval against this exact
+        // provider session, current policy boundary, and proof expiry.
+        const result = await client.rpc('account_required_mfa_satisfied');
+        if (!result.error && result.data === true) return false;
+      }
+      return true;
+    }
+    const verified = await client.rpc('account_required_mfa_satisfied');
+    return Boolean(verified.error || verified.data !== true);
+  }
+  const { data, error } =
+    await client.auth.mfa.getAuthenticatorAssuranceLevel();
+  if (error) throw error;
+  return data.currentLevel === 'aal1' && data.nextLevel === 'aal2';
+}

package/src/required-mfa-credentials.ts

@@ -0,0 +1,58 @@
+import {
+  getSupabaseAuthCookieUrls,
+  getSupabaseAuthStorageKey,
+} from '@tuturuuu/supabase/next/common';
+import type { NextRequest } from 'next/server';
+
+/** Read opaque credentials only. No decoded claim is trusted here; each token
+ * is verified by the provider or our app-token verifier before policy lookup. */
+export function accountAssuranceCredentials(request: NextRequest): string[] {
+  const bearer = request.headers
+    .get('authorization')
+    ?.match(/^Bearer\s+(\S+)$/i)?.[1];
+  const tokens = new Set<string>();
+  if (bearer && /^(?:eyJ|ttr_app_)/.test(bearer)) tokens.add(bearer);
+  for (const name of ['tuturuuu_web_app_session', 'tuturuuu_app_session']) {
+    const token = request.cookies.get(name)?.value;
+    if (token?.startsWith('ttr_app_')) tokens.add(token);
+  }
+  // Browser auth uses this project key even when the server URL is internal.
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  if (!url) return [...tokens];
+  for (const cookieUrl of getSupabaseAuthCookieUrls(url)) {
+    const key = getSupabaseAuthStorageKey(cookieUrl);
+    let raw = request.cookies.get(key)?.value;
+    if (!raw) {
+      const chunks: string[] = [];
+      for (let index = 0; request.cookies.has(`${key}.${index}`); index += 1) {
+        chunks.push(request.cookies.get(`${key}.${index}`)!.value);
+      }
+      raw = chunks.join('');
+    }
+    if (raw) {
+      try {
+        const decoded = raw.startsWith('base64-')
+          ? Buffer.from(raw.slice(7), 'base64url').toString('utf8')
+          : raw;
+        const session = JSON.parse(decoded) as { access_token?: unknown };
+        if (typeof session.access_token === 'string')
+          tokens.add(session.access_token);
+      } catch {
+        // Existing authentication/malformed-cookie guards reject these cookies.
+      }
+    }
+  }
+  return [...tokens];
+}
+
+/** Provider-first proxies must remove superseded app credentials from the
+ * forwarded request, not merely ignore them during policy enforcement. */
+export function discardAppCookiesForVerifiedProvider(request: NextRequest) {
+  for (const name of [
+    'tuturuuu_app_session',
+    'tuturuuu_web_app_session',
+    'tuturuuu_app_session_refresh',
+    'tuturuuu_web_app_session_refresh',
+  ])
+    request.cookies.delete(name);
+}

package/src/required-mfa-lineage.ts

@@ -0,0 +1,22 @@
+import type { TypedSupabaseClient } from '@tuturuuu/supabase/types';
+import type { MfaSessionProof } from './required-mfa-policy';
+
+/** The provider JWT does not contain factor_id. Resolve its verified session
+ * against current GoTrue factor state; signed handoffs retain that exact id. */
+export async function bindCurrentMfaFactor(
+  admin: TypedSupabaseClient,
+  userId: string,
+  proof: MfaSessionProof,
+  allowInitialBinding = false
+): Promise<MfaSessionProof | null> {
+  if (!proof.factorId && !allowInitialBinding) return null;
+  const { data, error } = await admin.rpc('account_mfa_verified_factor', {
+    p_user_id: userId,
+    p_session_id: proof.verificationSessionId ?? proof.sessionId,
+    p_verified_at: proof.verifiedAt,
+    p_primary_verified_at: proof.primaryVerifiedAt,
+  });
+  if (error) throw new Error('Account factor verification unavailable');
+  if (!data || (proof.factorId && data !== proof.factorId)) return null;
+  return { ...proof, factorId: data };
+}