@js-maia/auth (MAIA-AUTH)

Módulo local (in-process) Ring 1 — MAIA-Security. Instala ICoreGuards en @js-maia/core durante initialize() vía context.security.setGuards().

Estado (@js-maia/[email protected] — Guards+P2P consolidación; R16; R14; R13)

• moduleId: maia-auth
• manifest: type: "security", critical: true, autostart: true, ring: 1, peerPort (registry Core, default 3190 alineado con JWKS)
• capabilities: security, guards, p2p-token, jwks
• guards: canDecideCommunication (8 canales R14 + metadata R16 opcional), canRegister, canConnect, canIssuePeerToken
• fail-closed: false o throw ⇒ denegado (Core responde FORBIDDEN al remoto y loggea)

Instalación

bun add @js-maia/auth

Recomendado: @js-maia/auth@^1.7.0 con @js-maia/core@^0.5.1. R16: boundary + MAIA_AUTH_BOUNDARY_FACETS (default off). R14: canDecideCommunication (8 canales). R13/P2P: peer tokens + JWKS + peerPort en manifest (Roadmap 10).

R16 — fronteras inter-anillo (opt-in)

Core puede enviar en canDecideCommunication:

| Campo | Ejemplo | Uso | | --------------------------- | ----------- | ------------------------------------ | | boundary | "3→2" | Frontera cruzada (vocabulario Core) | | sourceRing / targetRing | 3, 2 | Anillos explícitos | | authFacet | "auth-r3" | Facet lógico en logs (no módulo npm) |

Flag AUTH: MAIA_AUTH_BOUNDARY_FACETS

| Valor | Comportamiento | | ------------------------- | -------------------------------------------------------------------------------------- | | unset / false (default) | Sin evaluación boundary — igual que 1.5.x | | true | Policy v1: mismo anillo OK; cross-ring solo ±1 hop; deny boundary inválido o multi-hop |

No breaking si el flag permanece apagado. Roadmap: 8-R16.

P2P peer tokens (R13 / Roadmap 10)

| Variable | Default | Efecto | | --------------------------------------------- | ------- | ----------------------------------------------------------------------------- | | MAIA_AUTH_JWKS_PORT / MAIA_AUTH_PEER_PORT | 3190 | HTTP JWKS; peerPort manifest (si no se define PEER_PORT, usa puerto JWKS) | | MAIA_AUTH_JWKS_PUBLIC_URL | — | URL pública JWKS para Core E2E | | MAIA_AUTH_PEER_TOKEN_SAME_RING_ONLY | off | Deny emisión cross-ring si rings conocidos | | MAIA_AUTH_MODULE_RINGS | — | JSON moduleId → ring para policy P2P |

Manifest incluye peerPort + peerEndpoint (ws://host:port/peer) para sincronización del registry Core. AUTH no implementa broker MCP2P — solo emisor JWT + JWKS.

Scopes denegados por defecto: core.*, system.*.

Uso (Core)

El Core cargará el módulo como local IModule y, al arrancar, MAIA-AUTH instalará los guards.

Política (MVP)

Política mínima allow/deny basada en patrones:

• Deny publish a system.shutdown y core.*
• Deny route a core.*
• Deny subscribe a system.shutdown y core.*

Todo lo demás: allow.

Matriz de política (MVP)

| Operación | Topic/Pattern | Decisión | Reason | Code | | ----------- | --------------------------------------- | ------------------- | --------------------------------------- | ----------- | | publish | system.shutdown | deny | publish-topic-denied-by-policy | FORBIDDEN | | publish | core.* | deny | publish-topic-denied-by-policy | FORBIDDEN | | route | core.* | deny | route-topic-denied-by-policy | FORBIDDEN | | subscribe | system.shutdown | deny | subscribe-pattern-denied-by-policy | FORBIDDEN | | subscribe | core.* | deny | subscribe-pattern-denied-by-policy | FORBIDDEN | | publish | throwPublishTopics (configurable) | throw (fail-closed) | publish-topic-configured-to-throw | FORBIDDEN | | route | throwRouteTopics (configurable) | throw (fail-closed) | route-topic-configured-to-throw | FORBIDDEN | | subscribe | throwSubscribePatterns (configurable) | throw (fail-closed) | subscribe-pattern-configured-to-throw | FORBIDDEN |

Cuando una operación es denegada o configurada para throw, AUTH emite maia-auth.denied con payload tipado MaiaSecurityDenied (kind, schemaVersion: "1.0", code, operation, moduleId, topic/pattern, reason). Sin secretos ni cuerpo WS. Ver contrato deny.

Roadmap activo

• Roadmap 8 — R16 boundary facets (↔ Core R16)
• Roadmap 7 — R14 guards (completado — 1.5.0)
• Roadmap 6 — R13 P2P
• Roadmap 5 — Gateway E/S (↔ Core R12)

Desarrollo

bun install
bun run check          # lint + typecheck + validate:module + tests
bun run check:prepublish
bun run build

Tras publicar en npm: bun run verify:published (comprueba que el registry coincide con package.json).