@dacyti-gsi/auth 0.0.0-stage → 0.3.0

package/src/next.ts

@@ -0,0 +1,309 @@
+import { cookies } from "next/headers";
+import { redirect } from "next/navigation";
+import { type NextRequest, NextResponse } from "next/server";
+
+import { defineSSO, type SSOClient, warnIfStaleSession } from "./index";
+import {
+  type AccessPolicy,
+  type AuthorizationError,
+  authorize,
+  isAuthorizationError,
+} from "./policy";
+import { bindComponents } from "./react";
+import type { SSOClientOptions, SSOSession } from "./types";
+
+/** Cuándo una pantalla quiere permisos vivos en lugar de la foto de la cookie. */
+export type SessionOptions = {
+  /**
+   * Vuelve a preguntar al portal por la identidad y los permisos.
+   *
+   * Cuesta una ida y vuelta —y una renovación de token si el acceso caducó—, así
+   * que no se hace por defecto. A cambio, es lo que hace que revocar un rol se
+   * note de inmediato. Para operaciones que dependen de un permiso concreto, es
+   * la opción correcta aunque el camino rápido sea más barato.
+   */
+  revalidate?: boolean;
+};
+
+export type NextSSO<Permission extends string> = SSOClient<Permission> & {
+  /**
+   * Handlers para el route handler catch-all.
+   *
+   * ```ts
+   * // app/api/sso/[...sso]/route.ts
+   * export const { GET, POST } = sso.handlers();
+   * export const runtime = "nodejs";
+   * ```
+   */
+  handlers(): {
+    GET: (request: Request) => Promise<Response>;
+    POST: (request: Request) => Promise<Response>;
+  };
+
+  /** Sesión actual, o `null`. Nunca redirige ni lanza. */
+  session(options?: SessionOptions): Promise<SSOSession<Permission> | null>;
+
+  /**
+   * Guarda declarativo para páginas: exige la política.
+   *
+   * ```ts
+   * const session = await sso.protectPage({ permission: "documentos:anular", requireMfa: true });
+   * ```
+   *
+   * Sin sesión redirige a autenticarse (con vuelta a la página actual cuando se
+   * le pasa `returnTo`). Sin permiso o sin segundo factor, lanza
+   * `SSOForbiddenError` / `SSOMfaRequiredError` para responder 403 —salvo que
+   * se pase `deniedRedirect`, que manda ahí al denegado en lugar de lanzar.
+   */
+  protectPage(
+    policy?: AccessPolicy<Permission> & {
+      returnTo?: string;
+      deniedRedirect?: string;
+    },
+  ): Promise<SSOSession<Permission>>;
+
+  /**
+   * Envuelve una Server Action o mutación con la política exigida.
+   *
+   * Revalida y persiste por defecto: las escrituras no usan la foto de la
+   * cookie sino permisos vivos del portal. Pasa `{ revalidate: false }` solo
+   * para lecturas baratas.
+   *
+   * ```ts
+   * export const anular = sso.action("documentos:anular", async (session, id: string) => { … });
+   * ```
+   *
+   * Sin sesión, sin permiso o sin segundo factor, lanza por defecto
+   * (`SSOAuthRequiredError`, `SSOForbiddenError`, `SSOMfaRequiredError`): lo
+   * correcto para páginas y rutas, donde el error lo atiende `error.tsx` o un
+   * 403. Para formularios con `useActionState`, pasa `onDenied` y la
+   * denegación se convierte en valor en lugar de reventar la acción.
+   *
+   * ```ts
+   * export const anular = sso.action("documentos:anular", run, {
+   *   onDenied: () => ({ ok: false as const, message: "Sin permiso." }),
+   * });
+   * ```
+   */
+  action<Args extends unknown[], Out>(
+    policy: Permission | AccessPolicy<Permission>,
+    fn: (session: SSOSession<Permission>, ...args: Args) => Promise<Out>,
+    options?: {
+      onDenied?: (error: AuthorizationError) => Promise<Out> | Out;
+    },
+  ): (...args: Args) => Promise<Out>;
+
+  /**
+   * URL que renueva la sesión y vuelve.
+   *
+   * Se usa como destino de un enlace o una navegación. Al pasar por un route
+   * handler, la cookie renovada sí se persiste.
+   */
+  refreshPath(returnTo?: string): string;
+
+  /**
+   * Renueva el acceso caducado ANTES de renderizar y deja la cookie nueva en la respuesta.
+   *
+   * Los Server Components no pueden escribir cookies: sin esto, pasados los 15 minutos de acceso
+   * cada render vuelve a canjear el refresh token (dos llamadas al portal por página) y, si el
+   * portal rota los tokens, acaba fallando. Se monta una vez por app:
+   *
+   * ```ts
+   * // proxy.ts
+   * import { sso } from "@/lib/sso";
+   * export const proxy = sso.proxy;
+   * export const config = { matcher: ["/((?!_next/|api/sso/|favicon.ico).*)"] };
+   * ```
+   *
+   * Si el portal no responde no hace nada: la página decide con lo que tenga.
+   */
+  proxy(request: NextRequest): Promise<NextResponse>;
+
+  /**
+   * Componentes de React ya atados a este cliente y con los permisos tipados:
+   * `Can`, `Protect`, `SignedIn`, `SignedOut`, `SignInLink`, `SignOutLink`.
+   */
+  components: ReturnType<typeof bindComponents<Permission>>;
+};
+
+/**
+ * Declara el cliente del portal con las piezas de Next.js ya montadas.
+ *
+ * ```ts
+ * // lib/sso.ts
+ * export const sso = defineNextSSO({
+ *   permissions: ["documentos:crear", "documentos:anular"],
+ * });
+ * // El resto sale del entorno: SSO_ISSUER, SSO_CLIENT_ID,
+ * // SSO_CLIENT_SECRET, SSO_SECRET, SSO_POST_LOGOUT_URI.
+ * ```
+ */
+export function defineNextSSO<const Permission extends string = string>(
+  options: SSOClientOptions<Permission>,
+): NextSSO<Permission> {
+  const client = defineSSO<Permission>(options);
+
+  /**
+   * En producción las cookies van con `Secure`; en desarrollo por HTTP, no.
+   * `appUrl` es la fuente más fiable: el servidor de Next.js no ve el protocolo
+   * del navegador desde aquí.
+   */
+  const secure = (options.appUrl ?? "").startsWith("https://")
+    ? true
+    : process.env.NODE_ENV === "production";
+
+  async function handle(request: Request): Promise<Response> {
+    const response = await client.handleRequest(request);
+
+    return (
+      response ??
+      new Response("Ruta del cliente SSO desconocida.", { status: 404 })
+    );
+  }
+
+  async function cookieValue(): Promise<string | undefined> {
+    const store = await cookies();
+
+    return store.get(client.cookieName)?.value;
+  }
+
+  /**
+   * Resuelve la sesión: camino rápido local, o contra el portal con
+   * `revalidate`. Un fallo del portal no cierra la sesión de inmediato: cae a
+   * la foto local, salvo que el acceso llevara caducado más de
+   * `MAX_STALE_SECONDS` (ver `warnIfStaleSession`).
+   */
+  async function resolve(
+    revalidate: boolean,
+  ): Promise<SSOSession<Permission> | null> {
+    try {
+      const resolved = await client.resolveSession(await cookieValue(), {
+        revalidate,
+      });
+      // Donde se puede escribir (Server Actions, route handlers) se guarda la renovación;
+      // en un Server Component `cookies().set` lanza y la renueva `proxy()`.
+      await persist(resolved?.cookie ?? null).catch(() => {});
+      return resolved?.session ?? null;
+    } catch {
+      // El núcleo ya aplica la ventana de gracia al revalidar; aquí solo
+      // queda la foto de la cookie. Si también está caducada hace más de la
+      // ventana, no se sirve: una caída del portal no es barra libre.
+      const session = await client.readSession(await cookieValue());
+      if (session && warnIfStaleSession(session.expiresAt)) return null;
+      return session;
+    }
+  }
+
+  async function persist(cookie: string | null): Promise<void> {
+    if (!cookie) return;
+    const store = await cookies();
+    store.set(client.cookieName, cookie, {
+      path: "/",
+      httpOnly: true,
+      sameSite: "lax",
+      secure,
+      maxAge: client.sessionMaxAge,
+    });
+  }
+
+  const self: Omit<NextSSO<Permission>, "components"> = {
+    ...client,
+
+    handlers: () => ({ GET: handle, POST: handle }),
+
+    session: (sessionOptions = {}) =>
+      resolve(sessionOptions.revalidate ?? false),
+
+    async proxy(request) {
+      const current = request.cookies.get(client.cookieName)?.value;
+      if (!current) return NextResponse.next();
+
+      let resolved: Awaited<ReturnType<typeof client.resolveSession>>;
+      try {
+        resolved = await client.resolveSession(current);
+      } catch {
+        return NextResponse.next();
+      }
+      if (!resolved?.cookie) return NextResponse.next();
+
+      // La página de esta misma petición debe ver la cookie nueva, no la caducada.
+      request.cookies.set(client.cookieName, resolved.cookie);
+      const response = NextResponse.next({ request });
+      response.cookies.set(client.cookieName, resolved.cookie, {
+        path: "/",
+        httpOnly: true,
+        sameSite: "lax",
+        secure,
+        maxAge: client.sessionMaxAge,
+      });
+      return response;
+    },
+
+    refreshPath(returnTo) {
+      return returnTo
+        ? `${client.basePath}/refresh?to=${encodeURIComponent(returnTo)}`
+        : `${client.basePath}/refresh`;
+    },
+
+    async protectPage(policy = {}) {
+      const { returnTo, deniedRedirect, ...access } = policy;
+      const session = await resolve(access.revalidate ?? false);
+      if (!session) redirect(client.signInPath(returnTo));
+      try {
+        return authorize(session, access);
+      } catch (error) {
+        // Denegación de la política (no fallo del portal): con destino
+        // declarado, al aviso en lugar de al 403 seco.
+        if (deniedRedirect && isAuthorizationError(error)) {
+          redirect(deniedRedirect);
+        }
+        throw error;
+      }
+    },
+
+    action<Args extends unknown[], Out>(
+      this: void,
+      policy: Permission | AccessPolicy<Permission>,
+      fn: (session: SSOSession<Permission>, ...args: Args) => Promise<Out>,
+      options?: {
+        onDenied?: (error: AuthorizationError) => Promise<Out> | Out;
+      },
+    ): (...args: Args) => Promise<Out> {
+      const access: AccessPolicy<Permission> =
+        typeof policy === "string"
+          ? { permission: policy, revalidate: true }
+          : { revalidate: true, ...policy };
+      return (async (...args: Args) => {
+        const resolved = await client.resolveSession(await cookieValue(), {
+          revalidate: access.revalidate ?? true,
+        });
+        let session: SSOSession<Permission>;
+        try {
+          session = authorize(resolved?.session ?? null, access);
+        } catch (error: unknown) {
+          // Solo las denegaciones de la política se convierten en valor, y
+          // solo si se pidió: un fallo del portal sigue lanzando.
+          if (options?.onDenied && isAuthorizationError(error)) {
+            return options.onDenied(error);
+          }
+          throw error;
+        }
+        await persist(resolved?.cookie ?? null);
+        return fn(session, ...args);
+      }) as (...args: Args) => Promise<Out>;
+    },
+  };
+
+  return { ...self, components: bindComponents<Permission>(self) };
+}
+
+export { SSOForbiddenError } from "./errors";
+export {
+  type AccessPolicy,
+  type AuthorizationError,
+  authorize,
+  isAuthorizationError,
+  SSOAuthRequiredError,
+  SSOMfaRequiredError,
+} from "./policy";
+export type { SSOSession, SSOUser } from "./types";

package/src/pkce.ts

@@ -0,0 +1,48 @@
+import { createHash, randomBytes } from "node:crypto";
+
+function base64url(input: Buffer): string {
+  return input.toString("base64url");
+}
+
+export type AuthorizationAttempt = {
+  /** Se guarda en la cookie temporal y se envía al canjear el código. */
+  verifier: string;
+  /** Viaja en la URL de autorización. */
+  challenge: string;
+  /** Debe volver intacto; es la protección contra CSRF en el redirect. */
+  state: string;
+};
+
+/**
+ * Prepara un intento de autorización con PKCE.
+ *
+ * El verifier son 48 bytes aleatorios; el challenge es su SHA-256. El portal
+ * exige `S256` para todos los clientes, también los confidenciales: sin PKCE,
+ * un código interceptado en el redirect puede canjearse desde otro sitio.
+ */
+export function createAuthorizationAttempt(): AuthorizationAttempt {
+  const verifier = base64url(randomBytes(48));
+
+  return {
+    verifier,
+    challenge: base64url(createHash("sha256").update(verifier).digest()),
+    state: base64url(randomBytes(16)),
+  };
+}
+
+/**
+ * Compara dos `state` sin filtrar información por el tiempo de comparación.
+ *
+ * Una comparación normal con `===` sale antes en el primer carácter distinto,
+ * lo que permitiría adivinar el valor byte a byte cronometrando.
+ */
+export function statesMatch(expected: string, received: string): boolean {
+  if (expected.length !== received.length) return false;
+
+  let difference = 0;
+  for (let index = 0; index < expected.length; index += 1) {
+    difference |= expected.charCodeAt(index) ^ received.charCodeAt(index);
+  }
+
+  return difference === 0;
+}

package/src/policy.ts

@@ -0,0 +1,102 @@
+import { SSOError, SSOForbiddenError } from "./errors";
+import type { SSOSession } from "./types";
+
+/** La sesión terminó o nunca existió: hay que mandar a autenticarse. */
+export class SSOAuthRequiredError extends SSOError {
+  constructor(message = "Se requiere sesión.") {
+    super(message);
+  }
+}
+
+/** Hay sesión pero sin segundo factor, y la política lo exige. */
+export class SSOMfaRequiredError extends SSOError {
+  constructor(message = "Esta operación requiere verificación en dos pasos.") {
+    super(message);
+  }
+}
+
+/**
+ * Denegación de la política: sin sesión, sin permiso o sin segundo factor.
+ *
+ * Son los únicos errores que `onDenied` convierte en valor. Un fallo del
+ * portal (`SSOProtocolError`) o de configuración nunca se tragan: una caída
+ * no es una denegación y tratarla como tal echaría a usuarios por un 502.
+ */
+export type AuthorizationError =
+  | SSOAuthRequiredError
+  | SSOForbiddenError
+  | SSOMfaRequiredError;
+
+export function isAuthorizationError(
+  error: unknown,
+): error is AuthorizationError {
+  return (
+    error instanceof SSOAuthRequiredError ||
+    error instanceof SSOForbiddenError ||
+    error instanceof SSOMfaRequiredError
+  );
+}
+
+/**
+ * Política de acceso declarativa. Todo deniega por defecto: solo se permite lo
+ * que se declara.
+ */
+export type AccessPolicy<Permission extends string = string> = {
+  /** Permiso exigido. Sin sesión o sin permiso, se deniega. */
+  permission?: Permission | readonly Permission[];
+  /** Exige que todos los permisos listados estén presentes. Por defecto basta uno. */
+  mode?: "any" | "all";
+  /**
+   * Exige tener al menos un permiso de esta aplicación, cualquiera.
+   *
+   * El portal autentica a cualquier cuenta: haber entrado no significa tener acceso a
+   * esta app. Con `access: true` quien llega sin ningún permiso queda fuera (403), sin
+   * tener que escoger un permiso «de entrada» arbitrario.
+   */
+  access?: boolean;
+  /** Exige segundo factor (`amr` incluye `mfa`). */
+  requireMfa?: boolean;
+  /** Vuelve a preguntar al portal por permisos vivos. */
+  revalidate?: boolean;
+};
+
+/**
+ * Decide si una sesión cumple la política. No habla con la red: la frescura la
+ * decide quien llama (`revalidate` en `protect`/`action`).
+ *
+ * Lanza `SSOForbiddenError`, `SSOMfaRequiredError` o `SSOAuthRequiredError`.
+ * Devuelve la sesión para encadenar.
+ */
+export function authorize<Permission extends string>(
+  session: SSOSession<Permission> | null,
+  policy: AccessPolicy<Permission> = {},
+): SSOSession<Permission> {
+  if (!session) throw new SSOAuthRequiredError();
+
+  if (policy.access && session.permissions.length === 0) {
+    throw new SSOForbiddenError("acceso");
+  }
+
+  const wanted = policy.permission
+    ? Array.isArray(policy.permission)
+      ? [...policy.permission]
+      : [policy.permission]
+    : [];
+
+  if (wanted.length > 0) {
+    const ok =
+      policy.mode === "all"
+        ? session.canAll(...wanted)
+        : session.canAny(...wanted);
+    if (!ok) {
+      const missing = wanted.find((p) => !session.can(p)) ?? wanted[0];
+      session.requires(missing as Permission);
+    }
+  }
+
+  if (policy.requireMfa && !session.usedSecondFactor()) {
+    throw new SSOMfaRequiredError();
+  }
+
+  return session;
+}

package/src/react.tsx

@@ -0,0 +1,171 @@
+import type { ComponentProps, ReactNode } from "react";
+
+import { type AccessPolicy, authorize } from "./policy";
+import type { SSOSession } from "./types";
+
+/** Lo mínimo que un componente necesita: resolver la sesión actual. */
+export type SessionResolver<Permission extends string> = {
+  session(options?: {
+    revalidate?: boolean;
+  }): Promise<SSOSession<Permission> | null>;
+};
+
+export type ProtectProps<Permission extends string> =
+  AccessPolicy<Permission> & {
+    /** El cliente Next (`sso`). Explícito a propósito: sin contexto global que heredar. */
+    sso: SessionResolver<Permission>;
+    children: ReactNode;
+    /** Qué pintar cuando se deniega. Por defecto no pinta nada (niega por defecto). */
+    fallback?: ReactNode;
+  };
+
+/**
+ * Guarda declarativa para React Server Components.
+ *
+ * ```tsx
+ * <Protect sso={sso} permission="pedidos:anular" fallback={<p>Sin acceso.</p>}>
+ *   <BotonAnular />
+ * </Protect>
+ * ```
+ *
+ * Nunca redirige ni lanza: denegar pinta `fallback` (o nada). Para páginas
+ * completas usa `sso.protectPage()`, que sí redirige a entrar.
+ */
+export async function Protect<Permission extends string>({
+  sso,
+  children,
+  fallback = null,
+  ...policy
+}: ProtectProps<Permission>): Promise<ReactNode> {
+  const session = await sso.session({ revalidate: policy.revalidate ?? false });
+
+  try {
+    authorize(session, policy);
+    return children;
+  } catch {
+    return fallback;
+  }
+}
+
+export type CanProps<Permission extends string> = AccessPolicy<Permission> & {
+  sso: SessionResolver<Permission>;
+  children: ReactNode;
+  fallback?: ReactNode;
+};
+
+/**
+ * Alias de `Protect` para permisos puntuales en la interfaz. Misma negación
+ * por defecto: sin permiso, `fallback` o nada.
+ */
+export async function Can<Permission extends string>(
+  props: CanProps<Permission>,
+): Promise<ReactNode> {
+  return Protect(props);
+}
+
+/** Lo mínimo para pintar enlaces de entrada y salida. */
+export type LinkResolver = {
+  signInPath(returnTo?: string): string;
+  signOutPath(): string;
+};
+
+type AnchorRest = Omit<ComponentProps<"a">, "href">;
+
+export type SignInLinkProps = AnchorRest & {
+  /** El cliente Next (`sso`). */
+  sso: LinkResolver;
+  /** A dónde volver tras entrar. Por defecto, la raíz. */
+  returnTo?: string;
+};
+
+/**
+ * Enlace de entrada.
+ *
+ * ```tsx
+ * <SignInLink sso={sso} returnTo="/panel" className="boton">
+ *   Entrar con el Portal SSO
+ * </SignInLink>
+ * ```
+ */
+export function SignInLink({
+  sso,
+  returnTo,
+  children = "Entrar",
+  ...anchor
+}: SignInLinkProps): ReactNode {
+  return (
+    <a {...anchor} href={sso.signInPath(returnTo)}>
+      {children}
+    </a>
+  );
+}
+
+export type SignOutLinkProps = AnchorRest & {
+  /** El cliente Next (`sso`). */
+  sso: LinkResolver;
+};
+
+/**
+ * Enlace de salida. Cierra la sesión local **y** la del portal: salir solo de
+ * la local dejaría a la persona dentro del portal y el siguiente entrar la
+ * devolvería sin pedir nada.
+ */
+export function SignOutLink({
+  sso,
+  children = "Salir",
+  ...anchor
+}: SignOutLinkProps): ReactNode {
+  return (
+    <a {...anchor} href={sso.signOutPath()}>
+      {children}
+    </a>
+  );
+}
+
+type BoundProps<Permission extends string> = AccessPolicy<Permission> & {
+  children: ReactNode;
+  fallback?: ReactNode;
+};
+
+/**
+ * Los componentes ya atados a un cliente: sin pasar `sso` en cada uso y con el catálogo de
+ * permisos tipado (una errata en `permission` no compila).
+ *
+ * ```tsx
+ * // lib/sso.ts
+ * export const { Can, SignedIn, SignedOut, SignInLink, SignOutLink } = sso.components;
+ *
+ * <SignedOut><SignInLink returnTo="/panel" /></SignedOut>
+ * <SignedIn><SignOutLink /></SignedIn>
+ * <Can permission="pedidos:anular"><BotonAnular /></Can>
+ * ```
+ */
+export function bindComponents<Permission extends string>(
+  sso: SessionResolver<Permission> & LinkResolver,
+) {
+  return {
+    /** Pinta los hijos si se cumple la política; si no, `fallback` o nada. */
+    Can: (props: BoundProps<Permission>) => Protect({ ...props, sso }),
+    /** Igual que `Can`; el nombre que lee mejor para bloques completos. */
+    Protect: (props: BoundProps<Permission>) => Protect({ ...props, sso }),
+
+    /** Solo con sesión. */
+    SignedIn: async ({
+      children,
+    }: {
+      children: ReactNode;
+    }): Promise<ReactNode> => ((await sso.session()) ? children : null),
+
+    /** Solo sin sesión. */
+    SignedOut: async ({
+      children,
+    }: {
+      children: ReactNode;
+    }): Promise<ReactNode> => ((await sso.session()) ? null : children),
+
+    SignInLink: (props: Omit<SignInLinkProps, "sso">) =>
+      SignInLink({ ...props, sso }),
+    SignOutLink: (props: Omit<SignOutLinkProps, "sso">) =>
+      SignOutLink({ ...props, sso }),
+  };
+}