@tuturuuu/utils 0.6.1 → 0.8.0

package/src/api-proxy-guard.ts

@@ -2,6 +2,10 @@ import { Ratelimit } from '@upstash/ratelimit';
 import type { NextRequest } from 'next/server';
 import { NextResponse } from 'next/server';
 import { extractIPFromRequest, isIPBlockedEdge } from './abuse-protection/edge';
+import {
+  type CachedTrustEntry,
+  getCachedTrustEntries,
+} from './abuse-protection/edge-trust';
 import { DEV_MODE, MAX_PAYLOAD_SIZE } from './constants';
 import { validateRequestEmojiLimit } from './request-emoji-limit';
 import {
@@ -11,6 +15,45 @@ import {
 
 const isDev = process.env.NODE_ENV !== 'production';
 
+// Quantized trust tiers — the cached multiplier is floored to one of these
+// before scaling read limits, so the limiter prefix (and therefore the Redis
+// sliding-window buckets) stays bounded and stable even as a subject's exact
+// multiplier drifts.
+const TRUST_MULTIPLIER_TIERS = [1, 1.5, 2, 3, 5, 10, 25, 100] as const;
+
+function isEnvFlagEnabled(name: string, defaultOn = true): boolean {
+  const raw = process.env[name];
+  if (raw == null || raw.trim() === '') {
+    return defaultOn;
+  }
+
+  return !/^(0|false|off|no)$/i.test(raw.trim());
+}
+
+/**
+ * Whether trusted accounts/locations get scaled read limits (and trusted
+ * sessions get their own per-session bucket) at the edge. Default on; set
+ * `API_PROXY_EDGE_TRUST_ENABLED=0` to disable trust uplift and fall back to
+ * legacy per-IP read limiting without a deploy.
+ */
+function edgeTrustEnabled(): boolean {
+  return isEnvFlagEnabled('API_PROXY_EDGE_TRUST_ENABLED');
+}
+
+/**
+ * Floors a raw trust multiplier to the nearest quantized tier. Never reduces
+ * below 1 — trust uplift only ever raises read limits.
+ */
+function quantizeTrustMultiplier(multiplier: number): number {
+  let tier = 1;
+  for (const candidate of TRUST_MULTIPLIER_TIERS) {
+    if (multiplier >= candidate) {
+      tier = candidate;
+    }
+  }
+  return tier;
+}
+
 type CallerClass = 'anonymous' | 'authenticated';
 
 export type RateLimitWindow = 'minute' | 'hour' | 'day';
@@ -37,6 +80,7 @@ export type TrustedProxyBypassRule = {
 };
 
 export type GuardOptions = {
+  additionalRoutePolicies?: ProxyRoutePolicy[];
   prefixBase: string;
   routePolicies?: ProxyRoutePolicy[];
   trustedBypassRules?: TrustedProxyBypassRule[];
@@ -250,15 +294,24 @@ const TASK_BOARD_READ_RATE_LIMITS: RateLimitProfile = {
     createConfig(
       'minute',
       '1 m',
-      300,
+      600,
       'API_PROXY_TASK_BOARD_READ_LIMIT_MINUTE'
     ),
-    createConfig('hour', '1 h', 3000, 'API_PROXY_TASK_BOARD_READ_LIMIT_HOUR'),
-    createConfig('day', '1 d', 20_000, 'API_PROXY_TASK_BOARD_READ_LIMIT_DAY'),
+    createConfig('hour', '1 h', 12_000, 'API_PROXY_TASK_BOARD_READ_LIMIT_HOUR'),
+    createConfig('day', '1 d', 80_000, 'API_PROXY_TASK_BOARD_READ_LIMIT_DAY'),
   ],
   mutate: DEFAULT_MUTATE_RATE_LIMITS,
 };
 
+const USERS_DATABASE_READ_OVER_POST_RATE_LIMITS: RateLimitProfile = {
+  get: NO_READ_RATE_LIMITS,
+  mutate: [
+    { window: 'minute', limit: 300, duration: '1 m' },
+    { window: 'hour', limit: 3000, duration: '1 h' },
+    { window: 'day', limit: 20_000, duration: '1 d' },
+  ],
+};
+
 const FINANCE_READ_RATE_LIMITS: RateLimitProfile = {
   get: [
     createConfig('minute', '1 m', 1200, 'API_PROXY_FINANCE_READ_LIMIT_MINUTE', [
@@ -299,6 +352,16 @@ function isFinanceRead(req: NextRequest) {
   );
 }
 
+function isUsersDatabaseReadOverPost(req: NextRequest) {
+  if (req.method !== 'POST') {
+    return false;
+  }
+
+  return /^\/api\/v1\/workspaces\/[^/]+\/users\/(?:database|groups\/(?:featured-counts|possible-excluded))\/?$/u.test(
+    req.nextUrl.pathname
+  );
+}
+
 const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
   {
     key: 'cron',
@@ -363,6 +426,11 @@ const DEFAULT_ROUTE_POLICIES: ProxyRoutePolicy[] = [
         )),
     rateLimits: TASK_BOARD_READ_RATE_LIMITS,
   },
+  {
+    key: 'users-database-read-over-post',
+    matches: isUsersDatabaseReadOverPost,
+    rateLimits: USERS_DATABASE_READ_OVER_POST_RATE_LIMITS,
+  },
   {
     key: 'finance-read',
     matches: isFinanceRead,
@@ -742,10 +810,241 @@ export function hasAuthenticatedApiSession(req: NextRequest): boolean {
 }
 
 function getCallerClass(req: NextRequest): CallerClass {
+  // Intentionally always 'anonymous'. Auth headers/cookies are forgeable at the
+  // edge (we can't verify signatures cheaply here), so presence alone must never
+  // grant an elevated proxy budget — real per-user enforcement happens
+  // downstream. Higher read throughput for genuinely trusted accounts/locations
+  // is granted instead via the server-written trust cache (see resolveProxyIdentity
+  // + getCachedTrustMultiplier), which cannot be forged.
   void req;
   return 'anonymous';
 }
 
+/**
+ * Edge-safe stable subject hash. MUST stay byte-identical to
+ * `reputation.ts hashStableSubject` (sha256 hex, sliced to 24 chars) so that
+ * the edge `session:<hash>` subject key matches the DB-side key used by the
+ * trust cache.
+ */
+async function hashStableSubjectEdge(value: string): Promise<string> {
+  const digest = await crypto.subtle.digest(
+    'SHA-256',
+    new TextEncoder().encode(value)
+  );
+  return Array.from(new Uint8Array(digest))
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('')
+    .slice(0, 24);
+}
+
+function parseCookieHeaderEdge(
+  cookieHeader: string | null
+): Array<{ name: string; value: string }> {
+  if (!cookieHeader) {
+    return [];
+  }
+
+  return cookieHeader
+    .split(';')
+    .map((entry) => {
+      const separatorIndex = entry.indexOf('=');
+      if (separatorIndex < 0) {
+        return null;
+      }
+
+      return {
+        name: entry.slice(0, separatorIndex).trim(),
+        value: entry.slice(separatorIndex + 1).trim(),
+      };
+    })
+    .filter(
+      (entry): entry is { name: string; value: string } =>
+        !!entry?.name && !!entry.value
+    );
+}
+
+function getSessionAuthCookie(
+  req: NextRequest
+): { name: string; value: string } | null {
+  const cookies = parseCookieHeaderEdge(req.headers.get('cookie'));
+  return (
+    cookies.find(
+      (cookie) =>
+        cookie.name === 'tuturuuu_app_session' ||
+        GENERIC_SUPABASE_AUTH_COOKIE_NAME_PATTERN.test(cookie.name)
+    ) ?? null
+  );
+}
+
+/**
+ * Mirrors `reputation.ts getCidrSubjectKey` so the edge cidr subject key matches
+ * the DB-side trusted-location key.
+ */
+function getCidrSubjectKeyEdge(ipAddress: string | null): string | null {
+  if (!ipAddress) {
+    return null;
+  }
+
+  const ipv4Parts = ipAddress.split('.');
+  if (
+    ipv4Parts.length === 4 &&
+    ipv4Parts.every((part) => /^\d{1,3}$/.test(part))
+  ) {
+    return `cidr:${ipv4Parts.slice(0, 3).join('.')}.0/24`;
+  }
+
+  const ipv6Parts = ipAddress.split(':').filter(Boolean);
+  if (ipv6Parts.length >= 4) {
+    return `cidr:${ipv6Parts.slice(0, 4).join(':')}::/64`;
+  }
+
+  return null;
+}
+
+export type ProxyIdentity = {
+  /** `ip:<ip>` subject key, or null when the IP is unknown. */
+  ipKey: string | null;
+  /** `cidr:<network>` subject key for trusted-location lookups, or null. */
+  cidrKey: string | null;
+  /** `session:<hash>` subject key for cookie sessions, or null. Matches the
+   * DB-side session subject key so trusted sessions resolve from the cache. */
+  sessionKey: string | null;
+  /** `workspace:<wsId>` subject key parsed from a workspace-scoped API path, or
+   * null. Lets an admin workspace rule uplift reads for the whole workspace. */
+  workspaceKey: string | null;
+};
+
+const WORKSPACE_PATH_PATTERN =
+  /^\/api(?:\/v1)?\/workspaces\/([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})(?:\/|$)/u;
+
+function getWorkspaceSubjectKey(pathname: string): string | null {
+  const match = WORKSPACE_PATH_PATTERN.exec(pathname);
+  return match ? `workspace:${match[1]!.toLowerCase()}` : null;
+}
+
+/**
+ * Resolves the trust/keying subject keys for a request. Limited to
+ * session/cidr/ip (keys an attacker would have to actually possess or share a
+ * network with) plus a workspace key parsed from the path — so trust uplift and
+ * per-session keying can never be granted by a forged credential.
+ */
+async function resolveProxyIdentity(
+  req: NextRequest,
+  ip: string
+): Promise<ProxyIdentity> {
+  const normalizedIp = ip && ip !== 'unknown' ? ip : null;
+  const sessionCookie = getSessionAuthCookie(req);
+  const sessionKey = sessionCookie
+    ? `session:${await hashStableSubjectEdge(`${sessionCookie.name}:${sessionCookie.value}`)}`
+    : null;
+
+  return {
+    cidrKey: getCidrSubjectKeyEdge(normalizedIp),
+    ipKey: normalizedIp ? `ip:${normalizedIp}` : null,
+    sessionKey,
+    workspaceKey: getWorkspaceSubjectKey(req.nextUrl.pathname),
+  };
+}
+
+/**
+ * Scales the read (`get`) limits of a profile by a trust multiplier. Mutation
+ * limits are left flat — those are already trust-scaled at the DB and in the
+ * downstream session/API wrappers, so scaling them here would double-apply.
+ */
+function scaleReadLimits(
+  profile: RateLimitProfile,
+  multiplier: number
+): RateLimitProfile {
+  if (multiplier <= 1) {
+    return profile;
+  }
+
+  return {
+    ...profile,
+    get: profile.get.map((config) => ({
+      ...config,
+      limit: Math.max(config.limit, Math.floor(config.limit * multiplier)),
+    })),
+  };
+}
+
+function entryReadFloor(abs: NonNullable<CachedTrustEntry['abs']>): number {
+  return abs.minute ?? abs.hour ?? abs.day ?? 0;
+}
+
+/**
+ * Combines all applicable cached entries (session + location/workspace) into a
+ * single effective read decision. Most-permissive wins: unlimited beats
+ * absolute beats the highest multiplier.
+ */
+function combineTrustEntries(
+  entries: Array<CachedTrustEntry | null | undefined>
+): CachedTrustEntry | null {
+  const active = entries.filter((entry): entry is CachedTrustEntry => !!entry);
+  if (active.length === 0) {
+    return null;
+  }
+
+  if (active.some((entry) => entry.mode === 'unlimited')) {
+    return { m: 1, mode: 'unlimited' };
+  }
+
+  const absolutes = active.filter(
+    (
+      entry
+    ): entry is CachedTrustEntry & {
+      abs: NonNullable<CachedTrustEntry['abs']>;
+    } => entry.mode === 'absolute' && !!entry.abs
+  );
+  if (absolutes.length > 0) {
+    const best = absolutes.reduce((winner, candidate) =>
+      entryReadFloor(candidate.abs) > entryReadFloor(winner.abs)
+        ? candidate
+        : winner
+    );
+    return { abs: best.abs, m: best.m, mode: 'absolute' };
+  }
+
+  return { m: Math.max(...active.map((entry) => entry.m)) };
+}
+
+/**
+ * Applies a combined trust entry to a route profile's READ limits and returns
+ * the scaled profile plus a bucket-prefix suffix that uniquely encodes the
+ * effective limit (so distinct limits never share a Redis sliding window).
+ */
+function applyTrustEntryToReads(
+  profile: RateLimitProfile,
+  entry: CachedTrustEntry | null
+): { profile: RateLimitProfile; suffix: string } {
+  if (!entry) {
+    return { profile, suffix: '' };
+  }
+
+  if (entry.mode === 'unlimited') {
+    // Drop the read cap entirely (no read limiter is constructed for [] get).
+    return { profile: { ...profile, get: [] }, suffix: ':unl' };
+  }
+
+  if (entry.mode === 'absolute' && entry.abs) {
+    const get = profile.get.map((config) => {
+      const absolute = entry.abs?.[config.window];
+      return absolute != null ? { ...config, limit: absolute } : config;
+    });
+    const { minute, hour, day } = entry.abs;
+    return {
+      profile: { ...profile, get },
+      suffix: `:abs-${minute ?? 'x'}-${hour ?? 'x'}-${day ?? 'x'}`,
+    };
+  }
+
+  const tier = quantizeTrustMultiplier(entry.m);
+  if (tier <= 1) {
+    return { profile, suffix: '' };
+  }
+  return { profile: scaleReadLimits(profile, tier), suffix: `:t${tier}` };
+}
+
 function getEffectiveRateLimits(
   routePolicy: ProxyRoutePolicy,
   callerClass: CallerClass
@@ -764,21 +1063,17 @@ function getEffectiveRateLimits(
   return routePolicy.rateLimits;
 }
 
-function shouldScopeRateLimitByPath(routePolicy: ProxyRoutePolicy): boolean {
-  return routePolicy.key === 'default' || routePolicy.key === 'users-me';
-}
-
-function getPathScopedRateLimitPrefix(
+function getRateLimitPrefix(
   prefixBase: string,
   routePolicy: ProxyRoutePolicy,
   callerClass: CallerClass,
-  pathname: string
+  trustSuffix = ''
 ): string {
-  const scopeSuffix = shouldScopeRateLimitByPath(routePolicy)
-    ? `:${pathname.replaceAll('/', ':') || ':root'}`
-    : '';
-
-  return `${prefixBase}:${routePolicy.key}:${callerClass}${scopeSuffix}`;
+  // Only trusted/uplifted traffic gets a suffixed bucket; untrusted traffic
+  // keeps the original prefix so its sliding windows are unaffected. The suffix
+  // must uniquely encode the effective limit (tier or absolute values) so two
+  // different effective limits never share a Redis sliding-window prefix.
+  return `${prefixBase}:${routePolicy.key}:${callerClass}${trustSuffix}`;
 }
 
 export function isTrustedProxyBypassRequest(
@@ -846,7 +1141,10 @@ export async function guardApiProxyRequest(
     );
   }
 
-  const routePolicies = options.routePolicies ?? DEFAULT_ROUTE_POLICIES;
+  const routePolicies = [
+    ...(options.additionalRoutePolicies ?? []),
+    ...(options.routePolicies ?? DEFAULT_ROUTE_POLICIES),
+  ];
   const trustedBypassRules = [
     ...DEFAULT_TRUSTED_BYPASS_RULES,
     ...(options.trustedBypassRules ?? []),
@@ -862,8 +1160,9 @@ export async function guardApiProxyRequest(
   ) {
     const callerClass = getCallerClass(req);
     const ip = extractIPFromRequest(req.headers);
+    const identity = await resolveProxyIdentity(req, ip);
 
-    if (ip !== 'unknown' && callerClass === 'anonymous') {
+    if (ip !== 'unknown') {
       const blockInfo = await isIPBlockedEdge(ip);
       if (blockInfo) {
         const retryAfter = Math.max(
@@ -875,15 +1174,63 @@ export async function guardApiProxyRequest(
           'X-Proxy-Block-Reason': 'ip-already-blocked',
         });
       }
+    }
+
+    const routePolicy = getRoutePolicy(req, routePolicies);
+    const isRead = req.method === 'GET' || req.method === 'HEAD';
+
+    // Resolve trust for reads only. Account trust (session key) and location
+    // trust (cidr/ip keys) are distinguished so that:
+    //   * a genuinely trusted SESSION (cache entry keyed on the real cookie's
+    //     hash — unforgeable) gets its OWN per-session bucket, so trusted
+    //     teammates behind one NAT no longer collide; and
+    //   * a trusted LOCATION (office cidr/ip) uplifts the shared per-IP bucket
+    //     for the whole team without any per-request credential.
+    // Untrusted traffic keeps legacy per-IP keying, preserving single-IP abuse
+    // caps. A forged cookie hashes to a key with no cache entry → no uplift,
+    // no per-session escape.
+    let trustEntry: CachedTrustEntry | null = null;
+    let sessionTrusted = false;
+    if (isRead && edgeTrustEnabled()) {
+      const lookupKeys = [
+        identity.sessionKey,
+        identity.cidrKey,
+        identity.ipKey,
+        identity.workspaceKey,
+      ].filter((key): key is string => key != null);
+      const entries = await getCachedTrustEntries(lookupKeys);
+
+      const sessionEntry = identity.sessionKey
+        ? entries.get(identity.sessionKey)
+        : undefined;
+      // Location/workspace trust applies to the shared per-IP bucket for the
+      // whole team; session trust applies to the per-session bucket.
+      const locationEntry = combineTrustEntries([
+        identity.cidrKey ? entries.get(identity.cidrKey) : undefined,
+        identity.ipKey ? entries.get(identity.ipKey) : undefined,
+        identity.workspaceKey ? entries.get(identity.workspaceKey) : undefined,
+      ]);
+
+      trustEntry = combineTrustEntries([sessionEntry, locationEntry]);
+      sessionTrusted = !!identity.sessionKey && !!sessionEntry;
+    }
 
-      const routePolicy = getRoutePolicy(req, routePolicies);
-      const isRead = req.method === 'GET' || req.method === 'HEAD';
-      const rateLimits = getEffectiveRateLimits(routePolicy, callerClass);
-      const limiterPrefix = getPathScopedRateLimitPrefix(
+    // Trusted sessions key per-session; everyone else keys per-IP.
+    const limiterId =
+      sessionTrusted && identity.sessionKey
+        ? identity.sessionKey
+        : identity.ipKey;
+
+    if (limiterId) {
+      const baseRateLimits = getEffectiveRateLimits(routePolicy, callerClass);
+      const { profile: rateLimits, suffix: trustSuffix } =
+        applyTrustEntryToReads(baseRateLimits, trustEntry);
+
+      const limiterPrefix = getRateLimitPrefix(
         options.prefixBase,
         routePolicy,
         callerClass,
-        req.nextUrl.pathname
+        trustSuffix
       );
       const limiterCacheKey = `${limiterPrefix}:${JSON.stringify(rateLimits)}`;
       const limiters = await getRateLimiters(limiterPrefix, rateLimits);
@@ -894,7 +1241,7 @@ export async function guardApiProxyRequest(
         let result: RateLimitResult;
 
         try {
-          result = await limiter.limit(ip);
+          result = await limiter.limit(limiterId);
         } catch {
           const fallbackLimiters = replaceWithLocalRateLimiters(
             limiterCacheKey,
@@ -912,7 +1259,7 @@ export async function guardApiProxyRequest(
             continue;
           }
 
-          result = await fallbackBucket.limiter.limit(ip);
+          result = await fallbackBucket.limiter.limit(limiterId);
         }
 
         const { success, limit, remaining, reset } = result;
@@ -921,7 +1268,7 @@ export async function guardApiProxyRequest(
           const consumed = limit - remaining;
           const kind = isRead ? 'read' : 'mutate';
           console.log(
-            `[ProxyGuard] ${routePolicy.key}:${kind}:${window} ${consumed}/${limit} | IP: ${ip} | path: ${req.nextUrl.pathname}`
+            `[ProxyGuard] ${routePolicy.key}:${kind}:${window} ${consumed}/${limit} | id: ${limiterId} | path: ${req.nextUrl.pathname}`
           );
         }
 

package/src/internal-domains.ts

@@ -370,12 +370,53 @@ function canUpgradeToRegisteredHttpsOrigin(value: URL, registeredUrl: URL) {
 }
 
 const PORTLESS_APP_HOSTS = new Set(Object.values(TUTURUUU_PORTLESS_APP_HOSTS));
+const DEFAULT_PORTLESS_PROXY_PORT = '1355';
+
+function normalizePortlessProxyPort(value: string | undefined) {
+  const trimmed = value?.trim();
+
+  if (!trimmed || !/^\d+$/u.test(trimmed)) {
+    return null;
+  }
+
+  const port = Number(trimmed);
+  return Number.isInteger(port) && port > 0 && port <= 65535
+    ? String(port)
+    : null;
+}
+
+function getPortFromUrl(value: string | undefined) {
+  if (!value?.trim()) {
+    return null;
+  }
+
+  try {
+    return normalizePortlessProxyPort(new URL(value).port);
+  } catch {
+    return null;
+  }
+}
+
+function getAllowedPortlessProxyPorts() {
+  return new Set(
+    [
+      DEFAULT_PORTLESS_PROXY_PORT,
+      normalizePortlessProxyPort(process.env.PORTLESS_PORT),
+      getPortFromUrl(process.env.PORTLESS_URL),
+    ].filter((port): port is string => Boolean(port))
+  );
+}
+
+function isAllowedPortlessProxyPort(port: string) {
+  return getAllowedPortlessProxyPorts().has(port);
+}
 
 function canUseLocalPortlessProxyPort(value: URL, registeredUrl: URL) {
   return (
     value.protocol === registeredUrl.protocol &&
     !registeredUrl.port &&
     Boolean(value.port) &&
+    isAllowedPortlessProxyPort(value.port) &&
     PORTLESS_APP_HOSTS.has(registeredUrl.hostname)
   );
 }
@@ -447,16 +488,27 @@ function matchesAppDomainUrl(value: URL, domain: AppDomain) {
 
 function canonicalizeAppDomainUrl(value: URL, domain: AppDomain) {
   const registeredUrl = parseHttpUrl(domain.url);
+  const matchesDirectPortlessProxy =
+    registeredUrl &&
+    domain.kind === 'internal' &&
+    matchesPortlessProxyOrigin(value, registeredUrl);
+  const matchesPrefixedPortlessProxy =
+    registeredUrl &&
+    domain.kind === 'internal' &&
+    matchesPrefixedPortlessOrigin(value, registeredUrl);
 
   if (
     registeredUrl &&
     domain.kind === 'internal' &&
     (canUpgradeToRegisteredHttpsOrigin(value, registeredUrl) ||
-      matchesPortlessProxyOrigin(value, registeredUrl))
+      matchesDirectPortlessProxy ||
+      matchesPrefixedPortlessProxy)
   ) {
     const canonicalUrl = new URL(value.toString());
     canonicalUrl.protocol = registeredUrl.protocol;
-    canonicalUrl.hostname = registeredUrl.hostname;
+    canonicalUrl.hostname = matchesPrefixedPortlessProxy
+      ? value.hostname
+      : registeredUrl.hostname;
     canonicalUrl.port = registeredUrl.port;
     return serializeUrl(canonicalUrl);
   }

package/src/money.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import {
+  formatMoneyFromMinor,
+  getAmountStep,
+  getCurrencyFractionDigits,
+  getMinorUnitFactor,
+  majorToMinor,
+  minorToMajor,
+  normalizeAmount,
+} from './money';
+
+describe('currency precision', () => {
+  it('knows fraction digits per currency', () => {
+    expect(getCurrencyFractionDigits('USD')).toBe(2);
+    expect(getCurrencyFractionDigits('EUR')).toBe(2);
+    expect(getCurrencyFractionDigits('JPY')).toBe(0);
+    expect(getCurrencyFractionDigits('VND')).toBe(0);
+  });
+
+  it('falls back to 2 digits for unknown currencies', () => {
+    expect(getCurrencyFractionDigits('XYZ')).toBe(2);
+  });
+
+  it('derives the minor-unit factor', () => {
+    expect(getMinorUnitFactor('USD')).toBe(100);
+    expect(getMinorUnitFactor('JPY')).toBe(1);
+    expect(getMinorUnitFactor('VND')).toBe(1);
+  });
+});
+
+describe('major <-> minor conversion', () => {
+  it('converts dollars to cents', () => {
+    expect(majorToMinor(100, 'USD')).toBe(10000);
+    expect(majorToMinor(9.99, 'USD')).toBe(999);
+  });
+
+  it('treats zero-decimal currencies 1:1', () => {
+    expect(majorToMinor(500, 'JPY')).toBe(500);
+    expect(majorToMinor(25000, 'VND')).toBe(25000);
+  });
+
+  it('round-trips cleanly', () => {
+    expect(minorToMajor(10000, 'USD')).toBe(100);
+    expect(minorToMajor(999, 'USD')).toBe(9.99);
+    expect(minorToMajor(500, 'JPY')).toBe(500);
+  });
+
+  it('rounds rather than truncating fractional minor units', () => {
+    expect(majorToMinor(1.005, 'USD')).toBe(101);
+  });
+
+  it('handles non-finite input defensively', () => {
+    expect(majorToMinor(Number.NaN, 'USD')).toBe(0);
+    expect(minorToMajor(Number.POSITIVE_INFINITY, 'USD')).toBe(0);
+  });
+});
+
+describe('normalizeAmount & getAmountStep', () => {
+  it('normalizes to currency precision', () => {
+    expect(normalizeAmount(9.999, 'USD')).toBe(10);
+    expect(normalizeAmount(9.994, 'USD')).toBe(9.99);
+    expect(normalizeAmount(500.7, 'JPY')).toBe(501);
+  });
+
+  it('returns the right input step', () => {
+    expect(getAmountStep('USD')).toBe('0.01');
+    expect(getAmountStep('JPY')).toBe('1');
+    expect(getAmountStep('VND')).toBe('1');
+  });
+});
+
+describe('formatMoneyFromMinor', () => {
+  it('formats USD cents as dollars', () => {
+    // Non-breaking space / symbol placement varies by ICU; assert the digits.
+    expect(formatMoneyFromMinor(10000, 'USD', 'en-US')).toContain('100.00');
+    expect(formatMoneyFromMinor(999, 'USD', 'en-US')).toContain('9.99');
+  });
+
+  it('formats zero-decimal currencies without scaling', () => {
+    expect(formatMoneyFromMinor(500, 'JPY', 'ja-JP')).toContain('500');
+  });
+});