@envisiongroup/create-alakazam 0.1.1 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envisiongroup/create-alakazam",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "type": "module",
   "description": "CLI para generar proyectos Mastra cliente sobre @envisiongroup/alakazam (agents hub con auth, storage y rutas ya cableadas).",
   "license": "SEE LICENSE IN LICENSE",

package/templates/default/.env.sample

@@ -37,6 +37,9 @@ AUTH_DISABLED=false
 # true → bypass de auth solo para Mastra Studio (same-origin, sin Bearer).
 # Recomendado en local. En producción debe quedar sin setear (o false).
 STUDIO_AUTH_BYPASS=true
+# ¿Llamadas servicio-a-servicio (M2M) sin usuario interactivo? No uses estos
+# flags: ver las variantes comentadas en src/mastra/index.ts (endpoints
+# públicos puntuales / provider app-only en src/mastra/auth/).
 
 # ── CORS ────────────────────────────────────────────────────────────────────
 # Lista de orígenes permitidos separados por coma (tu SPA en local):

package/templates/default/src/mastra/access/role-rules.ts

@@ -19,6 +19,10 @@ import type { RoleRule } from '@envisiongroup/alakazam';
  * { when: { provider: 'google', domain: 'envisiongroup.com' }, grant: 'employee' },
  * // Email directo → rol (útil para admins puntuales):
  * { when: { email: 'admin@envisiongroup.com' }, grant: 'hub-admin' },
+ * // Servicio M2M (app-only Entra, provider 'entra-service' del ejemplo
+ * // `auth/service-identity-provider.ts`; el `user` es el Object ID del
+ * // service principal llamante):
+ * { when: { provider: 'entra-service', user: '<OBJECT-ID-DEL-SP>' }, grant: 'mi-rol-servicio' },
  * ```
  *
  * Requiere que la App Registration de la API tenga configurado

package/templates/default/src/mastra/auth/service-identity-provider.ts

@@ -0,0 +1,217 @@
+/**
+ * EJEMPLO: autenticación servicio-a-servicio (M2M) junto al login de usuario.
+ *
+ * Por default el hub solo acepta tokens de USUARIO delegados de Entra ID
+ * (flujo interactivo del SPA, claim `scp` con `access_as_user`). Este archivo
+ * muestra cómo aceptar ADEMÁS tokens **app-only** emitidos por Entra para
+ * otra aplicación (client credentials flow), de modo que un servicio X
+ * (un backend, un job, una Azure Function, …) pueda invocar agents con su
+ * propia identidad, sin usuario interactivo y SIN desactivar la auth.
+ *
+ * ─── ¿Por qué UN provider compuesto y no dos providers? ────────────────────
+ *
+ * Con varios providers, el hub elige cuál valida cada token por su claim
+ * `iss` (routing multi-IdP). Pero un token app-only del MISMO tenant tiene
+ * exactamente el mismo `iss` que un token de usuario — el routing no puede
+ * distinguirlos. Por eso este provider se registra como ÚNICO provider y
+ * discrimina por la FORMA del token:
+ *
+ *   - token SIN claim `scp` (o con `idtyp: 'app'`)  → app-only: se valida
+ *     aquí (firma + issuer + audience + app role requerido).
+ *   - cualquier otro token → se delega intacto al provider de usuario de
+ *     siempre (`EntraIdentityProvider`), conservando la semántica 401/403
+ *     original para el SPA.
+ *
+ * ─── Alta en Microsoft Entra (una vez, por servicio llamante) ──────────────
+ *
+ *  1. En la App Registration DE ESTA API (la de `AZURE_API_CLIENT_ID`):
+ *     "App roles" → crear rol con `allowedMemberTypes: ['Applications']`,
+ *     value `Hub.Invoke` (o el que pases como `requiredAppRole`).
+ *  2. En la App Registration DEL SERVICIO llamante: "API permissions" →
+ *     "Application permissions" → agregar el rol `Hub.Invoke` de tu API →
+ *     conceder admin consent.
+ *  3. El servicio pide token con client credentials:
+ *       POST https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token
+ *       grant_type=client_credentials
+ *       client_id=<app-del-servicio>&client_secret=<...>
+ *       scope=api://<AZURE_API_CLIENT_ID>/.default
+ *     y llama al hub con `Authorization: Bearer <token>`.
+ *
+ * ─── Identidad resultante y roles ──────────────────────────────────────────
+ *
+ * El `subject` de la identidad es el Object ID del service principal llamante
+ * (claim `sub`; fallback `azp`). Ese subject pasa a ser el
+ * `MASTRA_RESOURCE_ID_KEY` de la request: memoria, threads y ownership de
+ * runs quedan aislados POR SERVICIO, igual que por usuario.
+ *
+ * La identidad se reporta con `provider: 'entra-service'` para que el
+ * `roleResolver` pueda otorgar roles distintos a servicios que a usuarios
+ * (ver `access/role-rules.ts`):
+ *
+ *   { when: { provider: 'entra-service', user: '<OBJECT-ID-DEL-SP>' }, grant: 'mi-rol-servicio' },
+ *
+ * Nota: si lo que buscas es NO exigir credencial alguna (red privada, dev),
+ * no necesitas un provider — usa los flags `AUTH_DISABLED` /
+ * `config.publicPaths` (ver los comentarios de `src/mastra/index.ts`).
+ */
+import { createRemoteJWKSet, jwtVerify } from 'jose';
+import {
+    AuthError,
+    entraIdentityProvider,
+    type EntraIdentityProvider,
+    type HubIdentity,
+    type IdentityProvider,
+} from '@envisiongroup/alakazam';
+
+/** Nombre del provider en la identidad resultante (lo usan las RoleRules). */
+export const ENTRA_SERVICE_PROVIDER_NAME = 'entra-service' as const;
+
+/**
+ * JWKS del tenant (mismo endpoint que el flujo de usuario). `new URL` no
+ * puede fallar con un tenant sano, pero validamos para reportar config
+ * rota como error de servidor y no como excepción suelta en el arranque.
+ */
+const buildTenantJwks = (tenantId: string) => {
+    try {
+        return createRemoteJWKSet(
+            new URL(
+                `https://login.microsoftonline.com/${tenantId}/discovery/v2.0/keys`,
+            ),
+        );
+    } catch (error) {
+        throw new AuthError(
+            `Invalid tenant id for JWKS URL: ${error instanceof Error ? error.message : error}`,
+            500,
+        );
+    }
+};
+
+export type EntraServiceIdentityProviderOptions = {
+    /** Tenant de Entra ID. Default: env AZURE_API_TENANT_ID. */
+    tenantId?: string;
+    /**
+     * Audience exigido: la App Registration de esta API.
+     * Default: env AZURE_API_CLIENT_ID (se acepta GUID y `api://<GUID>`,
+     * igual que en el flujo de usuario).
+     */
+    apiClientId?: string;
+    /**
+     * App role (application permission) que el token del servicio debe
+     * incluir en su claim `roles`. Default: 'Hub.Invoke'.
+     */
+    requiredAppRole?: string;
+};
+
+export class EntraServiceIdentityProvider implements IdentityProvider {
+    /**
+     * Se registra como provider único: el routing por `iss` no entra en
+     * juego (con un solo provider el hub lo usa directamente). El nombre
+     * del provider de USUARIOS sigue siendo 'entra' en sus identidades;
+     * las identidades app-only salen de aquí con 'entra-service'.
+     */
+    readonly provider = 'entra';
+    readonly issuers: readonly string[];
+
+    readonly #apiClientId: string;
+    readonly #requiredAppRole: string;
+    readonly #jwks: ReturnType<typeof createRemoteJWKSet>;
+    readonly #userProvider: EntraIdentityProvider;
+
+    constructor(options: EntraServiceIdentityProviderOptions = {}) {
+        const tenantId =
+            options.tenantId ?? process.env.AZURE_API_TENANT_ID ?? '';
+        this.#apiClientId =
+            options.apiClientId ?? process.env.AZURE_API_CLIENT_ID ?? '';
+        this.#requiredAppRole = options.requiredAppRole ?? 'Hub.Invoke';
+
+        // Mismos issuers y JWKS que el flujo de usuario (mismo tenant):
+        // v2.0 y v1.0, según `accessTokenAcceptedVersion` de cada app.
+        this.issuers = tenantId
+            ? [
+                  `https://login.microsoftonline.com/${tenantId}/v2.0`,
+                  `https://sts.windows.net/${tenantId}/`,
+              ]
+            : [];
+        this.#jwks = buildTenantJwks(tenantId);
+        this.#userProvider = entraIdentityProvider(
+            options.tenantId ? { tenantId: options.tenantId } : {},
+        );
+    }
+
+    async validateToken(token: string): Promise<HubIdentity> {
+        const serviceIdentity = await this.#tryValidateServiceToken(token);
+        if (serviceIdentity) {
+            return serviceIdentity;
+        }
+        // Token de usuario delegado (o token inválido): flujo de siempre,
+        // que produce los mismos 401/403 que sin este provider.
+        return this.#userProvider.validateToken(token);
+    }
+
+    /**
+     * Valida el token como app-only (client credentials). Devuelve `null`
+     * cuando el token NO es app-only (tiene `scp` → es de usuario, o no
+     * verifica → el flujo de usuario reportará el error adecuado).
+     */
+    async #tryValidateServiceToken(token: string): Promise<HubIdentity | null> {
+        if (!this.#apiClientId || this.issuers.length === 0) {
+            return null;
+        }
+
+        let payload;
+        try {
+            ({ payload } = await jwtVerify(token, this.#jwks, {
+                issuer: [...this.issuers],
+                audience: [this.#apiClientId, `api://${this.#apiClientId}`],
+            }));
+        } catch {
+            return null;
+        }
+
+        // Los tokens de usuario delegados SIEMPRE traen `scp` (scopes);
+        // los app-only traen `roles` (app roles) y, en v2.0, `idtyp: 'app'`.
+        const isAppOnly =
+            payload.idtyp === 'app' || typeof payload.scp !== 'string';
+        if (!isAppOnly) {
+            return null;
+        }
+
+        const roles = Array.isArray(payload.roles)
+            ? payload.roles.filter(
+                  (role: unknown): role is string => typeof role === 'string',
+              )
+            : [];
+        if (!roles.includes(this.#requiredAppRole)) {
+            throw new AuthError(
+                `Token missing required app role: ${this.#requiredAppRole}`,
+                403,
+            );
+        }
+
+        // En tokens app-only, `sub` es el Object ID del service principal
+        // llamante; `azp` es el Client ID de su app (fallback).
+        const subject = payload.sub ?? (payload.azp as string | undefined);
+        if (!subject) {
+            throw new AuthError('Token missing sub claim', 401);
+        }
+        const tenantId = payload.tid as string | undefined;
+        if (!tenantId) {
+            throw new AuthError('Token missing tid claim', 401);
+        }
+
+        return {
+            provider: ENTRA_SERVICE_PROVIDER_NAME,
+            subject,
+            email: '', // app-only: no hay email de usuario
+            principals: [
+                { kind: 'user', id: subject },
+                { kind: 'domain', id: tenantId },
+            ],
+            raw: payload,
+        };
+    }
+}
+
+export const entraServiceIdentityProvider = (
+    options: EntraServiceIdentityProviderOptions = {},
+): EntraServiceIdentityProvider => new EntraServiceIdentityProvider(options);

package/templates/default/src/mastra/index.ts

@@ -45,3 +45,54 @@ export const mastra = await createAgentsHub({
         roleResolver: staticRoleResolver(ROLE_RULES),
     },
 });
+
+// --- Autenticación: variantes para clientes sin usuario interactivo ---------
+// Por defecto, todo lo bajo `/api/*` (rutas nativas de Mastra) y `/app/*`
+// (rutas custom) exige un Bearer token de usuario de Entra ID. El hub
+// soporta tres variantes para escenarios distintos (p. ej. que un servicio
+// X — otro backend, un job, una Function— llame a los agents):
+//
+// A) APAGADO TOTAL — solo emergencias/debug, NUNCA en producción.
+//      En `.env`:  AUTH_DISABLED=true
+//    Ninguna ruta exige token y el catálogo (`/app/agents/catalog`) lista
+//    TODOS los recursos sin filtrar por roles. No hay usuario autenticado:
+//    se degrada el aislamiento por usuario (threads/runs sin ownership,
+//    pinned agents, uploads/downloads). No requiere AZURE_API_*.
+//
+// B) ENDPOINTS PÚBLICOS PUNTUALES — un caller sin token accede solo a lo
+//    que declares; el resto del hub sigue exigiendo Entra. Es el mismo
+//    patrón que usa `/app/files` (donde el downloadId opaco es el credential):
+//
+//      export const mastra = await createAgentsHub({
+//          // ... agents, tools, workflows, auth, ...
+//          config: {
+//              // Path exacto público (p. ej. el stream nativo de UN agente):
+//              publicPaths: ['/api/agents/weather-agent/stream'],
+//              // …o prefijos completos (todo lo del agente):
+//              // publicPathPrefixes: ['/api/agents/weather-agent/'],
+//          },
+//      });
+//
+//    Ojo: lo que publiques así queda SIN credencial — compensa a nivel de
+//    red (VNet, firewall, API Management) si lo expones fuera de localhost.
+//
+// C) SERVICIO A SERVICIO CON CREDENCIAL (recomendado para M2M) — el servicio
+//    X se autentica con client credentials de Entra (token app-only) y el hub
+//    lo valida como una identidad propia, con roles y aislamiento por
+//    servicio. Implementación de ejemplo lista para adaptar en
+//    `./auth/service-identity-provider.ts` (incluye el alta paso a paso en
+//    Entra). Se registra como provider ÚNICO — él mismo distingue tokens
+//    app-only de tokens de usuario del mismo tenant:
+//
+//      import { entraServiceIdentityProvider } from './auth/service-identity-provider';
+//      ...
+//      auth: {
+//          providers: [entraServiceIdentityProvider()],
+//          roleResolver: staticRoleResolver(ROLE_RULES),
+//      },
+//
+//    Roles para la identidad del servicio: ver `./access/role-rules.ts`.
+//
+// No uses STUDIO_AUTH_BYPASS para esto: ese flag es solo para Mastra Studio
+// en local (un caller server-to-server sin header Origin también pasaría el
+// bypass — en producción debe quedar sin setear).