@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 |

Auth Error Diagnostics

ApiClientHandler and AuthContextHandler catch internal failures (Redis errors, CAS network errors) and fall back to their normal "unauthenticated" result rather than throwing into your request handler. By default those failures are silent. Pass onAuthError to createKernel() to observe them without changing any behavior:

const kernel = createKernel({
  redis: { client: redis },
  onAuthError: (error, context) => {
    // context.stage identifies which internal step failed, e.g.
    // 'apiClientHandler.validateApiClient' or 'authContextHandler.fetchContext'
    logger.warn({ ...context, error: (error as Error)?.message }, 'kernel auth error');
  },
});

The hook is purely observational -- it never affects control flow -- and never receives secret_key or other sensitive cached fields, only the error and a small identifying context (stage, plus publicKey or uuid/authGuard).

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 | |----------|-------------| | CHANGELOG.md | Version history and notable changes | | 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 |

Notable Fixes

ML-44 -- Concurrent API client / auth context requests could cross-contaminate

Issue: ApiClientHandler and AuthContextHandler were constructed once per process (createKernel()) and shared by every in-flight request. Both store the current request's identity (publicKey, or uuid/authGuard) as mutable instance state, re-read lazily across await boundaries. Under real concurrent load, one request's setPublicKey()/setUuid() could overwrite another's mid-flight, so a slower request could resume and validate against -- or read the cached secret of -- a different client. No malformed or malicious input was required; two honest clients calling at the same moment was enough. This showed up as intermittent, unexplained 401s and a risk of Redis cache poisoning (cas.api_clients.* written under the wrong key).

Fix: createFastifyPlugin()'s apiClientAuth/authContext/authorization hooks now construct a fresh handler instance per request (wired to the same shared CAS connector) instead of reusing the kernel's singleton apiClientHandler/authContext. ApiClientHandler and AuthContextHandler themselves are unchanged -- the fix is entirely in how the Fastify adapter wires them, so it applies transparently to both the Fastify and NestJS adapters with no consumer-facing API changes.

Also added: the onAuthError diagnostic hook (see Auth Error Diagnostics above) and distinct internal error messages in createApiClientAuthMiddleware, so failures that previously collapsed into one generic "Invalid API client credentials" 401 -- CAS/Redis blips vs. a genuinely unknown client vs. a cache-read failure after successful validation -- can now be told apart server-side.

Regression coverage: tests/unit/adapters/fastify-plugin.api-client-auth.concurrency.test.ts drives the real adapter hook with two concurrent clients and asserts neither is cross-contaminated.

License

UNLICENSED