@dacyti-gsi/auth 0.3.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.3.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",
@@ -65,7 +65,7 @@
     "@dacyti-gsi/config": "^0.1.0",
     "@types/node": "^20.19.43",
     "@types/react": "^19",
-    "next": "16.4.0",
+    "next": "16.4.2",
     "react": "19.3.0",
     "typescript": "^5",
     "vitest": "^4.1.10"

package/src/config.ts

@@ -78,7 +78,10 @@ function isLocalhost(url: URL): boolean {
 function isSecureOrLocal(value: string): boolean {
   try {
     const url = new URL(value);
-    return url.protocol === "https:" || (url.protocol === "http:" && isLocalhost(url));
+    return (
+      url.protocol === "https:" ||
+      (url.protocol === "http:" && isLocalhost(url))
+    );
   } catch {
     return false;
   }

package/src/core.ts

@@ -446,3 +446,64 @@ export function refreshOnce(
 
   return pending;
 }
+
+/**
+ * Envía el manifiesto (permisos y roles) de la aplicación al portal.
+ *
+ * Autentica con `client_secret_basic`, las mismas credenciales con las que ya se
+ * canjean los códigos. El portal lo aplica de forma idempotente y solo sobre el
+ * catálogo de este `clientId`, así que se puede llamar en cada arranque.
+ */
+export async function syncManifest(input: {
+  issuer: string;
+  clientId: string;
+  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(
+    `${input.clientId}:${input.clientSecret}`,
+  ).toString("base64");
+
+  const response = await portalFetch(endpoint.toString(), {
+    method: "POST",
+    headers: {
+      authorization: `Basic ${credentials}`,
+      "content-type": "application/json",
+    },
+    body: JSON.stringify({
+      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],
+      })),
+    }),
+  });
+
+  const payload = (await response.json().catch(() => ({}))) as Record<
+    string,
+    unknown
+  >;
+
+  if (!response.ok) {
+    throw new SSOProtocolError(
+      `El portal rechazó el manifiesto (HTTP ${response.status}): ${String(payload.message ?? payload.error ?? "sin detalle")}`,
+      payload,
+      response.status,
+    );
+  }
+
+  return {
+    permissions: Number(payload.permissions ?? 0),
+    roles: Number(payload.roles ?? 0),
+  };
+}

package/src/index.ts

@@ -8,6 +8,7 @@ import {
   refreshOnce,
   refreshTokens,
   sessionFromPayload,
+  syncManifest,
   type TokenSet,
 } from "./core";
 import { isCredentialRejected, SSOError } from "./errors";
@@ -17,7 +18,7 @@ import {
   type SessionPayload,
   sealSession,
 } from "./session-cookie";
-import type { SSOClientOptions, SSOSession } from "./types";
+import type { SSOClientOptions, SSOSession, SyncResult } from "./types";
 
 export {
   type ResolvedSSOOptions,
@@ -46,6 +47,7 @@ export type {
   SSOClientOptions,
   SSOSession,
   SSOUser,
+  SyncResult,
 } from "./types";
 
 /**
@@ -150,6 +152,15 @@ export type SSOClient<Permission extends string = string> = {
 
   /** Atiende las rutas del cliente. Devuelve `null` si la ruta no le compete. */
   handleRequest(request: Request): Promise<Response | null>;
+
+  /**
+   * Declara en el portal los `permissions` y `roles` de esta aplicación.
+   *
+   * Es idempotente y solo toca el catálogo de este cliente: llámalo en cada
+   * arranque (p. ej. desde `instrumentation.ts`) y la consola refleja siempre lo
+   * que el código exige. No asigna roles a cuentas.
+   */
+  sync(): Promise<SyncResult>;
 };
 
 /**
@@ -640,6 +651,16 @@ export function defineSSO<const Permission extends string = string>(
 
     resolveSession,
 
+    sync: () =>
+      syncManifest({
+        issuer: resolved.issuer,
+        clientId: resolved.clientId,
+        clientSecret: resolved.clientSecret,
+        permissions: resolved.permissions ?? [],
+        roles: resolved.roles ?? {},
+        descriptions: resolved.descriptions,
+      }),
+
     async handleRequest(request) {
       const { pathname } = new URL(request.url);
       if (!pathname.startsWith(`${basePath}/`)) return null;

package/src/types.ts

@@ -47,6 +47,30 @@ export type SSOClientOptions<Permission extends string = string> = {
    */
   permissions?: readonly Permission[];
 
+  /**
+   * Roles de la aplicación y los permisos que agrupa cada uno.
+   *
+   * Junto con `permissions`, es el manifiesto que `sso.sync()` envía al portal:
+   * declarar aquí evita copiarlos a mano en la consola. Los permisos de cada
+   * rol salen del mismo tipo que `permissions`, así que una errata no compila.
+   * Sincronizar solo declara el catálogo; a quién se asigna cada rol se sigue
+   * decidiendo en la consola.
+   */
+  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;
 
@@ -139,3 +163,6 @@ export type DiscoveryDocument = {
   revocation_endpoint?: string;
   introspection_endpoint?: string;
 };
+
+/** Lo que el portal respondió al sincronizar el manifiesto. */
+export type SyncResult = { permissions: number; roles: number };