@seedgrid/fe-security 2026.6.2 → 2026.7.1

package/scaffold/src/modules/security/hooks/usePermission.ts

@@ -0,0 +1,35 @@
+"use client";
+
+import { useMemo } from "react";
+
+import { buildCrudPermissions } from "@seedgrid/fe-security";
+import { useAuth } from "./useAuth";
+
+export function usePermission(permission: string) {
+  const auth = useAuth();
+
+  return auth.hasPermission(permission);
+}
+
+export function useCrudPermission(resource: string) {
+  const auth = useAuth();
+
+  return useMemo(() => {
+    const permissions = buildCrudPermissions(resource);
+
+    return {
+      ...permissions,
+      canRead: auth.hasPermission(permissions.read),
+      canCreate: auth.hasPermission(permissions.create),
+      canUpdate: auth.hasPermission(permissions.update),
+      canDelete: auth.hasPermission(permissions.delete),
+      isReadOnly:
+        auth.hasPermission(permissions.read) &&
+        !auth.hasAnyPermission([
+          permissions.create,
+          permissions.update,
+          permissions.delete,
+        ]),
+    };
+  }, [auth, resource]);
+}

package/scaffold/src/modules/security/host-access.ts

@@ -0,0 +1,59 @@
+"use client";
+
+import { useEffect, useState } from "react";
+
+import { appEnvironment } from "@/config/environment";
+
+export type SecurityHostKind = "local" | "master" | "tenant" | "unknown";
+
+export function resolveSecurityHostKind(hostname: string): SecurityHostKind {
+  const normalizedHostname = hostname.trim().toLowerCase();
+  const masterHost = appEnvironment.hosts.masterAppHost.trim().toLowerCase();
+
+  if (
+    !normalizedHostname ||
+    normalizedHostname === "localhost" ||
+    normalizedHostname === "127.0.0.1" ||
+    normalizedHostname.endsWith(".local")
+  ) {
+    return "local";
+  }
+
+  if (normalizedHostname === masterHost) {
+    return "master";
+  }
+
+  if (masterHost && normalizedHostname.endsWith(`.${masterHost}`)) {
+    return "tenant";
+  }
+
+  return "unknown";
+}
+
+export function isCompanyManagementEnabledForHostKind(
+  hostKind: SecurityHostKind
+) {
+  return hostKind !== "master";
+}
+
+export function useSecurityHostKind() {
+  const [hostKind, setHostKind] = useState<SecurityHostKind | null>(null);
+
+  useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    setHostKind(resolveSecurityHostKind(window.location.hostname));
+  }, []);
+
+  return hostKind;
+}
+
+export function useCompanyManagementEnabledForCurrentHost() {
+  const hostKind = useSecurityHostKind();
+
+  return hostKind == null
+    ? null
+    : isCompanyManagementEnabledForHostKind(hostKind);
+}

package/scaffold/src/modules/security/index.ts

@@ -0,0 +1,44 @@
+// seedgrid:managed
+
+export { AuthProvider, useAuthContext } from "./AuthProvider";
+export { useAuth } from "./hooks/useAuth";
+export { useCrudPermission, usePermission } from "./hooks/usePermission";
+export { useDebouncedSearch } from "./hooks/useDebouncedSearch";
+export { AppShell } from "./components/AppShell";
+export { CompanyManagementGuard } from "./components/CompanyManagementGuard";
+export { PageFrame, InlineNotice } from "./components/PageFrame";
+export { RouteGuard } from "./components/RouteGuard";
+export { securityConfig } from "./config";
+export {
+  isCompanyManagementEnabledForHostKind,
+  resolveSecurityHostKind,
+  useCompanyManagementEnabledForCurrentHost,
+  useSecurityHostKind,
+} from "./host-access";
+export { resolvePostAuthPath } from "./navigation";
+export { useSecurityAppShellSections } from "./useSecurityAppShellSections";
+export { authService } from "./services/auth-service";
+export {
+  classifySelfEnterInvitationAdminError,
+  classifySelfEnterInvitationError,
+  isSelfEnterInvitationEmailMismatchError,
+  securityService,
+} from "./services/security-service";
+export {
+  extractApiMessage,
+  isApiClientError,
+} from "./services/security-api";
+export type * from "./types";
+
+// Promovidos pra lib versionada (@seedgrid/fe-security) — ver ADR 0004/0005 e
+// scaffold/README.md pro criterio lib vs scaffold usado nesta extracao.
+export { PickListField, StatusBadge } from "@seedgrid/fe-security/client";
+export {
+  buildCrudPermissions,
+  createPermissionSet,
+  hasAllPermissions,
+  hasAnyPermission,
+  hasPermission,
+  normalizePermission,
+  securityMessages,
+} from "@seedgrid/fe-security";

package/scaffold/src/modules/security/navigation.ts

@@ -0,0 +1,41 @@
+import { securityConfig } from "./config";
+
+// seedgrid:post-auth-resolvers-imports:start
+// seedgrid:post-auth-resolvers-imports:end
+
+/**
+ * Resolve pra onde mandar o usuário logo após um login bem-sucedido. Devolve
+ * a rota, ou `null` pra deixar o próximo resolver (ou o dashboard) decidir.
+ * Pode ser síncrono ou assíncrono (ex.: consultar as empresas do usuário).
+ */
+export type PostAuthResolver = (
+  permissions: Iterable<string>,
+) => Promise<string | null> | string | null;
+
+// Módulos registram seus resolvers aqui via o campo `postAuthResolver` do
+// module.ts (o CLI insere no marcador abaixo). Ex.: login-tenancy manda pro
+// select-company quando o usuário tem mais de uma empresa.
+const postAuthResolvers: PostAuthResolver[] = [
+  // seedgrid:post-auth-resolvers-register:start
+  // seedgrid:post-auth-resolvers-register:end
+];
+
+export async function resolvePostAuthPath(
+  permissions: Iterable<string>,
+): Promise<string> {
+  const permissionList = Array.from(permissions);
+
+  for (const resolver of postAuthResolvers) {
+    try {
+      const path = await resolver(permissionList);
+      if (path) {
+        return path;
+      }
+    } catch {
+      // Um resolver que falha não pode travar o login — segue pro próximo
+      // (e, no fim, pro dashboard).
+    }
+  }
+
+  return securityConfig.routes.dashboard;
+}

package/scaffold/src/modules/security/server/avatar-routes.ts

@@ -0,0 +1,86 @@
+import { NextResponse } from "next/server";
+
+import { getSecuritySessionServer } from "./session-server";
+
+// Proxy do avatar do usuário: repassa o binário do report-api com a sessão do
+// usuário (cookie→Bearer, refresh em 401). Usa o MESMO motor de sessão
+// (createSecurityServer, via getSecuritySessionServer) que o resto do app —
+// `fetchWithSession` devolve a Response crua, ideal pra repassar bytes.
+export async function createUserAvatarRouteResponse(
+  publicId: string,
+  version: string | null
+) {
+  const normalizedPublicId = publicId.trim();
+
+  if (!normalizedPublicId) {
+    return NextResponse.json(
+      {
+        message: "User publicId is required.",
+      },
+      {
+        status: 400,
+      }
+    );
+  }
+
+  const query = version ? `?v=${encodeURIComponent(version)}` : "";
+  const path = `/users/${encodeURIComponent(normalizedPublicId)}/avatar${query}`;
+
+  let upstreamResponse: Response;
+  try {
+    const session = await getSecuritySessionServer();
+    upstreamResponse = await session.fetchWithSession(path, { cache: "no-store" });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        message:
+          error instanceof Error ? error.message : "Unexpected avatar proxy error.",
+      },
+      {
+        status: 500,
+      }
+    );
+  }
+
+  if (!upstreamResponse.ok) {
+    const text = await upstreamResponse.text();
+    const trimmed = text.trim();
+
+    if (!trimmed) {
+      return new NextResponse(null, { status: upstreamResponse.status });
+    }
+
+    const contentType =
+      upstreamResponse.headers.get("content-type") ?? "text/plain; charset=utf-8";
+
+    return new NextResponse(trimmed, {
+      status: upstreamResponse.status,
+      headers: { "content-type": contentType },
+    });
+  }
+
+  const headers = new Headers();
+  copyResponseHeader(upstreamResponse, headers, "content-type");
+  copyResponseHeader(upstreamResponse, headers, "content-disposition");
+  copyResponseHeader(upstreamResponse, headers, "content-length");
+  copyResponseHeader(upstreamResponse, headers, "cache-control");
+  copyResponseHeader(upstreamResponse, headers, "etag");
+  copyResponseHeader(upstreamResponse, headers, "last-modified");
+
+  return new NextResponse(await upstreamResponse.arrayBuffer(), {
+    status: upstreamResponse.status,
+    headers,
+  });
+}
+
+function copyResponseHeader(
+  response: Response,
+  headers: Headers,
+  headerName: string
+) {
+  const value = response.headers.get(headerName);
+
+  if (value) {
+    headers.set(headerName, value);
+  }
+}

package/scaffold/src/modules/security/server/public-api-base-url.ts

@@ -0,0 +1,26 @@
+"use server";
+
+import { headers } from "next/headers";
+
+import { resolveApiBaseUrlForHostname } from "@/config/environment";
+
+export async function resolvePublicApiBaseUrl() {
+  const requestHeaders = await headers();
+  const hostname = resolveRequestHostname(requestHeaders);
+
+  if (!hostname) {
+    throw new Error(
+      "Could not resolve the public API base URL. Access the app through a configured domain hostname and provide the corresponding host header."
+    );
+  }
+
+  return resolveApiBaseUrlForHostname(hostname);
+}
+
+function resolveRequestHostname(requestHeaders: Headers) {
+  const forwardedHost = requestHeaders.get("x-forwarded-host")?.trim();
+  const hostHeader = requestHeaders.get("host")?.trim();
+  const candidate = forwardedHost || hostHeader || "";
+
+  return candidate.replace(/:\d+$/, "");
+}

package/scaffold/src/modules/security/server/session-routes.ts.hbs

@@ -0,0 +1,322 @@
+import { NextRequest, NextResponse } from "next/server";
+
+import { resolveApiBaseUrlForHostname } from "@/config/environment";
+import { ApiClientError, createApiClient } from "@seedgrid/fe-core";
+
+const REFRESH_COOKIE_NAME =
+  process.env.SEEDGRID_SECURITY_REFRESH_COOKIE_NAME?.trim() ||
+  "sg_{{project_slug}}_refresh_token";
+const ACCESS_COOKIE_NAME =
+  process.env.SEEDGRID_SECURITY_ACCESS_COOKIE_NAME?.trim() ||
+  "sg_{{project_slug}}_access_token";
+const REFRESH_COOKIE_MAX_AGE_SECONDS = resolveRefreshCookieMaxAge();
+
+export async function createLoginRouteResponse(request: NextRequest) {
+  const body = await request.json();
+
+  return forwardPublicAuthRequest(request, "/public/auth/login", {
+    body,
+  });
+}
+
+export async function createVerifyTwoFactorRouteResponse(request: NextRequest) {
+  const body = await request.json();
+
+  return forwardPublicAuthRequest(request, "/public/2f/verify", {
+    body,
+  });
+}
+
+export async function createResendTwoFactorRouteResponse(request: NextRequest) {
+  const body = await request.json();
+
+  return forwardPublicAuthRequest(request, "/public/2f/resend", {
+    body,
+  });
+}
+
+const pendingRefreshResponses = new Map<string, Promise<NextResponse>>();
+
+export async function createRefreshRouteResponse(request: NextRequest) {
+  const refreshToken = request.cookies.get(REFRESH_COOKIE_NAME)?.value?.trim();
+
+  if (!refreshToken) {
+    return createUnauthorizedRouteResponse();
+  }
+
+  const existing = pendingRefreshResponses.get(refreshToken);
+
+  if (existing) {
+    return existing;
+  }
+
+  const refreshPromise = (async () => {
+    try {
+      const authClient = createAuthClient(request);
+      const payload = await authClient.post<unknown>("/public/auth/refresh", {
+        body: {
+          refreshToken,
+        },
+        requireAuth: false,
+        retry: false,
+        cache: "no-store",
+      });
+
+      return createAuthSuccessResponse(payload);
+    } catch (error) {
+      return createAuthErrorResponse(error, true);
+    }
+  })().finally(() => {
+    pendingRefreshResponses.delete(refreshToken);
+  });
+
+  pendingRefreshResponses.set(refreshToken, refreshPromise);
+
+  return refreshPromise;
+}
+
+export function createLogoutRouteResponse() {
+  const response = NextResponse.json(
+    {
+      ok: true,
+    },
+    {
+      status: 200,
+    }
+  );
+
+  clearRefreshTokenCookie(response);
+  clearAccessTokenCookie(response);
+
+  return response;
+}
+
+async function forwardPublicAuthRequest(
+  request: NextRequest,
+  path: string,
+  options: {
+    body?: Record<string, unknown>;
+  }
+) {
+  try {
+    const authClient = createAuthClient(request);
+    const payload = await authClient.post<unknown>(path, {
+      body: options.body,
+      requireAuth: false,
+      retry: false,
+      cache: "no-store",
+    });
+
+    return createAuthSuccessResponse(payload);
+  } catch (error) {
+    return createAuthErrorResponse(error, false);
+  }
+}
+
+function createAuthClient(request: NextRequest) {
+  return createApiClient({
+    baseUrl: resolveApiBaseUrlForHostname(resolveRequestHostname(request)),
+    defaultCache: "no-store",
+  });
+}
+
+function resolveRequestHostname(request: NextRequest) {
+  const forwardedHost = request.headers.get("x-forwarded-host")?.trim();
+  const hostHeader = request.headers.get("host")?.trim();
+  const candidate = forwardedHost || hostHeader || request.nextUrl.hostname;
+
+  return candidate.replace(/:\d+$/, "");
+}
+
+function createAuthSuccessResponse(payload: unknown) {
+  const response = NextResponse.json(stripRefreshToken(payload), {
+    status: 200,
+  });
+  const refreshToken = pickString(payload, "refreshToken");
+  const accessToken = pickString(payload, "accessToken") ?? pickString(payload, "token");
+  const expiresIn = pickNumber(payload, "expiresIn");
+
+  if (refreshToken) {
+    setRefreshTokenCookie(response, refreshToken);
+  }
+
+  if (accessToken) {
+    setAccessTokenCookie(response, accessToken, expiresIn ?? undefined);
+  }
+
+  return response;
+}
+
+function createUnauthorizedRouteResponse() {
+  const response = NextResponse.json(
+    {
+      message: "Refresh token is missing or expired.",
+    },
+    {
+      status: 401,
+    }
+  );
+
+  clearRefreshTokenCookie(response);
+  clearAccessTokenCookie(response);
+
+  return response;
+}
+
+function createAuthErrorResponse(error: unknown, clearCookieOnUnauthorized: boolean) {
+  if (error instanceof ApiClientError) {
+    const response = NextResponse.json(
+      normalizeErrorBody(error.responseBody, error.message),
+      {
+        status: error.status,
+      }
+    );
+
+    if (clearCookieOnUnauthorized && error.status === 401) {
+      clearRefreshTokenCookie(response);
+      clearAccessTokenCookie(response);
+    }
+
+    return response;
+  }
+
+  const response = NextResponse.json(
+    {
+      message: error instanceof Error ? error.message : "Unexpected auth error.",
+    },
+    {
+      status: 500,
+    }
+  );
+
+  if (clearCookieOnUnauthorized) {
+    clearRefreshTokenCookie(response);
+    clearAccessTokenCookie(response);
+  }
+
+  return response;
+}
+
+function setRefreshTokenCookie(response: NextResponse, refreshToken: string) {
+  response.cookies.set({
+    name: REFRESH_COOKIE_NAME,
+    value: refreshToken,
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: REFRESH_COOKIE_MAX_AGE_SECONDS,
+  });
+}
+
+function setAccessTokenCookie(
+  response: NextResponse,
+  accessToken: string,
+  expiresIn?: number
+) {
+  response.cookies.set({
+    name: ACCESS_COOKIE_NAME,
+    value: accessToken,
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: expiresIn ?? 900,
+  });
+}
+
+function clearRefreshTokenCookie(response: NextResponse) {
+  response.cookies.set({
+    name: REFRESH_COOKIE_NAME,
+    value: "",
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: 0,
+  });
+}
+
+function clearAccessTokenCookie(response: NextResponse) {
+  response.cookies.set({
+    name: ACCESS_COOKIE_NAME,
+    value: "",
+    httpOnly: true,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: "lax",
+    path: "/",
+    maxAge: 0,
+  });
+}
+
+function stripRefreshToken(payload: unknown) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return payload;
+  }
+
+  const record = payload as Record<string, unknown>;
+  const { refreshToken: _refreshToken, ...rest } = record;
+
+  return rest;
+}
+
+function normalizeErrorBody(body: unknown, fallbackMessage: string) {
+  if (!body) {
+    return {
+      message: fallbackMessage,
+    };
+  }
+
+  if (typeof body === "string") {
+    return {
+      message: body,
+    };
+  }
+
+  if (typeof body === "object") {
+    return body;
+  }
+
+  return {
+    message: fallbackMessage,
+  };
+}
+
+function pickString(value: unknown, key: string) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const candidate = (value as Record<string, unknown>)[key];
+
+  return typeof candidate === "string" && candidate.trim().length > 0
+    ? candidate.trim()
+    : null;
+}
+
+function pickNumber(value: unknown, key: string) {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+
+  const candidate = (value as Record<string, unknown>)[key];
+
+  return typeof candidate === "number" && Number.isFinite(candidate)
+    ? candidate
+    : null;
+}
+
+function resolveRefreshCookieMaxAge() {
+  const configuredValue =
+    process.env.SEEDGRID_SECURITY_REFRESH_COOKIE_MAX_AGE_SECONDS?.trim() ?? "";
+
+  if (!configuredValue) {
+    return 60 * 60 * 24 * 30;
+  }
+
+  const parsedValue = Number.parseInt(configuredValue, 10);
+
+  return Number.isFinite(parsedValue) && parsedValue > 0
+    ? parsedValue
+    : 60 * 60 * 24 * 30;
+}

package/scaffold/src/modules/security/server/session-server.ts.hbs

@@ -0,0 +1,30 @@
+"use server";
+
+// Instância do motor de sessão do fe-security (createSecurityServer) com a
+// config de cookie do app. É o MESMO motor que os módulos compostos
+// (billing/tenancy/backup) usam via os seus `server.ts` — o próprio security
+// passa a usá-lo também (ex.: proxy de avatar), em vez do antigo
+// `createServerApiClient` (removido). Um motor só de fetch autenticado.
+
+import { createSecurityServer } from "@seedgrid/fe-security/server";
+
+import { resolvePublicApiBaseUrl } from "./public-api-base-url";
+
+const ACCESS_COOKIE_NAME =
+  process.env.SEEDGRID_SECURITY_ACCESS_COOKIE_NAME?.trim() ||
+  "sg_{{project_slug}}_access_token";
+const REFRESH_COOKIE_NAME =
+  process.env.SEEDGRID_SECURITY_REFRESH_COOKIE_NAME?.trim() ||
+  "sg_{{project_slug}}_refresh_token";
+const PASSWORD_CHANGE_REQUIRED_COOKIE_NAME = "sg_{{project_slug}}_password_change_required";
+
+export async function getSecuritySessionServer() {
+  return createSecurityServer({
+    apiBaseUrl: await resolvePublicApiBaseUrl(),
+    cookies: {
+      token: ACCESS_COOKIE_NAME,
+      refresh: REFRESH_COOKIE_NAME,
+      passwordChangeRequired: PASSWORD_CHANGE_REQUIRED_COOKIE_NAME,
+    },
+  });
+}