@xemahq/xema-service-nest 0.1.0

package/LICENSE

@@ -0,0 +1,176 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,84 @@
+# @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`.
+
+```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:
+
+```ts
+@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:
+
+```ts
+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.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { XemaServiceModule, type XemaServiceModuleOptions, } from './lib/xema-service-module';
+export { applyXemaServiceMiddleware } from './lib/apply-xema-service-middleware';
+export { type ConfigureAuthMiddlewareOptions } from '@xemahq/platform-common';
+export { validateBiomeServiceDescriptor, BiomeServiceDescriptorError, type BiomeServiceDescriptor, } from './lib/biome-service-descriptor';
+export { ServiceKind } from '@xemahq/xema-decorators';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EACL,iBAAiB,EACjB,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EAAE,0BAA0B,EAAE,MAAM,qCAAqC,CAAC;AACjF,OAAO,EAAE,KAAK,8BAA8B,EAAE,MAAM,yBAAyB,CAAC;AAG9E,OAAO,EACL,8BAA8B,EAC9B,2BAA2B,EAC3B,KAAK,sBAAsB,GAC5B,MAAM,gCAAgC,CAAC;AAIxC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ServiceKind = exports.BiomeServiceDescriptorError = exports.validateBiomeServiceDescriptor = exports.applyXemaServiceMiddleware = exports.XemaServiceModule = void 0;
+var xema_service_module_1 = require("./lib/xema-service-module");
+Object.defineProperty(exports, "XemaServiceModule", { enumerable: true, get: function () { return xema_service_module_1.XemaServiceModule; } });
+var apply_xema_service_middleware_1 = require("./lib/apply-xema-service-middleware");
+Object.defineProperty(exports, "applyXemaServiceMiddleware", { enumerable: true, get: function () { return apply_xema_service_middleware_1.applyXemaServiceMiddleware; } });
+var biome_service_descriptor_1 = require("./lib/biome-service-descriptor");
+Object.defineProperty(exports, "validateBiomeServiceDescriptor", { enumerable: true, get: function () { return biome_service_descriptor_1.validateBiomeServiceDescriptor; } });
+Object.defineProperty(exports, "BiomeServiceDescriptorError", { enumerable: true, get: function () { return biome_service_descriptor_1.BiomeServiceDescriptorError; } });
+var xema_decorators_1 = require("@xemahq/xema-decorators");
+Object.defineProperty(exports, "ServiceKind", { enumerable: true, get: function () { return xema_decorators_1.ServiceKind; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AACA,iEAGmC;AAFjC,wHAAA,iBAAiB,OAAA;AAKnB,qFAAiF;AAAxE,2IAAA,0BAA0B,OAAA;AAInC,2EAIwC;AAHtC,0IAAA,8BAA8B,OAAA;AAC9B,uIAAA,2BAA2B,OAAA;AAM7B,2DAAsD;AAA7C,8GAAA,WAAW,OAAA"}

package/dist/lib/apply-xema-service-middleware.d.ts

@@ -0,0 +1,4 @@
+import type { MiddlewareConsumer } from '@nestjs/common';
+import { type ConfigureAuthMiddlewareOptions } from '@xemahq/platform-common';
+export declare function applyXemaServiceMiddleware(consumer: MiddlewareConsumer, options?: ConfigureAuthMiddlewareOptions): void;
+//# sourceMappingURL=apply-xema-service-middleware.d.ts.map

package/dist/lib/apply-xema-service-middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-xema-service-middleware.d.ts","sourceRoot":"","sources":["../../src/lib/apply-xema-service-middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACzD,OAAO,EAEL,KAAK,8BAA8B,EACpC,MAAM,yBAAyB,CAAC;AA0BjC,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,GAAE,8BAAmC,GAC3C,IAAI,CAEN"}

package/dist/lib/apply-xema-service-middleware.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.applyXemaServiceMiddleware = applyXemaServiceMiddleware;
+const platform_common_1 = require("@xemahq/platform-common");
+function applyXemaServiceMiddleware(consumer, options = {}) {
+    (0, platform_common_1.configureAuthMiddleware)(consumer, options);
+}
+//# sourceMappingURL=apply-xema-service-middleware.js.map

package/dist/lib/apply-xema-service-middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-xema-service-middleware.js","sourceRoot":"","sources":["../../src/lib/apply-xema-service-middleware.ts"],"names":[],"mappings":";;AA8BA,gEAKC;AAlCD,6DAGiC;AA0BjC,SAAgB,0BAA0B,CACxC,QAA4B,EAC5B,UAA0C,EAAE;IAE5C,IAAA,yCAAuB,EAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC7C,CAAC"}

package/dist/lib/biome-service-descriptor.d.ts

@@ -0,0 +1,14 @@
+import { ServiceKind } from '@xemahq/xema-decorators';
+export interface BiomeServiceDescriptor {
+    readonly name: string;
+    readonly semver: string;
+    readonly serviceKind: ServiceKind;
+    readonly displayName: string;
+    readonly requiresServices: readonly string[];
+    readonly exposesCapabilities: readonly string[];
+}
+export declare class BiomeServiceDescriptorError extends Error {
+    constructor(message: string);
+}
+export declare function validateBiomeServiceDescriptor(descriptor: BiomeServiceDescriptor): void;
+//# sourceMappingURL=biome-service-descriptor.d.ts.map

package/dist/lib/biome-service-descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"biome-service-descriptor.d.ts","sourceRoot":"","sources":["../../src/lib/biome-service-descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAkBtD,MAAM,WAAW,sBAAsB;IAErC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAElC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAO7B,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C,QAAQ,CAAC,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAOD,qBAAa,2BAA4B,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAInC;AAQD,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,sBAAsB,GACjC,IAAI,CAsCN"}

package/dist/lib/biome-service-descriptor.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BiomeServiceDescriptorError = void 0;
+exports.validateBiomeServiceDescriptor = validateBiomeServiceDescriptor;
+const xema_decorators_1 = require("@xemahq/xema-decorators");
+class BiomeServiceDescriptorError extends Error {
+    constructor(message) {
+        super(`[xema-service-nest] ${message}`);
+        this.name = 'BiomeServiceDescriptorError';
+    }
+}
+exports.BiomeServiceDescriptorError = BiomeServiceDescriptorError;
+const SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+function validateBiomeServiceDescriptor(descriptor) {
+    if (!descriptor || typeof descriptor !== 'object') {
+        throw new BiomeServiceDescriptorError('forBiome requires a BiomeServiceDescriptor (did you import the generated bootstrap constant?).');
+    }
+    if (!descriptor.name || !SLUG_PATTERN.test(descriptor.name)) {
+        throw new BiomeServiceDescriptorError(`descriptor.name must be a kebab-case slug; got ${JSON.stringify(descriptor.name)}.`);
+    }
+    if (!descriptor.semver || descriptor.semver.trim() === '') {
+        throw new BiomeServiceDescriptorError(`descriptor.semver is required for ${descriptor.name}.`);
+    }
+    if (!Object.values(xema_decorators_1.ServiceKind).includes(descriptor.serviceKind)) {
+        throw new BiomeServiceDescriptorError(`descriptor.serviceKind for ${descriptor.name} must be one of ${Object.values(xema_decorators_1.ServiceKind).join(', ')}; got ${JSON.stringify(descriptor.serviceKind)}.`);
+    }
+    if (!descriptor.displayName || descriptor.displayName.trim() === '') {
+        throw new BiomeServiceDescriptorError(`descriptor.displayName is required for ${descriptor.name}.`);
+    }
+    if (!Array.isArray(descriptor.requiresServices)) {
+        throw new BiomeServiceDescriptorError(`descriptor.requiresServices for ${descriptor.name} must be an array (may be empty).`);
+    }
+    if (!Array.isArray(descriptor.exposesCapabilities)) {
+        throw new BiomeServiceDescriptorError(`descriptor.exposesCapabilities for ${descriptor.name} must be an array (may be empty).`);
+    }
+}
+//# sourceMappingURL=biome-service-descriptor.js.map

package/dist/lib/biome-service-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"biome-service-descriptor.js","sourceRoot":"","sources":["../../src/lib/biome-service-descriptor.ts"],"names":[],"mappings":";;;AAwDA,wEAwCC;AAhGD,6DAAsD;AA2CtD,MAAa,2BAA4B,SAAQ,KAAK;IACpD,YAAmB,OAAe;QAChC,KAAK,CAAC,uBAAuB,OAAO,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;IAC5C,CAAC;CACF;AALD,kEAKC;AAED,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAMzC,SAAgB,8BAA8B,CAC5C,UAAkC;IAElC,IAAI,CAAC,UAAU,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,IAAI,2BAA2B,CACnC,gGAAgG,CACjG,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,IAAI,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,2BAA2B,CACnC,kDAAkD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,CACrF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,IAAI,2BAA2B,CACnC,qCAAqC,UAAU,CAAC,IAAI,GAAG,CACxD,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,6BAAW,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,2BAA2B,CACnC,8BAA8B,UAAU,CAAC,IAAI,mBAAmB,MAAM,CAAC,MAAM,CAC3E,6BAAW,CACZ,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CAC/D,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,UAAU,CAAC,WAAW,IAAI,UAAU,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACpE,MAAM,IAAI,2BAA2B,CACnC,0CAA0C,UAAU,CAAC,IAAI,GAAG,CAC7D,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,2BAA2B,CACnC,mCAAmC,UAAU,CAAC,IAAI,mCAAmC,CACtF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,mBAAmB,CAAC,EAAE,CAAC;QACnD,MAAM,IAAI,2BAA2B,CACnC,sCAAsC,UAAU,CAAC,IAAI,mCAAmC,CACzF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/lib/xema-service-module.d.ts

@@ -0,0 +1,16 @@
+import type { DynamicModule, ModuleMetadata, FactoryProvider } from '@nestjs/common';
+import { DiscoveryMode, PolicyMode, type XemaCapabilityRegistryClient } from '@xemahq/xema-decorators';
+import { type BiomeServiceDescriptor } from './biome-service-descriptor';
+export interface XemaServiceModuleOptions {
+    readonly policy?: PolicyMode;
+    readonly discovery?: DiscoveryMode;
+    readonly manifestOutputDir?: string;
+    readonly registerCapabilities?: boolean;
+    readonly useCapabilityRegistryClient?: (...args: never[]) => XemaCapabilityRegistryClient | Promise<XemaCapabilityRegistryClient>;
+    readonly inject?: FactoryProvider['inject'];
+    readonly imports?: ModuleMetadata['imports'];
+}
+export declare class XemaServiceModule {
+    static forBiome(descriptor: BiomeServiceDescriptor, options?: XemaServiceModuleOptions): DynamicModule;
+}
+//# sourceMappingURL=xema-service-module.d.ts.map

package/dist/lib/xema-service-module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xema-service-module.d.ts","sourceRoot":"","sources":["../../src/lib/xema-service-module.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAkBrF,OAAO,EACL,aAAa,EACb,UAAU,EAEV,KAAK,4BAA4B,EAClC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,4BAA4B,CAAC;AAQpC,MAAM,WAAW,wBAAwB;IAMvC,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAE7B,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC;IAKnC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAMpC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAExC,QAAQ,CAAC,2BAA2B,CAAC,EAAE,CACrC,GAAG,IAAI,EAAE,KAAK,EAAE,KACb,4BAA4B,GAAG,OAAO,CAAC,4BAA4B,CAAC,CAAC;IAE1E,QAAQ,CAAC,MAAM,CAAC,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAC;IAE5C,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC;CAC9C;AAsCD,qBAAa,iBAAiB;WACd,QAAQ,CACpB,UAAU,EAAE,sBAAsB,EAClC,OAAO,GAAE,wBAA6B,GACrC,aAAa;CAejB"}

package/dist/lib/xema-service-module.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XemaServiceModule = void 0;
+const config_1 = require("@nestjs/config");
+const identity_client_1 = require("@xemahq/identity-client");
+const service_registry_1 = require("@xemahq/kernel-contracts/service-registry");
+const kernel_state_runtime_1 = require("@xemahq/kernel-state-runtime");
+const platform_common_1 = require("@xemahq/platform-common");
+const service_registry_nest_1 = require("@xemahq/service-registry-nest");
+const xema_decorators_1 = require("@xemahq/xema-decorators");
+const biome_service_descriptor_1 = require("./biome-service-descriptor");
+class XemaServiceModule {
+    static forBiome(descriptor, options = {}) {
+        (0, biome_service_descriptor_1.validateBiomeServiceDescriptor)(descriptor);
+        const consumes = [...descriptor.requiresServices];
+        return {
+            module: XemaServiceModule,
+            imports: [
+                buildServiceRegistryModule(descriptor, consumes),
+                buildIdentityBootstrapModule(descriptor),
+                buildAuthModule(),
+                buildRuntimeModule(descriptor, options),
+            ],
+        };
+    }
+}
+exports.XemaServiceModule = XemaServiceModule;
+function buildServiceRegistryModule(descriptor, consumes) {
+    return service_registry_nest_1.ServiceRegistryModule.forRootAsync({
+        imports: [config_1.ConfigModule],
+        consumes,
+        useFactory: (config) => ({
+            adapter: service_registry_nest_1.ServiceRegistryAdapterKind.KernelState,
+            kernelStateFactory: () => (0, kernel_state_runtime_1.createKernelState)({
+                profile: (0, service_registry_nest_1.parseKernelStateProfile)(config.get('XEMA_KERNEL_STATE_PROFILE')),
+            }),
+            consumes,
+            descriptor: {
+                name: descriptor.name,
+                semver: descriptor.semver,
+                instanceId: `${descriptor.name}:${process.pid}`,
+                endpoints: [
+                    {
+                        protocol: service_registry_1.ServiceEndpointProtocol.Http,
+                        url: (0, service_registry_nest_1.buildSelfHttpEndpointUrl)(config, descriptor.name),
+                        auth: service_registry_1.ServiceEndpointAuth.ServiceToken,
+                    },
+                ],
+                exposesCapabilities: [...descriptor.exposesCapabilities],
+                requiresServices: consumes,
+            },
+        }),
+        inject: [config_1.ConfigService],
+    });
+}
+function buildIdentityBootstrapModule(descriptor) {
+    return identity_client_1.IdentityBootstrapModule.forRootAsync({
+        imports: [config_1.ConfigModule],
+        useFactory: (config) => ({
+            identityApiUrl: config.getOrThrow('IDENTITY_API_URL'),
+            identityApiInternalToken: config.getOrThrow('IDENTITY_API_INTERNAL_TOKEN'),
+            serviceName: descriptor.name,
+            serviceDisplayName: descriptor.displayName,
+        }),
+        inject: [config_1.ConfigService],
+    });
+}
+function buildAuthModule() {
+    return platform_common_1.AuthModule.forRootAsync({
+        useFactory: (bootstrap) => ({
+            keycloakBaseUrlProvider: async () => {
+                await bootstrap.waitForReady();
+                const url = bootstrap.getKeycloakBaseUrl();
+                if (!url) {
+                    throw new Error('IdentityBootstrapService did not return keycloakBaseUrl from identity-api');
+                }
+                return url;
+            },
+            allowedRealmsProvider: async () => {
+                await bootstrap.waitForReady();
+                return bootstrap.getAllowedRealms();
+            },
+        }),
+        inject: [identity_client_1.IdentityBootstrapService],
+    });
+}
+function buildRuntimeModule(descriptor, options) {
+    const discovery = options.discovery ?? xema_decorators_1.DiscoveryMode.Decorators;
+    const policy = options.policy ?? xema_decorators_1.PolicyMode.FailClosed;
+    if (options.registerCapabilities) {
+        return xema_decorators_1.XemaRuntimeModule.forServiceAsync({
+            serviceName: descriptor.name,
+            serviceKind: descriptor.serviceKind,
+            discovery,
+            policy,
+            registerCapabilities: true,
+            ...(options.manifestOutputDir !== undefined && {
+                manifestOutputDir: options.manifestOutputDir,
+            }),
+            ...(options.useCapabilityRegistryClient !== undefined && {
+                useCapabilityRegistryClient: options.useCapabilityRegistryClient,
+            }),
+            ...(options.inject !== undefined && { inject: options.inject }),
+            ...(options.imports !== undefined && { imports: options.imports }),
+        });
+    }
+    return xema_decorators_1.XemaRuntimeModule.forService({
+        serviceName: descriptor.name,
+        serviceKind: descriptor.serviceKind,
+        discovery,
+        policy,
+        ...(options.manifestOutputDir !== undefined && {
+            manifestOutputDir: options.manifestOutputDir,
+        }),
+    });
+}
+//# sourceMappingURL=xema-service-module.js.map

package/dist/lib/xema-service-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xema-service-module.js","sourceRoot":"","sources":["../../src/lib/xema-service-module.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@xemahq/xema-service-nest",
+  "version": "0.1.0",
+  "description": "Xema platform service-bootstrap SDK. `XemaServiceModule.forBiome(descriptor)` composes the full platform service stack — Service Registry, Identity bootstrap, Auth (JWT verification + request context), and the Xema runtime route/capability scanner — behind a single call, so a biome API is auth-correct in ~5 lines and never re-wires authentication.",
+  "keywords": [
+    "xema",
+    "xema-platform",
+    "nestjs",
+    "biome",
+    "bootstrap",
+    "auth",
+    "service-registry",
+    "identity"
+  ],
+  "homepage": "https://docs.xema.dev/xema-service-nest",
+  "bugs": {
+    "url": "https://github.com/xema-dev/xema-monorepo/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xema-dev/xema-monorepo.git",
+    "directory": "packages/sdks/xema-service-nest"
+  },
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/config": "^3 || ^4",
+    "@nestjs/core": "^10 || ^11",
+    "reflect-metadata": "^0.2"
+  },
+  "devDependencies": {
+    "@nestjs/common": "11.1.13",
+    "@nestjs/config": "4.0.2",
+    "@nestjs/core": "11.1.13",
+    "@nestjs/platform-express": "11.1.13",
+    "@nestjs/testing": "11.1.13",
+    "@types/jest": "^30.0.0",
+    "class-transformer": "0.5.1",
+    "class-validator": "0.14.4",
+    "@types/node": "25.2.3",
+    "jest": "^30.3.0",
+    "prettier": "3.6.2",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "ts-jest": "^29.4.9",
+    "typescript": "5.9.3"
+  },
+  "dependencies": {
+    "@xemahq/identity-client": "^0.3.2",
+    "@xemahq/kernel-contracts": "^0.3.0",
+    "@xemahq/kernel-state-runtime": "^0.1.4",
+    "@xemahq/platform-common": "^0.1.7",
+    "@xemahq/service-registry-nest": "^0.1.4",
+    "@xemahq/xema-decorators": "^0.1.3"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "xema-source": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./dist/lib/*": {
+      "types": "./dist/lib/*.d.ts",
+      "default": "./dist/lib/*.js"
+    }
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc -p tsconfig.build.json",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "jest"
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// The single-call platform service bootstrap.
+export {
+  XemaServiceModule,
+  type XemaServiceModuleOptions,
+} from './lib/xema-service-module';
+
+// Root-module middleware helper (request context).
+export { applyXemaServiceMiddleware } from './lib/apply-xema-service-middleware';
+export { type ConfigureAuthMiddlewareOptions } from '@xemahq/platform-common';
+
+// The manifest-derived bootstrap identity consumed by `forBiome`.
+export {
+  validateBiomeServiceDescriptor,
+  BiomeServiceDescriptorError,
+  type BiomeServiceDescriptor,
+} from './lib/biome-service-descriptor';
+
+// Re-export `ServiceKind` so a generated bootstrap constant can name its kind
+// without a second import from `@xemahq/xema-decorators`.
+export { ServiceKind } from '@xemahq/xema-decorators';

package/src/lib/apply-xema-service-middleware.ts

@@ -0,0 +1,36 @@
+import type { MiddlewareConsumer } from '@nestjs/common';
+import {
+  configureAuthMiddleware,
+  type ConfigureAuthMiddlewareOptions,
+} from '@xemahq/platform-common';
+
+/**
+ * Apply the platform request-context middleware from a biome's root
+ * `AppModule.configure()`. Wraps `configureAuthMiddleware` so a biome calls
+ * exactly ONE thing and never imports the raw middleware wiring.
+ *
+ * NestJS only invokes `configure()` on the ROOT module, so this cannot be done
+ * inside `XemaServiceModule.forBiome` — the host module must call it.
+ *
+ * The optional second argument is forwarded verbatim, so a service keeps full
+ * control over `extraExcludes` (extra public routes) and `additionalControllers`
+ * (internal routes that authenticate via service-account JWTs and should still
+ * receive `RequestContext`).
+ *
+ * @example
+ * ```ts
+ * export class AppModule implements NestModule {
+ *   configure(consumer: MiddlewareConsumer): void {
+ *     applyXemaServiceMiddleware(consumer);
+ *     // or, opting an internal controller into request-context:
+ *     // applyXemaServiceMiddleware(consumer, { additionalControllers: [InternalFooController] });
+ *   }
+ * }
+ * ```
+ */
+export function applyXemaServiceMiddleware(
+  consumer: MiddlewareConsumer,
+  options: ConfigureAuthMiddlewareOptions = {},
+): void {
+  configureAuthMiddleware(consumer, options);
+}

package/src/lib/biome-service-descriptor.ts

@@ -0,0 +1,97 @@
+import { ServiceKind } from '@xemahq/xema-decorators';
+
+/**
+ * The single-source-of-truth bootstrap identity of a biome API service.
+ *
+ * Every field here is derived from the biome's `xema-biome.json` manifest by
+ * `tooling/codegen/generate-service-bootstrap.mjs`, which emits one
+ * `src/generated/<service>.bootstrap.generated.ts` per `ships.apis[]` entry.
+ * `XemaServiceModule.forBiome(descriptor)` consumes that generated constant —
+ * so a developer declares name / version / dependencies ONCE in the manifest
+ * and never re-types them in `app.module.ts`.
+ *
+ * This type intentionally carries ONLY the identity a service registration
+ * needs. It does NOT carry route policy: a biome keeps full per-route freedom
+ * via the `@XemaPublicRoute` / `@XemaInternalRoute` / `@RequireOrgRole` /
+ * `@RequireTokenClass` decorators on its own controllers. The module wires the
+ * auth STACK; the biome decides what each endpoint exposes.
+ */
+export interface BiomeServiceDescriptor {
+  /** Canonical service slug (a `ServiceName` value), e.g. `'mailops-api'`. */
+  readonly name: string;
+  /** Published semver, mirrored from the manifest `version`. */
+  readonly semver: string;
+  /** Whether this is a platform service or a biome API. */
+  readonly serviceKind: ServiceKind;
+  /** Human-readable display name registered with identity-api. */
+  readonly displayName: string;
+  /**
+   * Names of services this one calls. Each becomes a typed-client provider
+   * (`@InjectService(name)`) AND a `requiresServices` entry on the registry
+   * descriptor. Always include the services the auth stack itself needs
+   * (e.g. `identity-api`).
+   */
+  readonly requiresServices: readonly string[];
+  /** Capability refs this service exposes (registry descriptor metadata). */
+  readonly exposesCapabilities: readonly string[];
+}
+
+/**
+ * A `BiomeServiceDescriptor` value error. Thrown at module-construction time
+ * so a malformed/empty descriptor fails the boot fast rather than registering
+ * a half-identified service.
+ */
+export class BiomeServiceDescriptorError extends Error {
+  public constructor(message: string) {
+    super(`[xema-service-nest] ${message}`);
+    this.name = 'BiomeServiceDescriptorError';
+  }
+}
+
+const SLUG_PATTERN = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Fail-fast validation of a bootstrap descriptor. Centralized so both
+ * `forBiome` and any test harness enforce the same invariants.
+ */
+export function validateBiomeServiceDescriptor(
+  descriptor: BiomeServiceDescriptor,
+): void {
+  if (!descriptor || typeof descriptor !== 'object') {
+    throw new BiomeServiceDescriptorError(
+      'forBiome requires a BiomeServiceDescriptor (did you import the generated bootstrap constant?).',
+    );
+  }
+  if (!descriptor.name || !SLUG_PATTERN.test(descriptor.name)) {
+    throw new BiomeServiceDescriptorError(
+      `descriptor.name must be a kebab-case slug; got ${JSON.stringify(descriptor.name)}.`,
+    );
+  }
+  if (!descriptor.semver || descriptor.semver.trim() === '') {
+    throw new BiomeServiceDescriptorError(
+      `descriptor.semver is required for ${descriptor.name}.`,
+    );
+  }
+  if (!Object.values(ServiceKind).includes(descriptor.serviceKind)) {
+    throw new BiomeServiceDescriptorError(
+      `descriptor.serviceKind for ${descriptor.name} must be one of ${Object.values(
+        ServiceKind,
+      ).join(', ')}; got ${JSON.stringify(descriptor.serviceKind)}.`,
+    );
+  }
+  if (!descriptor.displayName || descriptor.displayName.trim() === '') {
+    throw new BiomeServiceDescriptorError(
+      `descriptor.displayName is required for ${descriptor.name}.`,
+    );
+  }
+  if (!Array.isArray(descriptor.requiresServices)) {
+    throw new BiomeServiceDescriptorError(
+      `descriptor.requiresServices for ${descriptor.name} must be an array (may be empty).`,
+    );
+  }
+  if (!Array.isArray(descriptor.exposesCapabilities)) {
+    throw new BiomeServiceDescriptorError(
+      `descriptor.exposesCapabilities for ${descriptor.name} must be an array (may be empty).`,
+    );
+  }
+}

package/src/lib/xema-service-module.ts

@@ -0,0 +1,233 @@
+import type { DynamicModule, ModuleMetadata, FactoryProvider } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import {
+  IdentityBootstrapModule,
+  IdentityBootstrapService,
+} from '@xemahq/identity-client';
+import {
+  ServiceEndpointAuth,
+  ServiceEndpointProtocol,
+} from '@xemahq/kernel-contracts/service-registry';
+import { createKernelState } from '@xemahq/kernel-state-runtime';
+import { AuthModule } from '@xemahq/platform-common';
+import {
+  buildSelfHttpEndpointUrl,
+  parseKernelStateProfile,
+  ServiceRegistryAdapterKind,
+  ServiceRegistryModule,
+} from '@xemahq/service-registry-nest';
+import {
+  DiscoveryMode,
+  PolicyMode,
+  XemaRuntimeModule,
+  type XemaCapabilityRegistryClient,
+} from '@xemahq/xema-decorators';
+
+import {
+  validateBiomeServiceDescriptor,
+  type BiomeServiceDescriptor,
+} from './biome-service-descriptor';
+
+/**
+ * Optional behaviour overrides for {@link XemaServiceModule.forBiome}. Sane
+ * defaults are prod-safe (fail-closed route scan, KernelState registry
+ * adapter, capability auto-register OFF). A biome only sets these when it has
+ * a real reason to.
+ */
+export interface XemaServiceModuleOptions {
+  /**
+   * Route-classification policy for the composed runtime scanner. Defaults to
+   * {@link PolicyMode.FailClosed} — unclassified routes crash boot in
+   * production. Override to {@link PolicyMode.FailOpen} only for local dev.
+   */
+  readonly policy?: PolicyMode;
+  /** Discovery mode for the runtime scanner. Defaults to decorators. */
+  readonly discovery?: DiscoveryMode;
+  /**
+   * Override the runtime manifest output dir (tests / sandboxed tmpdir). See
+   * `XemaRuntimeModule` docs.
+   */
+  readonly manifestOutputDir?: string;
+  /**
+   * Opt into the boot-time capability auto-register path (Phase H#2). When
+   * `true`, `useCapabilityRegistryClient` + `inject` MUST be supplied — the
+   * runtime module refuses the flag without a client (no silent no-op).
+   */
+  readonly registerCapabilities?: boolean;
+  /** Factory producing the capability-registry client (DI-resolved). */
+  readonly useCapabilityRegistryClient?: (
+    ...args: never[]
+  ) => XemaCapabilityRegistryClient | Promise<XemaCapabilityRegistryClient>;
+  /** DI tokens for {@link useCapabilityRegistryClient}. */
+  readonly inject?: FactoryProvider['inject'];
+  /** Extra modules the capability-client factory needs (e.g. a client module). */
+  readonly imports?: ModuleMetadata['imports'];
+}
+
+/**
+ * The one module a biome API imports to be platform-correct.
+ *
+ * `XemaServiceModule.forBiome(descriptor)` **composes** (never reimplements)
+ * the full platform service stack, in dependency order:
+ *
+ *  1. `ServiceRegistryModule` — self-registers with the cluster KernelState and
+ *     pre-wires one typed client per `requiresServices` entry.
+ *  2. `IdentityBootstrapModule` — registers with identity-api, mints + refreshes
+ *     the service `service_jwt`, and exposes the Keycloak base URL + realms.
+ *  3. `AuthModule` — the global `JwtVerificationGuard` (+ `RolesGuard`), wired
+ *     lazily off `IdentityBootstrapService` so the realm config resolves after
+ *     bootstrap.
+ *  4. `XemaRuntimeModule` — the fail-closed route/capability decorator scan.
+ *
+ * All four are `global: true`, so importing this one module makes the whole
+ * stack available app-wide. The biome still owns its route policy: classify
+ * each endpoint with `@XemaPublicRoute` / `@XemaInternalRoute` /
+ * `@RequireOrgRole` / `@RequireTokenClass` exactly as before — this module wires
+ * the stack, it does not constrain what a biome exposes.
+ *
+ * The root `AppModule` must additionally call `applyXemaServiceMiddleware(consumer)`
+ * in its `configure()` — NestJS only lets the root module register global
+ * middleware (`RequestContextMiddleware`), so a dynamic module cannot do it.
+ *
+ * @example
+ * ```ts
+ * import { XemaServiceModule, applyXemaServiceMiddleware } from '@xemahq/xema-service-nest';
+ * import { MAILOPS_API_BOOTSTRAP } from './generated/mailops-api.bootstrap.generated';
+ *
+ * @Module({ imports: [ConfigModule.forRoot({ isGlobal: true }), XemaServiceModule.forBiome(MAILOPS_API_BOOTSTRAP), ...] })
+ * export class AppModule implements NestModule {
+ *   configure(c: MiddlewareConsumer) { applyXemaServiceMiddleware(c); }
+ * }
+ * ```
+ */
+export class XemaServiceModule {
+  public static forBiome(
+    descriptor: BiomeServiceDescriptor,
+    options: XemaServiceModuleOptions = {},
+  ): DynamicModule {
+    validateBiomeServiceDescriptor(descriptor);
+
+    const consumes = [...descriptor.requiresServices];
+
+    return {
+      module: XemaServiceModule,
+      imports: [
+        buildServiceRegistryModule(descriptor, consumes),
+        buildIdentityBootstrapModule(descriptor),
+        buildAuthModule(),
+        buildRuntimeModule(descriptor, options),
+      ],
+    };
+  }
+}
+
+function buildServiceRegistryModule(
+  descriptor: BiomeServiceDescriptor,
+  consumes: string[],
+): DynamicModule {
+  return ServiceRegistryModule.forRootAsync({
+    imports: [ConfigModule],
+    // Authoritative for typed-client provider creation (must be sync).
+    consumes,
+    useFactory: (config: ConfigService) => ({
+      adapter: ServiceRegistryAdapterKind.KernelState,
+      kernelStateFactory: () =>
+        createKernelState({
+          profile: parseKernelStateProfile(
+            config.get<string>('XEMA_KERNEL_STATE_PROFILE'),
+          ),
+        }),
+      consumes,
+      descriptor: {
+        name: descriptor.name,
+        semver: descriptor.semver,
+        instanceId: `${descriptor.name}:${process.pid}`,
+        endpoints: [
+          {
+            protocol: ServiceEndpointProtocol.Http,
+            url: buildSelfHttpEndpointUrl(config, descriptor.name),
+            auth: ServiceEndpointAuth.ServiceToken,
+          },
+        ],
+        exposesCapabilities: [...descriptor.exposesCapabilities],
+        requiresServices: consumes,
+      },
+    }),
+    inject: [ConfigService],
+  });
+}
+
+function buildIdentityBootstrapModule(
+  descriptor: BiomeServiceDescriptor,
+): DynamicModule {
+  return IdentityBootstrapModule.forRootAsync({
+    imports: [ConfigModule],
+    useFactory: (config: ConfigService) => ({
+      identityApiUrl: config.getOrThrow<string>('IDENTITY_API_URL'),
+      identityApiInternalToken: config.getOrThrow<string>(
+        'IDENTITY_API_INTERNAL_TOKEN',
+      ),
+      serviceName: descriptor.name,
+      serviceDisplayName: descriptor.displayName,
+    }),
+    inject: [ConfigService],
+  });
+}
+
+function buildAuthModule(): DynamicModule {
+  return AuthModule.forRootAsync({
+    useFactory: (bootstrap: IdentityBootstrapService) => ({
+      keycloakBaseUrlProvider: async () => {
+        await bootstrap.waitForReady();
+        const url = bootstrap.getKeycloakBaseUrl();
+        if (!url) {
+          throw new Error(
+            'IdentityBootstrapService did not return keycloakBaseUrl from identity-api',
+          );
+        }
+        return url;
+      },
+      allowedRealmsProvider: async () => {
+        await bootstrap.waitForReady();
+        return bootstrap.getAllowedRealms();
+      },
+    }),
+    inject: [IdentityBootstrapService],
+  });
+}
+
+function buildRuntimeModule(
+  descriptor: BiomeServiceDescriptor,
+  options: XemaServiceModuleOptions,
+): DynamicModule {
+  const discovery = options.discovery ?? DiscoveryMode.Decorators;
+  const policy = options.policy ?? PolicyMode.FailClosed;
+
+  if (options.registerCapabilities) {
+    return XemaRuntimeModule.forServiceAsync({
+      serviceName: descriptor.name,
+      serviceKind: descriptor.serviceKind,
+      discovery,
+      policy,
+      registerCapabilities: true,
+      ...(options.manifestOutputDir !== undefined && {
+        manifestOutputDir: options.manifestOutputDir,
+      }),
+      ...(options.useCapabilityRegistryClient !== undefined && {
+        useCapabilityRegistryClient: options.useCapabilityRegistryClient,
+      }),
+      ...(options.inject !== undefined && { inject: options.inject }),
+      ...(options.imports !== undefined && { imports: options.imports }),
+    });
+  }
+
+  return XemaRuntimeModule.forService({
+    serviceName: descriptor.name,
+    serviceKind: descriptor.serviceKind,
+    discovery,
+    policy,
+    ...(options.manifestOutputDir !== undefined && {
+      manifestOutputDir: options.manifestOutputDir,
+    }),
+  });
+}