@dacyti-gsi/auth 0.4.0 → 0.5.0

package/README.md

@@ -88,6 +88,48 @@ El portal solo redirige a URIs registradas, así que sin ella la sesión se cier
 igual pero el navegador se queda en el portal. Si la registras, indícala también
 en `postLogoutRedirectUri`.
 
+## Declarar permisos y roles desde el código (`sso.sync()`)
+
+El catálogo de la app vive en su código y se declara solo en el portal, sin copiarlo
+a mano a la consola:
+
+```ts
+// lib/sso.ts
+export const sso = defineNextSSO({
+  permissions: ["pedidos:ver", "pedidos:anular"] as const,
+  roles: {
+    gerente: ["pedidos:ver", "pedidos:anular"],
+    lector: ["pedidos:ver"],
+  },
+  // Lo que la consola muestra al decidir a quién dar cada cosa.
+  descriptions: {
+    permissions: { "pedidos:anular": "Anular pedidos ya confirmados" },
+    roles: { gerente: "Gestiona los pedidos de su sucursal" },
+  },
+});
+```
+
+```ts
+// instrumentation.ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== "nodejs") return;
+  const { sso } = await import("@/lib/sso");
+  await sso.sync().catch((error) => console.warn("[sso] sin sincronizar:", error));
+}
+```
+
+- Los permisos de cada rol salen del tipo de `permissions`, y las claves de
+  `descriptions` también: una errata no compila.
+- Es idempotente y solo toca el catálogo de este `clientId` (autentica con las mismas
+  credenciales del cliente, `client_secret_basic`). Se puede llamar en cada arranque.
+- Declara el catálogo; **no asigna roles a cuentas**, eso se decide en la consola.
+- No borra: un permiso o rol que quitas del código sigue en la consola hasta que
+  alguien lo elimina allí.
+- Todo o nada: si un rol pide un permiso que no está en el catálogo, el portal rechaza
+  el manifiesto entero y `sync()` lanza con el motivo.
+- Un rol que incluya `sso:asignar-roles` permite a su titular asignar roles de esta
+  app desde su cuenta, sin ser administrador del portal.
+
 ## Renovar el acceso (`proxy.ts`)
 
 El acceso dura 15 minutos. Los Server Components no pueden escribir cookies, así que

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dacyti-gsi/auth",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Cliente del SSO de la división: OIDC (PKCE), sesión y permisos para Next.js/React",
   "keywords": [
     "sso",

package/src/core.ts

@@ -460,6 +460,10 @@ export async function syncManifest(input: {
   clientSecret: string;
   permissions: readonly string[];
   roles: Readonly<Record<string, readonly string[]>>;
+  descriptions?: {
+    permissions?: Readonly<Record<string, string | undefined>>;
+    roles?: Readonly<Record<string, string | undefined>>;
+  };
 }): Promise<{ permissions: number; roles: number }> {
   const endpoint = new URL("/api/apps/manifest", input.issuer);
   const credentials = Buffer.from(
@@ -473,10 +477,14 @@ export async function syncManifest(input: {
       "content-type": "application/json",
     },
     body: JSON.stringify({
-      permissions: input.permissions.map((key) => ({ key })),
+      permissions: input.permissions.map((key) => ({
+        key,
+        description: input.descriptions?.permissions?.[key],
+      })),
       roles: Object.entries(input.roles).map(([name, permissions]) => ({
         name,
         permissions,
+        description: input.descriptions?.roles?.[name],
       })),
     }),
   });

package/src/index.ts

@@ -658,6 +658,7 @@ export function defineSSO<const Permission extends string = string>(
         clientSecret: resolved.clientSecret,
         permissions: resolved.permissions ?? [],
         roles: resolved.roles ?? {},
+        descriptions: resolved.descriptions,
       }),
 
     async handleRequest(request) {

package/src/types.ts

@@ -58,6 +58,19 @@ export type SSOClientOptions<Permission extends string = string> = {
    */
   roles?: Readonly<Record<string, readonly Permission[]>>;
 
+  /**
+   * Descripciones legibles de permisos y roles, para la consola del portal.
+   *
+   * `sso.sync()` las envía junto al manifiesto; sin ellas la consola solo muestra
+   * claves como `pedidos:anular`, que no dicen qué concede cada una a quien debe
+   * decidir a quién dárselo. Las claves de `permissions` salen del mismo tipo que
+   * `permissions`: una descripción para un permiso que no existe no compila.
+   */
+  descriptions?: {
+    permissions?: Partial<Record<Permission, string>>;
+    roles?: Readonly<Record<string, string>>;
+  };
+
   /** Ruta donde se montan los handlers. Por defecto `/api/sso`. */
   basePath?: string;