@seedgrid/fe-security 2026.7.0 → 2026.7.1

package/dist/session-result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-result.d.ts","sourceRoot":"","sources":["../src/session-result.ts"],"names":[],"mappings":"AAIA,+EAA+E;AAC/E,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzD,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,CAAC,CAAA;CAAE,GACrB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,aAAa,CAAA;CAAE,CAAC;AAE1C,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CASjE"}

package/dist/session-result.js

@@ -0,0 +1,14 @@
+// Resultado de Server Action — client-safe. A action NÃO lança (o Next redige a
+// mensagem de erro em produção): ela RETORNA este result, que serializa com segurança
+// e carrega o problem+json do backend intacto até a UI.
+/** Lê a mensagem exibível de um ProblemDetail (detail → 1ª violação → title → status). */
+export function readProblemMessage(problem) {
+    if (problem.detail) {
+        return problem.detail;
+    }
+    const firstViolation = problem.violations?.find((v) => v.message)?.message;
+    if (firstViolation) {
+        return firstViolation;
+    }
+    return problem.title ?? `Erro ${problem.status}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seedgrid/fe-security",
-  "version": "2026.7.0",
+  "version": "2026.7.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,14 +16,49 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "default": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "default": "./dist/client/index.js"
+    },
+    "./paths": {
+      "types": "./dist/paths.d.ts",
+      "default": "./dist/paths.js"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "scaffold"
   ],
+  "peerDependencies": {
+    "@seedgrid/fe-components": "*",
+    "@seedgrid/fe-core": "*",
+    "next": ">=14",
+    "react": "^18.2.0 || ^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "next": "15.0.7",
+    "react": "19.0.0",
+    "@types/react": "^19.0.0",
+    "@seedgrid/fe-components": "2026.7.1",
+    "@seedgrid/fe-core": "2026.7.1"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "postbuild": "node scripts/emit-module-manifest.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "pnpm run build && node --test tests/paths.test.mjs"
+    "test": "pnpm run build && node --test tests/paths.test.mjs tests/module-manifest.test.mjs tests/permissions.test.mjs"
   }
 }

package/scaffold/README.md

@@ -0,0 +1,97 @@
+# `fe-security` scaffold
+
+Conteúdo copiado para dentro do app gerado pelo CLI (git do app, editável à
+vontade — ver `seedgrid-cli/docs/adr/0004-module-manifest-contract.md`).
+Extraído de `seedgrid-cli/templates/modules/security/`.
+
+## Critério lib vs scaffold usado nesta extração
+
+Regra objetiva aplicada arquivo a arquivo: **qualquer import de um alias
+`@/...`** (`@/config/*`, `@/i18n`, `@/theme`, `@/modules/core`,
+`@/components/layout/*`) **só resolve dentro do app gerado** — um pacote npm
+publicado não tem acesso a esses aliases. Então:
+
+- **Sem nenhum import `@/...`** → candidato a lib (`src/` do pacote).
+- **Com import `@/...` usado só como valor default trivial** (ex.:
+  `delayMs = securityConfig.search.debounceMs`) → decoupar (virar parâmetro
+  com default literal) e promover.
+- **Com import `@/...` usado em fluxo de controle/rota concreta** (redirects,
+  comparação de pathname, `securityConfig.apiBaseUrl` pra chamar a própria
+  rota-proxy do app) → fica scaffold. Não vale a pena forçar injeção de config
+  pra tudo nesta passada — fica como follow-up se algum dia fizer falta.
+
+`@/modules/core` é caso à parte: é só um shim local que reexporta
+`@seedgrid/fe-core` (não é acoplamento de verdade). Ao promover um arquivo pra
+lib, trocar `@/modules/core` por `@seedgrid/fe-core` direto.
+
+## O que foi promovido pra `@seedgrid/fe-security` (lib)
+
+- `permissions.ts` (`normalizePermission`, `hasPermission`, `hasAnyPermission`,
+  `hasAllPermissions`, `buildCrudPermissions`, `createPermissionSet`) — puro,
+  zero import `@/...`.
+- `messages.ts` (`securityMessages`) — puro, 5 locales, zero import `@/...`.
+- `components/StatusBadge.tsx`, `components/PickListField.tsx` — puros
+  (`PickListOption` também promovido, foi pra `dtos.ts` do pacote).
+
+## O que ficou scaffold (e por quê)
+
+- `AuthProvider.tsx`, `components/RouteGuard.tsx`, `navigation.ts` — fluxo de
+  redirect hardcoda rotas concretas (`securityConfig.routes.login` etc.).
+- `config.ts` — `securityConfig.routes`/`pagination` são a própria estrutura
+  de rotas do app; muda se o app mover uma tela de lugar.
+- `services/security-api.ts`, `services/security-service.ts`,
+  `services/auth-service.ts` — a camada de fetch client-side chama a própria
+  rota-proxy do app (`securityConfig.apiBaseUrl`) e (no caso de
+  `security-api.ts`) usa `@/i18n` pra 1 mensagem de fallback. Dava pra
+  decopiar com injeção de config, mas não foi feito nesta passada — ver
+  "Follow-ups" abaixo.
+- `components/PageFrame.tsx` (+`InlineNotice`) — usa `@/theme`
+  (`useSgTheme`), que é implementação própria do base-app, sem equivalente
+  npm hoje.
+- `components/AppShell.tsx`, `components/SecurityDashboard.tsx`,
+  `useSecurityAppShellSections.tsx` — acopladas a `@/i18n` +
+  `@/components/layout/*` e têm menu/rotas concretas. Estes 3 mantiveram
+  `.hbs` (têm `{{...}}` de verdade — condicionais por config do projeto,
+  ex. `security_api_keys_enabled`); os demais viraram `.ts`/`.tsx` puro (não
+  tinham templating real, só texto que por acaso teria a mesma extensão).
+- `hooks/useAuth.ts`, `hooks/usePermission.ts`,
+  `components/CompanyManagementGuard.tsx`, `host-access.ts`, `types.ts`,
+  `utils.ts` — dependem, direta ou indiretamente, de algo acima que ficou
+  scaffold (ex.: `useAuth` depende do `AuthProvider` scaffold).
+
+`index.ts` (barrel local do scaffold) mistura os dois: reexporta os itens
+promovidos direto de `@seedgrid/fe-security`/`@seedgrid/fe-security/client`, e
+mantém os demais como arquivo local — igual a como um app gerado hoje já
+usa esse barrel, só com a origem de alguns exports trocada.
+
+## Motor de sessão unificado (o "dois motores" foi resolvido em parte)
+
+Havia dois motores de **fetch autenticado** paralelos: o `server/server-api.ts`
+(`createServerApiClient`, scaffold) e o `createSecurityServer` da lib
+(`src/server/`, usado por todos os módulos compostos — billing/tenancy/backup).
+O único consumidor do antigo era o proxy de avatar.
+
+**Resolvido**: `server/server-api.ts` foi REMOVIDO. O avatar agora usa
+`server/session-server.ts` (`getSecuritySessionServer()` → `createSecurityServer`
+com a config de cookie do app) e `fetchWithSession()` — o MESMO motor do resto
+do app. Um motor de fetch autenticado só.
+
+**Deixado de propósito**: `server/session-routes.ts` (rotas públicas de
+login/2fa/refresh/logout em `app/api/security/session/**`) NÃO foi migrado.
+Ele não é um motor duplicado — é o **estabelecimento** de sessão (fluxos
+públicos que criam os cookies), enquanto o `createSecurityServer` é o consumo
+autenticado depois. Migrá-lo mexeria em semântica sutil de cookie (o antigo
+seta `maxAge` do refresh = 30d configurável; o `applySessionCookies` do motor
+novo grava cookie de sessão sem `maxAge`) e no dedup de refresh concorrente
+(`Map`), no caminho MAIS crítico (login) e SEM testes de runtime pra pegar
+regressão. Fica como follow-up com essa ressalva explícita.
+
+## Follow-ups (fora do escopo desta extração)
+
+- Promover `security-api.ts`/`security-service.ts`/`auth-service.ts` pra lib
+  exigiria injeção de config (ex.: aceitar um `createApiClient` já configurado
+  em vez de montar um com `securityConfig.apiBaseUrl` fixo). Ganho real (essa
+  é a camada de maior volume de código), mas é redesenho deliberado, não
+  mecânico — não fazer de afogadilho.
+- `AuthProvider`/`RouteGuard` também dava pra promover injetando as rotas via
+  props/config em vez de importar `securityConfig` direto. Mesma ressalva.

package/scaffold/src/app/api/security/session/2fa/resend/route.ts

@@ -0,0 +1,8 @@
+import { NextRequest } from "next/server";
+
+import { createResendTwoFactorRouteResponse } from "@/modules/security/server/session-routes";
+
+export async function POST(request: NextRequest) {
+  return createResendTwoFactorRouteResponse(request);
+}
+

package/scaffold/src/app/api/security/session/2fa/verify/route.ts

@@ -0,0 +1,8 @@
+import { NextRequest } from "next/server";
+
+import { createVerifyTwoFactorRouteResponse } from "@/modules/security/server/session-routes";
+
+export async function POST(request: NextRequest) {
+  return createVerifyTwoFactorRouteResponse(request);
+}
+

package/scaffold/src/app/api/security/session/login/route.ts

@@ -0,0 +1,7 @@
+import { NextRequest } from "next/server";
+
+import { createLoginRouteResponse } from "@/modules/security/server/session-routes";
+
+export async function POST(request: NextRequest) {
+  return createLoginRouteResponse(request);
+}

package/scaffold/src/app/api/security/session/logout/route.ts

@@ -0,0 +1,5 @@
+import { createLogoutRouteResponse } from "@/modules/security/server/session-routes";
+
+export async function POST() {
+  return createLogoutRouteResponse();
+}

package/scaffold/src/app/api/security/session/refresh/route.ts

@@ -0,0 +1,7 @@
+import { NextRequest } from "next/server";
+
+import { createRefreshRouteResponse } from "@/modules/security/server/session-routes";
+
+export async function POST(request: NextRequest) {
+  return createRefreshRouteResponse(request);
+}

package/scaffold/src/app/api/security/users/[publicId]/avatar/route.ts

@@ -0,0 +1,15 @@
+import { NextRequest } from "next/server";
+
+import { createUserAvatarRouteResponse } from "@/modules/security/server/avatar-routes";
+
+export async function GET(
+  request: NextRequest,
+  context: { params: Promise<{ publicId: string }> }
+) {
+  const params = await context.params;
+
+  return createUserAvatarRouteResponse(
+    params.publicId,
+    request.nextUrl.searchParams.get("v")
+  );
+}

package/scaffold/src/app/auth/2fa/verify/page.tsx

@@ -0,0 +1,286 @@
+"use client";
+
+import type { InputHTMLAttributes } from "react";
+import { useRef, useState } from "react";
+
+import {
+  SgButton,
+  SgCard,
+  SgInputOTP,
+  SgPanel,
+  SgStack,
+  SgWhistleHost,
+  sgWhistle,
+} from "@seedgrid/fe-components";
+import { useRouter } from "next/navigation";
+import {
+  type Control,
+  type FieldErrors,
+  type FieldValues,
+  type RegisterOptions,
+  useForm,
+} from "react-hook-form";
+
+import { useI18n } from "@/i18n";
+import { useSgTheme } from "@/theme";
+import {
+  InlineNotice,
+  extractApiMessage,
+  resolvePostAuthPath,
+  securityConfig,
+  useAuth,
+} from "@/modules/security";
+import { authService } from "@/modules/security/services/auth-service";
+import { readStoredSession } from "@/modules/security/services/session-storage";
+
+type TwoFactorVerifyFormValues = {
+  code: string;
+};
+
+const TWO_FACTOR_CODE_LENGTH = 6;
+
+export default function TwoFactorVerifyPage() {
+  const router = useRouter();
+  const { t } = useI18n();
+  const translate = t as unknown as (
+    key: string,
+    values?: Record<string, unknown>
+  ) => string;
+  const { currentMode } = useSgTheme();
+  const isDarkMode = currentMode === "dark";
+  const auth = useAuth();
+  const [pending, setPending] = useState(false);
+  const [resending, setResending] = useState(false);
+  const lastSubmittedCodeRef = useRef<string | null>(null);
+  const pendingMethod = auth.pendingTwoFactor?.method?.trim().toUpperCase() ?? "";
+  const canResendEmail = pendingMethod === "EMAIL";
+  const { control, handleSubmit, reset, setValue } =
+    useForm<TwoFactorVerifyFormValues>({
+      defaultValues: {
+        code: "",
+      },
+    });
+  const codeRules = {
+    required: translate("security.auth.two_factor.validation.code_required"),
+  };
+  const otpControl = control as unknown as Control<FieldValues>;
+  const otpRules = codeRules as RegisterOptions<FieldValues>;
+  const otpInputProps: Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    "value" | "defaultValue"
+  > = {
+    autoComplete: "one-time-code",
+    inputMode: "text",
+  };
+
+  function normalizeCode(value: string) {
+    return value.replace(/[^A-Za-z0-9]/g, "").toUpperCase();
+  }
+
+  const methodHint =
+    pendingMethod === "EMAIL"
+      ? translate("security.auth.two_factor.hint_email")
+      : pendingMethod === "TOTP"
+        ? translate("security.auth.two_factor.hint_totp")
+        : pendingMethod === "WHATSAPP"
+          ? translate("security.auth.two_factor.hint_whatsapp")
+          : translate("security.auth.two_factor.hint_generic");
+
+  async function handleVerify(values: TwoFactorVerifyFormValues) {
+    const normalizedCode = normalizeCode(values.code);
+
+    if (normalizedCode.length !== TWO_FACTOR_CODE_LENGTH || pending) {
+      return;
+    }
+
+    setPending(true);
+
+    try {
+      lastSubmittedCodeRef.current = normalizedCode;
+      await auth.verifyTwoFactor(normalizedCode);
+      sgWhistle.success({
+        message: translate("security.auth.two_factor.success"),
+      });
+      reset();
+      const nextPermissions = readStoredSession()?.permissions ?? [];
+      router.push(await resolvePostAuthPath(nextPermissions));
+    } catch (error) {
+      lastSubmittedCodeRef.current = null;
+      sgWhistle.error({
+        message:
+          extractApiMessage(error) ??
+          translate("security.auth.two_factor.error"),
+      });
+    } finally {
+      setPending(false);
+    }
+  }
+
+  async function handleAutoSubmit(rawValue: string) {
+    const normalizedCode = normalizeCode(rawValue);
+
+    if (
+      normalizedCode.length !== TWO_FACTOR_CODE_LENGTH ||
+      pending ||
+      lastSubmittedCodeRef.current === normalizedCode
+    ) {
+      return;
+    }
+
+    setValue("code", normalizedCode, {
+      shouldDirty: true,
+      shouldTouch: true,
+      shouldValidate: true,
+    });
+
+    await handleSubmit(handleVerify, handleInvalidSubmit)();
+  }
+
+  function handleInvalidSubmit(errors: FieldErrors<TwoFactorVerifyFormValues>) {
+    const firstMessage = errors.code?.message;
+
+    if (firstMessage) {
+      sgWhistle.error({ message: firstMessage });
+    }
+  }
+
+  async function handleResendEmail() {
+    const pendingSession = auth.pendingTwoFactor;
+
+    if (!pendingSession || resending) {
+      return;
+    }
+
+    setResending(true);
+
+    try {
+      await authService.resendTwoFactor(pendingSession);
+      sgWhistle.success({
+        message: translate("security.auth.two_factor.resend_success"),
+      });
+      reset({ code: "" });
+      lastSubmittedCodeRef.current = null;
+    } catch (error) {
+      sgWhistle.error({
+        message:
+          extractApiMessage(error) ??
+          translate("security.auth.two_factor.resend_error"),
+      });
+    } finally {
+      setResending(false);
+    }
+  }
+
+  return (
+    <div
+      className={`flex min-h-screen items-center justify-center px-4 py-8 sm:px-6 ${
+        isDarkMode
+          ? "bg-slate-950 text-slate-100"
+          : "bg-[radial-gradient(circle_at_top_left,_rgba(34,197,94,0.12),_transparent_28%),linear-gradient(180deg,#f8fafc_0%,#eef4fb_100%)] text-slate-900"
+      }`}
+    >
+      <SgCard
+        cardStyle="elevated"
+        size="lg"
+        className={`w-full max-w-md rounded-[2rem] border shadow-2xl ${
+          isDarkMode
+            ? "border-slate-800 bg-slate-900/95 shadow-black/30"
+            : "border-white/70 bg-white/95 shadow-slate-900/10"
+        }`}
+      >
+        <form
+          noValidate
+          onSubmit={handleSubmit(handleVerify, handleInvalidSubmit)}
+        >
+          <SgStack gap={24}>
+            <SgWhistleHost className="w-full" max={1} newestOnTop />
+
+            <SgStack gap={8} className="text-center">
+              <h1
+                className={`text-2xl font-semibold ${
+                  isDarkMode ? "text-slate-50" : "text-slate-950"
+                }`}
+              >
+                {translate("security.auth.two_factor.title")}
+              </h1>
+              <p
+                className={`text-sm leading-6 ${
+                  isDarkMode ? "text-slate-400" : "text-slate-600"
+                }`}
+              >
+                {translate("security.auth.two_factor.description")}
+              </p>
+              <p
+                className={`text-xs leading-5 ${
+                  isDarkMode ? "text-slate-500" : "text-slate-500"
+                }`}
+              >
+                {methodHint}
+              </p>
+            </SgStack>
+
+            {!auth.pendingTwoFactor ? (
+              <InlineNotice tone="warning">
+                {translate("security.auth.two_factor.missing")}
+              </InlineNotice>
+            ) : null}
+
+            <SgPanel
+              borderStyle="none"
+              className={`rounded-[1.5rem] px-3 py-4 ${
+                isDarkMode ? "bg-slate-950/70" : "bg-slate-50/70"
+              }`}
+            >
+              <SgInputOTP
+                id="security-two-factor-code"
+                control={otpControl}
+                name="code"
+                rules={otpRules}
+                label={translate("security.auth.two_factor.code")}
+                mask="### ###"
+                inputProps={otpInputProps}
+                onRawChange={(rawValue) => {
+                  if (normalizeCode(rawValue).length < TWO_FACTOR_CODE_LENGTH) {
+                    lastSubmittedCodeRef.current = null;
+                  }
+                }}
+                onComplete={(value) => {
+                  void handleAutoSubmit(value);
+                }}
+                groupClassName="justify-center"
+              />
+            </SgPanel>
+
+            <SgStack direction="row" justify="between" align="center" gap={12}>
+              <SgButton
+                appearance="outline"
+                severity="secondary"
+                shape="rounded"
+                label={translate("security.common.back")}
+                onClick={() => {
+                  window.location.assign(securityConfig.routes.login);
+                }}
+              />
+
+              {canResendEmail ? (
+                <SgButton
+                  appearance="ghost"
+                  severity="primary"
+                  shape="rounded"
+                  label={translate("security.auth.two_factor.resend")}
+                  loading={resending}
+                  disabled={resending || pending || !auth.pendingTwoFactor}
+                  onClick={() => {
+                    void handleResendEmail();
+                  }}
+                />
+              ) : (
+                <div />
+              )}
+            </SgStack>
+          </SgStack>
+        </form>
+      </SgCard>
+    </div>
+  );
+}

package/scaffold/src/app/auth/forgot-password/confirm/page.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { SgButton, SgPanel, SgStack } from "@seedgrid/fe-components";
+import { useRouter, useSearchParams } from "next/navigation";
+
+import { useI18n } from "@/i18n";
+import {
+  InlineNotice,
+  PageFrame,
+  authService,
+  extractApiMessage,
+  securityConfig,
+} from "@/modules/security";
+
+export default function ForgotPasswordConfirmPage() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const { t } = useI18n();
+  const [errorMessage, setErrorMessage] = useState<string | null>(null);
+
+  useEffect(() => {
+    const token = searchParams.get("token")?.trim();
+
+    if (!token) {
+      setErrorMessage(t("security.forgot_password.confirm.invalid_token"));
+      return;
+    }
+
+    let active = true;
+
+    void (async () => {
+      try {
+        await authService.confirmPasswordReset(token);
+
+        if (!active) {
+          return;
+        }
+
+        router.replace(securityConfig.routes.forgotPasswordSuccess);
+      } catch (error) {
+        if (!active) {
+          return;
+        }
+
+        setErrorMessage(
+          extractApiMessage(error) ?? t("security.forgot_password.confirm.error")
+        );
+      }
+    })();
+
+    return () => {
+      active = false;
+    };
+  }, [router, searchParams, t]);
+
+  return (
+    <PageFrame
+      title={t("security.forgot_password.confirm.title")}
+      description={t("security.forgot_password.confirm.description")}
+    >
+      {errorMessage ? (
+        <SgPanel borderStyle="none" className="mx-auto w-full max-w-xl">
+          <SgStack gap={16}>
+          <InlineNotice tone="danger">{errorMessage}</InlineNotice>
+          <SgStack direction="row" wrap gap={12}>
+            <SgButton
+              appearance="solid"
+              severity="primary"
+              shape="rounded"
+              label={t("security.forgot_password.confirm.request_new")}
+              onClick={() => {
+                window.location.assign(securityConfig.routes.forgotPassword);
+              }}
+            />
+            <SgButton
+              appearance="outline"
+              severity="secondary"
+              shape="rounded"
+              label={t("security.forgot_password.success_page.enter")}
+              onClick={() => {
+                window.location.assign(securityConfig.routes.login);
+              }}
+            />
+          </SgStack>
+          </SgStack>
+        </SgPanel>
+      ) : (
+        <SgPanel borderStyle="none" className="mx-auto w-full max-w-xl">
+          <InlineNotice>{t("security.forgot_password.confirm.loading")}</InlineNotice>
+        </SgPanel>
+      )}
+    </PageFrame>
+  );
+}