@dacyti-gsi/auth 0.0.0-stage → 0.2.0

package/src/types.ts

@@ -0,0 +1,143 @@
+/**
+ * Configuración del cliente.
+ *
+ * Todo tiene valor por defecto: lo que no se pasa se lee del entorno
+ * (`SSO_ISSUER`, `SSO_CLIENT_ID`, `SSO_CLIENT_SECRET`, `SSO_SECRET`,
+ * `APP_URL`, `SSO_POST_LOGOUT_URI`). Cada opción que hay que rellenar para
+ * empezar es una decisión que se le pide a alguien que todavía no conoce el
+ * sistema; las variables de entorno ya son el idioma de despliegue.
+ *
+ * ```ts
+ * export const sso = defineNextSSO({ permissions: ["documentos:anular"] });
+ * ```
+ */
+export type SSOClientOptions<Permission extends string = string> = {
+  /**
+   * URL del emisor, tal cual la publica el portal. Ej: `https://sso.ejemplo.com/api/auth`.
+   * Por defecto `SSO_ISSUER`.
+   */
+  issuer?: string;
+  /** Por defecto `SSO_CLIENT_ID`. */
+  clientId?: string;
+  /** Por defecto `SSO_CLIENT_SECRET`. */
+  clientSecret?: string;
+
+  /**
+   * Clave para cifrar la cookie de sesión. Mínimo 32 caracteres.
+   * Por defecto `SSO_SECRET`.
+   *
+   * La cookie guarda el access token. Cifrarla evita que acabe legible en un
+   * volcado de memoria, en un log de proxy o en una copia de seguridad del
+   * navegador.
+   */
+  secret?: string;
+
+  /**
+   * Espejo del catálogo que el portal declara para esta aplicación.
+   *
+   * El portal define los permisos (cadenas opacas: las almacena, las agrupa en
+   * roles y las emite como claim) y la aplicación les da significado al
+   * exigirlos con `can()`, `protectPage()`, `action()` o `<Protect>`. Esta
+   * lista no declara nada: si se pasa como tupla `as const`, `can()`
+   * autocompleta y un permiso mal escrito es un error de compilación en lugar
+   * de un `false` silencioso en producción.
+   *
+   * Declara primero en la consola del portal; lo que llegue sin declarar,
+   * simplemente nunca aparece en la sesión.
+   */
+  permissions?: readonly Permission[];
+
+  /** Ruta donde se montan los handlers. Por defecto `/api/sso`. */
+  basePath?: string;
+
+  /**
+   * URL pública de la aplicación consumidora. Solo explícita, nunca del
+   * entorno: el `redirect_uri` debe coincidir EXACTAMENTE con el registrado en
+   * el portal, y adivinarlo desde una variable global es como se acaba
+   * enviando el puerto equivocado.
+   *
+   * Opcional: se deduce de la petición entrante. Indícala si la aplicación vive
+   * detrás de un proxy que no reescribe `X-Forwarded-Host`, o si necesitas
+   * construir enlaces fuera del ciclo de una petición.
+   */
+  appUrl?: string;
+
+  /**
+   * A dónde vuelve el navegador tras cerrar la sesión en el portal.
+   * Por defecto `SSO_POST_LOGOUT_URI`.
+   *
+   * Por defecto, la raíz de la aplicación. **Tiene que estar registrada en el
+   * portal como URI de cierre de sesión** y coincidir exactamente: el endpoint
+   * de cierre solo redirige a URIs que un administrador dio de alta.
+   */
+  postLogoutRedirectUri?: string;
+
+  /** Por defecto `["openid", "profile", "email"]`. */
+  scopes?: string[];
+
+  /** Nombre de la cookie de sesión. Por defecto `__Host-sso_session`. */
+  cookieName?: string;
+
+  /** Duración de la sesión local, en segundos. Por defecto 7 días. */
+  sessionMaxAge?: number;
+};
+
+/** Métodos de autenticación, con los valores del RFC 8176. */
+export type AuthMethod = "pwd" | "otp" | "swk" | "mfa" | (string & {});
+
+export type SSOUser = {
+  /** Identificador estable. Úsalo como clave, no el correo. */
+  id: string;
+  email: string;
+  emailVerified: boolean;
+  name: string | null;
+  image: string | null;
+};
+
+export type SSOSession<Permission extends string = string> = {
+  user: SSOUser;
+
+  roles: string[];
+  permissions: Permission[];
+
+  /** Con qué se autenticó esta sesión. */
+  amr: AuthMethod[];
+
+  accessToken: string;
+  /** Marca de tiempo Unix en la que caduca el acceso. */
+  expiresAt: number;
+
+  /**
+   * Si el `access_token` ya caducó.
+   *
+   * Dura 15 minutos, muy poco frente a la vida de la cookie. Llamar a una API
+   * con un token caducado da 401, así que conviene consultarlo antes —o dejar
+   * que `session({ revalidate: true })` o `action()` lo renueven.
+   */
+  isExpired(): boolean;
+
+  /** Si la sesión tiene el permiso indicado. */
+  can(permission: Permission): boolean;
+  /** Si los tiene todos. */
+  canAll(...permissions: Permission[]): boolean;
+  /** Si tiene al menos uno. */
+  canAny(...permissions: Permission[]): boolean;
+
+  /** Lanza `SSOForbiddenError` si falta el permiso. */
+  requires(permission: Permission): void;
+
+  /** Si la autenticación usó más de un factor. */
+  usedSecondFactor(): boolean;
+};
+
+/** Documento de descubrimiento OIDC, con los campos que usa el cliente. */
+export type DiscoveryDocument = {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint: string;
+  jwks_uri: string;
+  end_session_endpoint?: string;
+  revocation_endpoint?: string;
+  introspection_endpoint?: string;
+};