@xemahq/xema-service-nest

This package belongs to Layer 1 — Kernel SDKs (the sanctioned SDK-tier aggregate). It composes sibling Layer-1 SDKs and Layer-0 contracts into a single platform-service bootstrap; nothing in Layer 0 or the individual SDKs may depend on it (the dependency edge runs downward only).

XemaServiceModule.forBiome(descriptor) wires the entire platform service stack behind one call so a biome API is auth-correct in ~5 lines and never re-wires authentication. It composes — it does not reimplement:

| Concern | Composed module | | --- | --- | | Self-registration + typed peer clients | @xemahq/service-registry-nest | | Service token mint/refresh + Keycloak config | @xemahq/identity-client | | Global JWT verification + request context | @xemahq/platform-common (AuthModule) | | Fail-closed route/capability decorator scan | @xemahq/xema-decorators (XemaRuntimeModule) |

Usage

The descriptor is generated from the biome's xema-biome.json by tooling/codegen/generate-service-bootstrap.mjs — you declare name/version/ dependencies once in the manifest, never again in app.module.ts.

import { Module, type MiddlewareConsumer, type NestModule } from '@nestjs/common';
import { ConfigModule } from '@nestjs/config';
import {
  XemaServiceModule,
  applyXemaServiceMiddleware,
} from '@xemahq/xema-service-nest';
import { MAILOPS_API_BOOTSTRAP } from './generated/mailops-api.bootstrap.generated';

@Module({
  imports: [
    ConfigModule.forRoot({ isGlobal: true, load: [appConfig] }),
    XemaServiceModule.forBiome(MAILOPS_API_BOOTSTRAP),
    // ...feature modules
  ],
})
export class AppModule implements NestModule {
  configure(consumer: MiddlewareConsumer): void {
    applyXemaServiceMiddleware(consumer);
  }
}

Route policy stays with the biome

This module wires the auth stack; it does not decide what your endpoints expose. Classify each route on your own controllers exactly as before:

@XemaPublicRoute({ reason: PublicRouteReason.K8sProbe })   // public
@XemaInternalRoute({ audience: InternalRouteAudience.Service }) // service-to-service
@RequireOrgRole(OrgRole.Admin)                              // org-admin only
@RequireTokenClass(TokenClass.AgentRuntimeToken)            // scoped runtime token

A biome keeps full per-route freedom — like a core app — bounded only by the platform's fail-closed scan (every route must be classified). The test suite pins this invariant.

Capability auto-register (opt-in)

When a biome ships fully-described @XemaCapability providers, pass registerCapabilities: true plus a client factory; the composed runtime POSTs them to capability-registry-api at boot:

XemaServiceModule.forBiome(MAILOPS_API_BOOTSTRAP, {
  registerCapabilities: true,
  imports: [CapabilityClientModule],
  inject: [ConfigService, IdentityBootstrapService],
  useCapabilityRegistryClient: (cfg, idb) => new CapabilityRegistryClient(cfg, idb),
});

Required environment

The module owns the auth/identity/registry env vars internally: IDENTITY_API_URL, IDENTITY_API_INTERNAL_TOKEN, XEMA_KERNEL_STATE_PROFILE (plus the kernel-state backing config). A consuming service does not redeclare them per call.