@nexmax/maxloop-kernel-js

Shared microservice infrastructure for Node.js services in the Maxloop ecosystem. Provides JWT authentication, RBAC authorization, multi-tenancy, service connectors, Redis caching, N8n notifications, structured logging with Loki, and framework-agnostic middleware with adapters for Fastify and NestJS.

Ported from the Laravel PHP package glc36/maxloop-kernel. Wire-compatible -- JWT tokens, HMAC signatures, Redis cache keys, and API payloads are identical across both runtimes.

Installation

npm install @nexmax/maxloop-kernel-js

Or install from a local path during development:

npm install ../path/to/maxloop-kernel-js

Peer Dependencies

Install the Redis client in your application:

npm install ioredis

Optional -- cache, JWT cache, auth-context cache, and security cache features will be disabled if ioredis is not installed.

Quick Start

import { createKernel } from '@nexmax/maxloop-kernel-js';
import Redis from 'ioredis';

const redis = new Redis({ host: 'localhost', port: 6379 });

const kernel = createKernel({
  redis: { client: redis },
});

Environment Variables

The package reads the same environment variables as the PHP kernel. See docs/INTEGRATION.md for the full list.

MICROSERVICE_NAME=my-service
MICROSERVICE_JWT_SIGNATURE=your-jwt-secret
MICROSERVICE_SHARED_TOKEN=your-shared-token
CONNECTOR_BASE_URL=https://api.example.com

Framework Integration

Framework adapters are available as sub-path imports:

import { createFastifyPlugin } from '@nexmax/maxloop-kernel-js/adapters/fastify';
import { MAXLOOP_KERNEL, PERMISSIONS_KEY } from '@nexmax/maxloop-kernel-js/adapters/nestjs';

Detailed guides:

• NestJS -- See docs/INTEGRATION.md
• Fastify -- See docs/INTEGRATION.md

API Overview

| Service | Access | Description | |---------|--------|-------------| | JWT | kernel.jwt | Sign, validate, refresh JWT tokens (HS256) | | Auth Context | kernel.authContext | RBAC context with Redis cache | | Cache | kernel.cache(key) | Redis cache with TTL, locks, remember pattern | | CAS Connector | kernel.connectors.cas | CAS authentication service | | Media Connector | kernel.connectors.media | File upload/retrieve/delete | | GS Connector | kernel.connectors.gs | Currencies and timezones | | Security | kernel.security | 2FA policy enforcement | | Notifications | kernel.notifications | N8n notification delivery | | Logger | kernel.logger | Structured logging via Loki |

Build & Test

npm run build         # tsup -- ESM + CJS + DTS
npm test              # vitest
npm run test:coverage # 80% threshold
npm run lint          # eslint
npm run typecheck     # tsc --noEmit

Documentation

| Document | Description | |----------|-------------| | USAGE.md | Function-by-function usage reference (cache, JWT, connectors, notifications, etc.) | | INTEGRATION.md | Framework integration guides (NestJS, Fastify) | | MIGRATION_GUIDE.md | PHP to TypeScript migration | | API_REFERENCE.md | PHP-to-TypeScript method mapping | | ARCHITECTURE.md | Directory structure, design decisions |

License

UNLICENSED