@hed-hog/core 0.0.390 → 0.0.393

package/src/utils/geo-ip.spec.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+
+jest.mock('geoip-lite', () => ({
+  __esModule: true,
+  lookup: jest.fn(),
+}));
+
+import * as geoip from 'geoip-lite';
+import { isPrivateIp, lookupGeo, normalizeIp } from './geo-ip';
+
+const mockLookup = geoip.lookup as unknown as jest.Mock;
+
+const GEO_SAMPLE = {
+  range: [0, 1],
+  country: 'BR',
+  region: 'SP',
+  eu: '0',
+  timezone: 'America/Sao_Paulo',
+  city: 'Sao Paulo',
+  ll: [-23.5, -46.6],
+  metro: 0,
+  area: 10,
+};
+
+describe('normalizeIp', () => {
+  it('strips the IPv4-mapped IPv6 prefix', () => {
+    expect(normalizeIp('::ffff:189.1.2.3')).toBe('189.1.2.3');
+    expect(normalizeIp('::FFFF:189.1.2.3')).toBe('189.1.2.3');
+  });
+
+  it('strips a trailing port from IPv4 and brackets from IPv6', () => {
+    expect(normalizeIp('189.1.2.3:51000')).toBe('189.1.2.3');
+    expect(normalizeIp('[2001:db8::1]:443')).toBe('2001:db8::1');
+  });
+
+  it('keeps a bare IPv6 untouched and returns null for empty input', () => {
+    expect(normalizeIp('2001:db8::1')).toBe('2001:db8::1');
+    expect(normalizeIp('')).toBeNull();
+    expect(normalizeIp('   ')).toBeNull();
+    expect(normalizeIp(null)).toBeNull();
+    expect(normalizeIp(undefined)).toBeNull();
+  });
+});
+
+describe('isPrivateIp', () => {
+  it.each([
+    ['10.244.1.7'],
+    ['10.0.0.1'],
+    ['127.0.0.1'],
+    ['192.168.1.1'],
+    ['169.254.1.1'],
+    ['172.16.0.1'],
+    ['172.31.255.254'],
+    ['100.64.0.1'],
+    ['100.127.255.255'],
+    ['0.0.0.0'],
+    ['::1'],
+    ['::'],
+    ['fd00::1'],
+    ['fe80::1'],
+    ['unknown'],
+    [''],
+  ])('treats %s as private', (ip) => {
+    expect(isPrivateIp(ip)).toBe(true);
+  });
+
+  it.each([
+    ['8.8.8.8'],
+    ['189.1.2.3'],
+    // Only 172.16.0.0/12 is private: everything outside 16-31 is public.
+    ['172.15.0.1'],
+    ['172.32.0.1'],
+    ['100.63.255.255'],
+    ['100.128.0.1'],
+    ['2001:db8::1'],
+  ])('treats %s as public', (ip) => {
+    expect(isPrivateIp(ip)).toBe(false);
+  });
+
+  it('normalizes before deciding', () => {
+    expect(isPrivateIp('::ffff:10.244.1.7')).toBe(true);
+    expect(isPrivateIp('::ffff:8.8.8.8')).toBe(false);
+  });
+});
+
+describe('lookupGeo', () => {
+  beforeEach(() => {
+    mockLookup.mockReset();
+  });
+
+  it('never queries the database for a private address', () => {
+    expect(lookupGeo('10.244.1.7')).toBeNull();
+    expect(lookupGeo('172.20.0.1')).toBeNull();
+    expect(lookupGeo(null)).toBeNull();
+    expect(mockLookup).not.toHaveBeenCalled();
+  });
+
+  it('queries 172.32.0.1, which is public despite the 172 prefix', () => {
+    mockLookup.mockReturnValue(null);
+    lookupGeo('172.32.0.1');
+    expect(mockLookup).toHaveBeenCalledWith('172.32.0.1');
+  });
+
+  it('normalizes the address before the lookup', () => {
+    mockLookup.mockReturnValue(GEO_SAMPLE);
+    lookupGeo('::ffff:189.1.2.3');
+    expect(mockLookup).toHaveBeenCalledWith('189.1.2.3');
+  });
+
+  it('maps the four fields', () => {
+    mockLookup.mockReturnValue(GEO_SAMPLE);
+    expect(lookupGeo('189.1.2.3')).toEqual({
+      country: 'BR',
+      region: 'SP',
+      city: 'Sao Paulo',
+      timezone: 'America/Sao_Paulo',
+    });
+  });
+
+  it('turns missing fields into null instead of undefined', () => {
+    mockLookup.mockReturnValue({ ...GEO_SAMPLE, region: '', city: '', timezone: undefined });
+    expect(lookupGeo('189.1.2.3')).toEqual({
+      country: 'BR',
+      region: null,
+      city: null,
+      timezone: null,
+    });
+  });
+
+  it('returns null when the database has no entry', () => {
+    mockLookup.mockReturnValue(null);
+    expect(lookupGeo('8.8.8.8')).toBeNull();
+  });
+});

package/src/utils/geo-ip.ts

@@ -0,0 +1,93 @@
+import * as geoip from 'geoip-lite';
+
+export interface GeoLocation {
+  /** ISO 3166-1 alpha-2, e.g. 'BR'. */
+  country: string | null;
+  /** Subdivision code, e.g. 'SP'. */
+  region: string | null;
+  city: string | null;
+  /** IANA timezone, e.g. 'America/Sao_Paulo'. */
+  timezone: string | null;
+}
+
+/**
+ * Strips the IPv4-mapped IPv6 prefix and any trailing port, and unwraps the
+ * bracket notation used for IPv6 hosts.
+ *
+ * Without this, `::ffff:189.1.2.3` — what a dual-stack socket reports — is
+ * looked up in the IPv6 database and always misses.
+ */
+export function normalizeIp(ip?: string | null): string | null {
+  const raw = (ip ?? '').trim();
+  if (!raw) return null;
+
+  // `[2001:db8::1]:443` -> `2001:db8::1`
+  const bracketed = raw.match(/^\[(.+)\](?::\d+)?$/);
+  const value = bracketed ? bracketed[1] : raw;
+
+  const unmapped = value.replace(/^::ffff:/i, '');
+
+  // `189.1.2.3:51000` -> `189.1.2.3` (only for IPv4; a bare IPv6 has many colons)
+  const withoutPort = unmapped.match(/^(\d{1,3}(?:\.\d{1,3}){3}):\d+$/);
+
+  return (withoutPort ? withoutPort[1] : unmapped) || null;
+}
+
+/**
+ * Loopback, private, link-local and CGNAT ranges — plus the placeholders the
+ * callers use when they could not resolve anything.
+ *
+ * The cluster pod CIDR (10.244.x.x) falls here, which is exactly what every
+ * ticket created before the client IP started being forwarded has stored.
+ *
+ * Careful with 172: only 172.16.0.0/12 is private, so the second octet has to
+ * be between 16 and 31. Blocking the whole `172.` prefix — as the copy in
+ * lms/platforma/handlers/lesson-heartbeat.handler.ts does — silently discards
+ * public addresses such as 172.32.5.9.
+ */
+export function isPrivateIp(ip?: string | null): boolean {
+  const value = normalizeIp(ip);
+  if (!value) return true;
+
+  const lower = value.toLowerCase();
+  if (lower === 'unknown' || lower === '::' || lower === '0.0.0.0') return true;
+
+  // IPv6: loopback, unique local (fc00::/7) and link-local (fe80::/10).
+  if (lower === '::1') return true;
+  if (/^f[cd]/.test(lower) && lower.includes(':')) return true;
+  if (/^fe[89ab]/.test(lower) && lower.includes(':')) return true;
+
+  const v4 = lower.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+  if (!v4) return false;
+
+  const [a, b] = [Number(v4[1]), Number(v4[2])];
+  if (a === 0 || a === 10 || a === 127) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 169 && b === 254) return true;
+  // CGNAT 100.64.0.0/10
+  if (a === 100 && b >= 64 && b <= 127) return true;
+
+  return false;
+}
+
+/**
+ * Offline lookup against the MaxMind-lite database bundled with geoip-lite.
+ *
+ * Returns null for empty, private or unknown addresses — never an invented
+ * country, which is what makes it safe to render the result directly.
+ */
+export function lookupGeo(ip?: string | null): GeoLocation | null {
+  const value = normalizeIp(ip);
+  if (!value || isPrivateIp(value)) return null;
+
+  const geo = geoip.lookup(value);
+  if (!geo) return null;
+
+  return {
+    country: geo.country || null,
+    region: geo.region || null,
+    city: geo.city || null,
+    timezone: geo.timezone || null,
+  };
+}

package/src/utils/locale-context.spec.ts

@@ -1,5 +1,9 @@
 import { describe, it, expect } from '@jest/globals';
-import { getLocaleFromContext, localeStorage } from './locale-context';
+import {
+  getLocaleFromContext,
+  isLocaleDetectedFromContext,
+  localeStorage,
+} from './locale-context';
 
 describe('locale-context', () => {
   it('retorna "en" quando não há contexto', () => {
@@ -19,4 +23,26 @@ describe('locale-context', () => {
     );
     expect(result).toBe('en');
   });
+
+  // A guarda que impede gravar o default do middleware como se fosse escolha
+  // do usuario. Sem ela, todo cliente sem `Accept-Language` congelaria `en`.
+  describe('isLocaleDetectedFromContext', () => {
+    it('é falso fora de qualquer contexto', () => {
+      expect(isLocaleDetectedFromContext()).toBe(false);
+    });
+
+    it('é falso quando o locale é apenas o default do middleware', () => {
+      const result = localeStorage.run({ locale: 'en', detected: false }, () =>
+        isLocaleDetectedFromContext(),
+      );
+      expect(result).toBe(false);
+    });
+
+    it('é verdadeiro quando o cliente declarou um idioma suportado', () => {
+      const result = localeStorage.run({ locale: 'pt', detected: true }, () =>
+        isLocaleDetectedFromContext(),
+      );
+      expect(result).toBe(true);
+    });
+  });
 });

package/src/utils/locale-context.ts

@@ -1,12 +1,15 @@
-import { AsyncLocalStorage } from 'async_hooks';
-
-interface LocaleContext {
-  locale: string;
-}
-
-export const localeStorage = new AsyncLocalStorage<LocaleContext>();
-
-export function getLocaleFromContext(): string {
-  const context = localeStorage.getStore();
-  return context?.locale || 'en';
-}
+/**
+ * O contexto de locale mora em `@hed-hog/api-locale`, junto do middleware que o
+ * popula. Este arquivo continua existindo como reexport porque `@hed-hog/core`
+ * e a fachada que as outras libraries importam (`operations`, validators).
+ *
+ * Manter uma copia do `AsyncLocalStorage` aqui criaria DOIS storages: o
+ * middleware escreveria num e `getLocaleFromContext()` leria o outro, sempre
+ * vazio.
+ */
+export {
+  getLocaleFromContext,
+  isLocaleDetectedFromContext,
+  localeStorage,
+  type LocaleContext,
+} from '@hed-hog/api-locale';

package/src/utils/security-event-vars.spec.ts

@@ -0,0 +1,161 @@
+import { describe, it, expect, jest, beforeEach } from '@jest/globals';
+
+jest.mock('geoip-lite', () => ({
+  __esModule: true,
+  lookup: jest.fn(),
+}));
+
+import * as geoip from 'geoip-lite';
+import {
+  buildSecurityEventVars,
+  countryFlagEmoji,
+  formatEventDateTime,
+} from './security-event-vars';
+
+const mockLookup = geoip.lookup as unknown as jest.Mock;
+
+const GEO_SAMPLE = {
+  range: [0, 1],
+  country: 'BR',
+  region: 'SP',
+  eu: '0',
+  timezone: 'America/Sao_Paulo',
+  city: 'Sao Paulo',
+  ll: [-23.5, -46.6],
+  metro: 0,
+  area: 10,
+};
+
+const CHROME_UA =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36';
+
+const AT = new Date('2026-08-08T15:04:00.000Z');
+
+describe('countryFlagEmoji', () => {
+  it('monta o par de regional indicators', () => {
+    expect(countryFlagEmoji('BR')).toBe('\u{1F1E7}\u{1F1F7}');
+    expect(countryFlagEmoji('US')).toBe('\u{1F1FA}\u{1F1F8}');
+  });
+
+  it('aceita minúsculas e espaços', () => {
+    expect(countryFlagEmoji(' br ')).toBe('\u{1F1E7}\u{1F1F7}');
+  });
+
+  it('devolve string vazia para qualquer coisa que não seja um ISO2', () => {
+    expect(countryFlagEmoji('BRA')).toBe('');
+    expect(countryFlagEmoji('B')).toBe('');
+    expect(countryFlagEmoji('12')).toBe('');
+    expect(countryFlagEmoji('')).toBe('');
+    expect(countryFlagEmoji(null)).toBe('');
+    expect(countryFlagEmoji(undefined)).toBe('');
+  });
+});
+
+describe('formatEventDateTime', () => {
+  it('formata no fuso informado', () => {
+    // 15:04 UTC = 12:04 em America/Sao_Paulo.
+    expect(formatEventDateTime(AT, 'pt', 'America/Sao_Paulo')).toContain('12:04');
+  });
+
+  it('cai para America/Sao_Paulo sem fuso', () => {
+    expect(formatEventDateTime(AT, 'pt', null)).toBe(
+      formatEventDateTime(AT, 'pt', 'America/Sao_Paulo'),
+    );
+  });
+
+  it('não lança com locale ou fuso inválidos, que vêm de fora', () => {
+    expect(() => formatEventDateTime(AT, 'pt_BR!!', 'Nao/Existe')).not.toThrow();
+    expect(formatEventDateTime(AT, 'pt_BR!!', 'Nao/Existe')).toEqual(expect.any(String));
+  });
+});
+
+describe('buildSecurityEventVars', () => {
+  beforeEach(() => {
+    mockLookup.mockReset();
+  });
+
+  it('traduz IP e User-Agent nos campos do cartão', () => {
+    mockLookup.mockReturnValue(GEO_SAMPLE);
+
+    const vars = buildSecurityEventVars({
+      ipAddress: '189.1.2.3',
+      userAgent: CHROME_UA,
+      locale: 'pt',
+      at: AT,
+    });
+
+    expect(vars).toMatchObject({
+      ipAddress: '189.1.2.3',
+      userAgent: CHROME_UA,
+      browser: 'Chrome 151',
+      os: 'Windows 10',
+      location: 'Sao Paulo, Brasil',
+      countryFlag: '\u{1F1E7}\u{1F1F7}',
+    });
+    expect(vars.datetime).toContain('12:04');
+  });
+
+  it('localiza o nome do país pelo locale', () => {
+    mockLookup.mockReturnValue(GEO_SAMPLE);
+
+    expect(
+      buildSecurityEventVars({ ipAddress: '189.1.2.3', locale: 'en', at: AT }).location,
+    ).toBe('Sao Paulo, Brazil');
+  });
+
+  it('corta a versão do navegador no major', () => {
+    mockLookup.mockReturnValue(null);
+
+    expect(
+      buildSecurityEventVars({ ipAddress: '189.1.2.3', userAgent: CHROME_UA, at: AT }).browser,
+    ).toBe('Chrome 151');
+  });
+
+  it('devolve string vazia — nunca "Unknown" — para IP privado', () => {
+    const vars = buildSecurityEventVars({
+      ipAddress: '10.244.1.7',
+      userAgent: CHROME_UA,
+      locale: 'pt',
+      at: AT,
+    });
+
+    expect(mockLookup).not.toHaveBeenCalled();
+    expect(vars.location).toBe('');
+    expect(vars.countryFlag).toBe('');
+    // Sem geo o fuso cai no padrão, mas a data continua preenchida.
+    expect(vars.datetime).toEqual(expect.any(String));
+  });
+
+  it('zera browser e os quando o User-Agent não identifica nada', () => {
+    mockLookup.mockReturnValue(null);
+
+    const vars = buildSecurityEventVars({
+      ipAddress: '189.1.2.3',
+      userAgent: 'curl/8.4.0',
+      at: AT,
+    });
+
+    // O template usa {{#unless browser}}{{#unless os}} para cair no UA cru.
+    expect(vars.browser).toBe('');
+    expect(vars.os).toBe('');
+    expect(vars.userAgent).toBe('curl/8.4.0');
+  });
+
+  it('não devolve null em campo nenhum, mesmo sem entrada alguma', () => {
+    const vars = buildSecurityEventVars({ at: AT });
+
+    for (const [key, value] of Object.entries(vars)) {
+      expect(typeof value).toBe('string');
+      expect(value).not.toBeNull();
+      if (key !== 'datetime') expect(value).toBe('');
+    }
+  });
+
+  it('usa o fuso do geoip para o horário', () => {
+    mockLookup.mockReturnValue({ ...GEO_SAMPLE, timezone: 'UTC' });
+
+    expect(
+      buildSecurityEventVars({ ipAddress: '189.1.2.3', locale: 'pt', at: AT }).datetime,
+    ).toContain('15:04');
+  });
+});

package/src/utils/security-event-vars.ts

@@ -0,0 +1,153 @@
+import { lookupGeo } from './geo-ip';
+import { parseUserAgent } from './user-agent';
+
+/**
+ * Fuso usado quando o geoip nao resolve (IP privado, base sem entrada). Sem
+ * ele o horario sairia em UTC, que e o pior dos mundos num alerta de seguranca:
+ * parece certo e esta tres horas errado.
+ */
+const DEFAULT_TIME_ZONE = 'America/Sao_Paulo';
+
+export interface SecurityEventContext {
+  ipAddress?: string | null;
+  userAgent?: string | null;
+  /** Codigo da tabela `locale` ('pt' | 'en' | 'es'), como chega do LocaleMiddleware. */
+  locale?: string | null;
+  /** Momento do evento. Default: agora. */
+  at?: Date;
+  /** Fuso quando o geoip nao resolve. Default: DEFAULT_TIME_ZONE. */
+  fallbackTimeZone?: string;
+}
+
+/**
+ * Variaveis prontas para os templates de e-mail de seguranca
+ * (`auth-login-new-device`, `auth-change-password-notification`).
+ *
+ * Todo campo e string, nunca null: `sendTemplatedMail` recebe um
+ * Record<string, string> e os templates usam `{{#if}}` para esconder a linha
+ * do cartao — string vazia e o que faz a linha sumir.
+ */
+export interface SecurityEventVars {
+  ipAddress: string;
+  /** UA cru; o template so imprime quando nao conseguiu identificar navegador nem SO. */
+  userAgent: string;
+  /** "Chrome 151" */
+  browser: string;
+  /** "Windows 10" */
+  os: string;
+  /** "Sao Paulo, Brasil" */
+  location: string;
+  /** "🇧🇷" */
+  countryFlag: string;
+  /** "8 de agosto de 2026 as 12:04" */
+  datetime: string;
+}
+
+/**
+ * Par de regional indicators para um ISO 3166-1 alpha-2.
+ *
+ * Mesma conta do countryFlag() em apps/admin/src/components/browser-os-icon.tsx,
+ * reimplementada aqui porque aquele arquivo e 'use client' e vive no app.
+ *
+ * Emoji e a unica forma de bandeira que renderiza nos tres clientes que
+ * importam: o Gmail remove <svg> inline e bloqueia data: URI, e o Outlook
+ * desktop nao renderiza SVG de jeito nenhum.
+ */
+export function countryFlagEmoji(code?: string | null): string {
+  const value = (code ?? '').trim().toUpperCase();
+  if (!/^[A-Z]{2}$/.test(value)) return '';
+
+  return [...value]
+    .map((c) => String.fromCodePoint(0x1f1e6 + c.charCodeAt(0) - 65))
+    .join('');
+}
+
+/**
+ * `Intl` lanca RangeError com tag malformada, e a tag vem da tabela `locale`,
+ * que nao tem allowlist. Valida uma vez aqui em vez de espalhar try/catch.
+ */
+function safeLocale(locale?: string | null): string {
+  const value = (locale ?? '').trim();
+  if (!value) return 'en';
+
+  try {
+    new Intl.DateTimeFormat(value);
+    return value;
+  } catch {
+    return 'en';
+  }
+}
+
+/** Idem para o fuso, que vem da base do geoip-lite. */
+function safeTimeZone(timeZone?: string | null): string {
+  const value = (timeZone ?? '').trim();
+  if (!value) return DEFAULT_TIME_ZONE;
+
+  try {
+    new Intl.DateTimeFormat('en', { timeZone: value });
+    return value;
+  } catch {
+    return DEFAULT_TIME_ZONE;
+  }
+}
+
+function countryName(code: string, locale: string): string {
+  try {
+    return new Intl.DisplayNames([locale], { type: 'region' }).of(code) ?? code;
+  } catch {
+    // Fica o ISO2, que ja e legivel o bastante para o destinatario.
+    return code;
+  }
+}
+
+export function formatEventDateTime(
+  at: Date,
+  locale?: string | null,
+  timeZone?: string | null,
+): string {
+  return new Intl.DateTimeFormat(safeLocale(locale), {
+    dateStyle: 'long',
+    timeStyle: 'short',
+    timeZone: safeTimeZone(timeZone),
+  }).format(at);
+}
+
+/**
+ * Traduz IP + User-Agent crus nas variaveis que o template de seguranca
+ * imprime, resolvendo geolocalizacao e navegador/SO pelos utilitarios que o
+ * access-log ja usa.
+ *
+ * O que nao foi possivel resolver volta como string vazia, e nao como um
+ * "Unknown" literal: o template esconde a linha inteira em vez de anunciar
+ * que o sistema nao sabe.
+ */
+export function buildSecurityEventVars(
+  ctx: SecurityEventContext,
+): SecurityEventVars {
+  const at = ctx.at ?? new Date();
+  const locale = safeLocale(ctx.locale);
+  const geo = lookupGeo(ctx.ipAddress);
+  const ua = parseUserAgent(ctx.userAgent);
+
+  const country = geo?.country ? countryName(geo.country, locale) : '';
+  // `region` fica de fora: o geoip devolve o codigo curto ('SP'), que nao
+  // localiza e so polui a linha.
+  const location = [geo?.city, country].filter(Boolean).join(', ');
+
+  // So o major: "151" em vez de "151.0.0.0".
+  const browserVersion = (ua?.browser_version ?? '').split('.')[0];
+
+  return {
+    ipAddress: (ctx.ipAddress ?? '').trim(),
+    userAgent: (ctx.userAgent ?? '').trim(),
+    browser: [ua?.browser_name, browserVersion].filter(Boolean).join(' '),
+    os: [ua?.os_name, ua?.os_version].filter(Boolean).join(' '),
+    location,
+    countryFlag: countryFlagEmoji(geo?.country),
+    datetime: formatEventDateTime(
+      at,
+      locale,
+      geo?.timezone ?? ctx.fallbackTimeZone,
+    ),
+  };
+}

package/src/utils/user-agent.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from '@jest/globals';
+
+import { parseUserAgent } from './user-agent';
+
+const CHROME_WINDOWS =
+  'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36';
+
+const SAFARI_IOS =
+  'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1';
+
+describe('parseUserAgent', () => {
+  it('parses a desktop Chrome on Windows', () => {
+    const result = parseUserAgent(CHROME_WINDOWS);
+    expect(result?.browser_name).toBe('Chrome');
+    expect(result?.browser_version).toMatch(/^131\./);
+    expect(result?.os_name).toBe('Windows');
+  });
+
+  it('parses mobile Safari on iOS', () => {
+    const result = parseUserAgent(SAFARI_IOS);
+    expect(result?.browser_name).toMatch(/Safari/);
+    expect(result?.os_name).toBe('iOS');
+  });
+
+  it('returns null for empty input', () => {
+    expect(parseUserAgent(null)).toBeNull();
+    expect(parseUserAgent(undefined)).toBeNull();
+    expect(parseUserAgent('')).toBeNull();
+    expect(parseUserAgent('   ')).toBeNull();
+  });
+
+  it('returns null when neither the browser nor the OS is identifiable', () => {
+    // What the API used to store while the site called it through a
+    // server-side fetch, with no browser involved.
+    expect(parseUserAgent('node')).toBeNull();
+  });
+});

package/src/utils/user-agent.ts

@@ -0,0 +1,46 @@
+import { UAParser } from 'ua-parser-js';
+
+export interface UserAgentInfo {
+  browser_name: string | null;
+  browser_version: string | null;
+  os_name: string | null;
+  os_version: string | null;
+  /** `mobile` | `tablet` | `desktop`. */
+  device_type: string | null;
+}
+
+/**
+ * Parses a raw User-Agent into the same four fields the access log already
+ * exposes, so the admin's BrowserIcon/OsIcon components match by name without
+ * any translation layer.
+ *
+ * Returns null when there is nothing to parse or when neither the browser nor
+ * the OS could be identified — the caller then skips the row entirely instead
+ * of rendering a line full of dashes.
+ */
+export function parseUserAgent(userAgent?: string | null): UserAgentInfo | null {
+  const value = (userAgent ?? '').trim();
+  if (!value) return null;
+
+  const result = new UAParser(value).getResult();
+
+  const browserName = result.browser?.name ?? null;
+  const osName = result.os?.name ?? null;
+
+  // O ua-parser não devolve `device.type` para desktop — a ausência É o desktop.
+  // Mas isso só vale quando ele reconheceu *algo*: assumir "desktop" diante de
+  // um User-Agent que não identificou nada é o que fazia um app de celular
+  // aparecer como computador.
+  const deviceType =
+    result.device?.type ?? (browserName || osName ? 'desktop' : null);
+
+  const info: UserAgentInfo = {
+    browser_name: browserName,
+    browser_version: result.browser?.version ?? null,
+    os_name: osName,
+    os_version: result.os?.version ?? null,
+    device_type: deviceType,
+  };
+
+  return info.browser_name || info.os_name ? info : null;
+}