@xemahq/biome-database-nest 0.12.1 → 0.12.2

package/src/lib/nest/biome-database.module.ts

@@ -1,174 +0,0 @@
-import { Module } from '@nestjs/common';
-import { IdentityBootstrapService } from '@xemahq/identity-client';
-import {
-  isOpenApiExtraction,
-  KERNEL_STATE_TOKEN,
-} from '@xemahq/service-registry-nest';
-
-import { bootstrapBiomeDatabases } from '../bootstrap';
-import { BiomeDatabaseMigrationMode } from '../migration-mode';
-
-import type {
-  BiomeDatabaseDeclaration,
-} from '../bootstrap';
-import type { DynamicModule } from '@nestjs/common';
-import type { KernelState } from '@xemahq/kernel-contracts/kernel-state';
-
-/**
- * DI-resolved sentinel that resolves to `true` once every declared biome
- * database has been schema-created, migrated, and exported into the env that
- * `createBiomePrismaAdapterFromEnv` reads.
- *
- * A consuming service MUST list this token in the `inject:[]` of its
- * `PrismaService` provider so Nest constructs the database connection ONLY
- * after the bootstrap has completed.
- */
-export const BIOME_DATABASE_READY = Symbol.for(
-  '@xemahq/biome-database-nest:ready',
-);
-
-interface BiomeDatabaseModuleCommonOptions {
-  /** The biome whose databases are being bootstrapped. */
-  readonly biomeId: string;
-}
-
-export interface ApplicationManagedBiomeDatabaseModuleOptions
-  extends BiomeDatabaseModuleCommonOptions {
-  readonly migrationMode: BiomeDatabaseMigrationMode.ApplicationManaged;
-  /**
-   * Explicit databases to bootstrap. Each declaration pins the credential
-   * generation independently of migration ownership.
-   */
-  readonly databases: readonly BiomeDatabaseDeclaration[];
-  /**
-   * Postgres extensions this biome needs (e.g. `['vector']`), ensured in the
-   * shared `public` schema BEFORE migrations run. Only declare extensions the
-   * biome actually uses. See `BootstrapBiomeDatabasesOptions.requiredExtensions`.
-   */
-  readonly requiredExtensions?: readonly string[];
-}
-
-
-/** Options for {@link BiomeDatabaseModule.forRoot}. */
-export type BiomeDatabaseModuleOptions =
-  ApplicationManagedBiomeDatabaseModuleOptions;
-
-function assertBiomeDatabaseModuleOptions(
-  opts: unknown,
-): asserts opts is BiomeDatabaseModuleOptions {
-  if (
-    opts === null ||
-    typeof opts !== 'object' ||
-    !('migrationMode' in opts) ||
-    opts.migrationMode !== BiomeDatabaseMigrationMode.ApplicationManaged
-  ) {
-    throw new Error(
-      '[biome-database] migrationMode is required and must be ApplicationManaged.',
-    );
-  }
-
-  if (
-    !('databases' in opts) ||
-    !Array.isArray(opts.databases) ||
-    opts.databases.length === 0
-  ) {
-    throw new Error(
-      '[biome-database] every migration mode requires at least one explicit database declaration.',
-    );
-  }
-}
-
-/**
- * Global Nest dynamic module that bootstraps a biome's database using an
- * explicitly selected migration ownership mode.
- *
- * Application-managed mode retains env-first config resolution. Externally
- * managed declarations select environment or control plane explicitly, so a
- * stale env override can never silently replace the intended runtime
- * credential.
- *
- * `IdentityBootstrapService` (from `@xemahq/identity-client`) is provided
- * globally by the app's `XemaServiceModule.forBiome(...)` bootstrap, so it is
- * injectable at DI time and mints the service bearer for the control-plane
- * call. The control-plane ADDRESS is discovered from the Xema service registry:
- * this factory injects the app's `KernelState` backend via `KERNEL_STATE_TOKEN`
- * (exposed globally by `ServiceRegistryModule`, wired by
- * `XemaServiceModule.forBiome(...)`) and drives a private, short-lived
- * `KernelStateServiceRegistry` to `resolve('org-database-pool-api')` with
- * bounded retry — see `resolveControlPlaneBaseUrl` in `control-plane-discovery`.
- * The app-wide registry is NOT injected: it hydrates only in `onModuleInit`,
- * which cannot run until this instantiation-phase factory returns.
- *
- * REQUIRES the consuming app to provide `KERNEL_STATE_TOKEN` globally — every
- * biome service does via `XemaServiceModule.forBiome(...)` /
- * `ServiceRegistryModule`. No extra import in this module is needed because that
- * provider is global; if it is absent, Nest fails fast at DI resolution.
- *
- * Fail-fast: an absent/unknown mode or any boot error aborts Nest startup.
- *
- * @example Consumer wiring
- * ```ts
- * // app.module.ts (or prisma.module.ts):
- * imports: [BiomeDatabaseModule.forRoot({
- *   biomeId: '<biome-id>',
- * })],
- *
- * // prisma.module.ts — the PrismaService provider waits on the boot:
- * {
- *   provide: PrismaService,
- *   useFactory: () => new PrismaService(),
- *   inject: [BIOME_DATABASE_READY],
- * }
- * ```
- */
-@Module({})
-export class BiomeDatabaseModule {
-  static forRoot(opts: BiomeDatabaseModuleOptions): DynamicModule;
-  static forRoot(opts: unknown): DynamicModule {
-    assertBiomeDatabaseModuleOptions(opts);
-    const databases: readonly BiomeDatabaseDeclaration[] = opts.databases;
-
-    // Build-time OpenAPI extraction compiles the DI graph for decorator
-    // metadata only: it never calls `app.init()`, never issues a query, and
-    // stubs `PrismaService` outright. Running the real bootstrap there would
-    // connect to — and MIGRATE — a throwaway scratch database, which is both
-    // pointless and (under parallel extraction) mutually destructive. Resolve
-    // the sentinel to `true` without injecting anything.
-    if (isOpenApiExtraction()) {
-      return {
-        module: BiomeDatabaseModule,
-        global: true,
-        providers: [{ provide: BIOME_DATABASE_READY, useValue: true }],
-        exports: [BIOME_DATABASE_READY],
-      };
-    }
-
-    return {
-      module: BiomeDatabaseModule,
-      global: true,
-      providers: [
-        {
-          provide: BIOME_DATABASE_READY,
-          useFactory: async (
-            identityBootstrap: IdentityBootstrapService,
-            kernelState: KernelState,
-          ): Promise<true> => {
-            await bootstrapBiomeDatabases({
-              biomeId: opts.biomeId,
-              migrationMode: opts.migrationMode,
-              databases,
-              ...(opts.requiredExtensions !== undefined
-                ? { requiredExtensions: opts.requiredExtensions }
-                : {}),
-              serviceToken: () => identityBootstrap.getAccessToken(),
-              kernelState,
-            });
-            return true;
-          },
-          inject: [IdentityBootstrapService, KERNEL_STATE_TOKEN],
-        },
-      ],
-      exports: [BIOME_DATABASE_READY],
-    };
-  }
-}

package/src/lib/nest/org-erasure.module.ts

@@ -1,158 +0,0 @@
-/**
- * LC-1 topology-1 org-erasure ENDPOINT — the DRY adoption surface.
- *
- * A first-party biome that holds org data by-row opts in with ONE line:
- *
- * ```ts
- * imports: [OrgErasureModule.forRoot({ prismaServiceToken: PrismaService })]
- * ```
- *
- * That exposes the STANDARD internal route `POST /internal/org-erasure/:orgId`,
- * which erases every row belonging to the org across the service's org-scoped
- * models via {@link eraseOrgData} on the UNSCOPED client (`asSystem()`). The
- * org-erasure orchestrator saga fans out to this route on every participant.
- *
- * Service-only, and ENFORCED by `ServiceActorGuard` — not by the classification
- * decorator. `@XemaInternalRoute({ audience: Service })` is metadata the
- * fail-closed route scanner reads; it installs NO runtime guard (see
- * `.claude/rules/public-and-internal-route-guarding.md`). The global stack only
- * proves the JWT signature, and `RolesGuard` enforces nothing unless a route
- * declares `@RequireOrgRole`/`@RequireTokenClass`. Without the guard, ANY
- * authenticated user token reaching this service — trivially so for any
- * participant whose chart enables ingress — could irreversibly erase an
- * arbitrary org's data, since `:orgId` is taken verbatim from the path. This
- * module is adopted by 17 participants, so the guard belongs HERE, once.
- *
- * The org filter is applied inside {@link eraseOrgData}; the runner passes the
- * unscoped client so scoping is neither doubled nor left to ambient context.
- *
- * **The module refuses to boot a participant that can erase nothing.** Wiring
- * the runner asserts (via {@link assertOrgErasureMatchesModels}) that the
- * configured `orgField` matches at least one model of THIS service's schema. A
- * participant registered against a column its schema does not spell matches
- * zero models, deletes nothing, and returns `{totalDeleted: 0}` — which the
- * orchestrator records as a successful erasure. That must fail at deploy, not
- * silently succeed during a Data Subject Request.
- */
-import {
-  Controller,
-  Inject,
-  Logger,
-  Param,
-  Post,
-  UseGuards,
-  type DynamicModule,
-  type Type,
-} from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
-import { ServiceActorGuard } from '@xemahq/platform-common';
-import { InternalRouteAudience, XemaInternalRoute } from '@xemahq/xema-decorators';
-
-import {
-  assertOrgErasureMatchesModels,
-  eraseOrgData,
-  type EraseOrgDataOptions,
-  type OrgErasureReport,
-} from '../tenant-isolation/org-erasure';
-import { DEFAULT_ORG_FIELD } from '../tenant-isolation/tenant-isolation.extension';
-
-import type { TenantScopedApi } from './prisma-service-factory';
-
-/** DI token for the erasure runner the controller delegates to. */
-export const ORG_ERASURE_RUNNER = Symbol.for(
-  '@xemahq/biome-database-nest/org-erasure-runner',
-);
-
-/**
- * The capability a topology-1 participant declares in its service descriptor's
- * `exposesCapabilities` so the org-erasure orchestrator can DISCOVER it via the
- * service registry (`registry.list()` filtered on this string) and fan out to
- * its `POST /internal/org-erasure/:orgId`. Single source of truth shared by the
- * declaring service and the orchestrator — discovery is explicit-by-declaration,
- * never a probe-and-guess heuristic.
- */
-export const ORG_DATA_ERASURE_CAPABILITY = 'xema.org-data-erasure';
-
-/** The internal route path this module exposes (orchestrator fans out to it). */
-export const ORG_ERASURE_ROUTE_PATH = 'internal/org-erasure';
-
-export interface OrgErasureRunner {
-  erase(orgId: string): Promise<OrgErasureReport>;
-}
-
-@ApiTags('org-erasure')
-@UseGuards(ServiceActorGuard)
-@Controller('internal/org-erasure')
-export class OrgErasureController {
-  constructor(
-    @Inject(ORG_ERASURE_RUNNER) private readonly runner: OrgErasureRunner,
-  ) {}
-
-  @XemaInternalRoute({ audience: InternalRouteAudience.Service })
-  @Post(':orgId')
-  @ApiOperation({
-    summary:
-      "Erase every row belonging to an org across this service's org-scoped models",
-  })
-  erase(@Param('orgId') orgId: string): Promise<OrgErasureReport> {
-    return this.runner.erase(orgId);
-  }
-}
-
-export interface OrgErasureModuleOptions extends EraseOrgDataOptions {
-  /**
-   * The service's PrismaService DI token — the class it provides as its Prisma
-   * service (a {@link BiomePrismaServiceInstance}). The runner resolves it and
-   * calls `.asSystem()` to get the unscoped client.
-   */
-  readonly prismaServiceToken: Type<unknown> | string | symbol;
-}
-
-/**
- * The subset of the biome Prisma service the runner needs: the unscoped
- * `asSystem()` client accessor.
- */
-type AsSystemProvider = TenantScopedApi<unknown>;
-
-export class OrgErasureModule {
-  static forRoot(options: OrgErasureModuleOptions): DynamicModule {
-    const { prismaServiceToken, ...eraseOptions } = options;
-    return {
-      module: OrgErasureModule,
-      controllers: [OrgErasureController],
-      providers: [
-        {
-          provide: ORG_ERASURE_RUNNER,
-          useFactory: (prisma: AsSystemProvider): OrgErasureRunner => {
-            const client = prisma.asSystem();
-            // BOOT GATE. A participant whose orgField matches no model can
-            // never delete a row, and `eraseOrgData` would have answered every
-            // erasure `{totalDeleted: 0}` — which the orchestrator saga records
-            // as a successful erasure. Discovering that during a live Data
-            // Subject Request is discovering it too late, so the service
-            // refuses to START rather than advertise `xema.org-data-erasure`
-            // it cannot honour. Throwing here aborts Nest's bootstrap.
-            //
-            // This is the CONFIGURATION proof; `eraseOrgData` re-asserts per
-            // request, which is the proof of the RUN being recorded as
-            // evidence. The assertion is on MODELS matched — an org that
-            // genuinely holds no rows here still erases successfully.
-            const models = [
-              ...assertOrgErasureMatchesModels(client, eraseOptions),
-            ].sort();
-            new Logger(OrgErasureModule.name).log(
-              `org-erasure participant armed on "${
-                eraseOptions.orgField ?? DEFAULT_ORG_FIELD
-              }" over ${models.length} model(s): ${models.join(', ')}`,
-            );
-            return {
-              erase: (orgId: string): Promise<OrgErasureReport> =>
-                eraseOrgData(prisma.asSystem(), orgId, eraseOptions),
-            };
-          },
-          inject: [prismaServiceToken],
-        },
-      ],
-    };
-  }
-}