@xemahq/biome-database-nest 0.12.1 → 0.12.2

package/src/lib/nest/prisma-service-factory.ts

@@ -1,377 +0,0 @@
-import { Injectable, Logger } from '@nestjs/common';
-import { getAmbientOrgId } from '@xemahq/platform-common';
-
-import { createBiomePrismaAdapterFromEnv } from '../adapter';
-import {
-  TenantIsolationMode,
-  resolveTenantIsolationMode,
-} from '../tenant-isolation/tenant-isolation-mode';
-import {
-  DEFAULT_ORG_FIELD,
-  collectOrgScopedModels,
-  createTenantIsolationExtension,
-  readRuntimeModels,
-  type TenantIsolationLogger,
-} from '../tenant-isolation/tenant-isolation.extension';
-import {
-  assertUnscopedModelsDeclared,
-  type UnscopedModelDeclarations,
-} from '../tenant-isolation/unscoped-models';
-
-import type { OnModuleDestroy, OnModuleInit, Type } from '@nestjs/common';
-
-/**
- * Minimal structural shape of a generated Prisma `PrismaClient` as far as the
- * lifecycle wrapper cares: it is a constructor whose single (optional) argument
- * is the Prisma client options bag (we inject `{ adapter }`), and instances
- * expose the `$connect`/`$disconnect` lifecycle methods.
- *
- * It is deliberately structural and `any`-arg so that EVERY service's own
- * generated `PrismaClient` — each with a different model surface — satisfies it
- * without the SDK having to know any concrete schema.
- */
-export type BiomePrismaClientCtor<TClient extends BiomePrismaClient> = new (
-  // The generated PrismaClient constructor's options arg is schema-specific;
-  // we only ever pass `{ adapter }`, which every generated client accepts.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ...args: any[]
-) => TClient;
-
-/** The lifecycle surface every generated `PrismaClient` exposes. */
-export interface BiomePrismaClient {
-  $connect(): Promise<void>;
-  $disconnect(): Promise<void>;
-}
-
-/** Tenant-isolation knobs a service may set on its Prisma service. */
-export interface TenantIsolationServiceOptions {
-  /**
-   * Mode for the DEFAULT (ambient-scoped) client. Resolution: this option >
-   * `XEMA_TENANT_ISOLATION_MODE` env var > `Observe`.
-   */
-  readonly mode?: TenantIsolationMode;
-  /** Org column detected on models (default `orgId`). */
-  readonly orgField?: string;
-  /**
-   * Models that carry the org column but are deliberately NOT tenant-scoped.
-   * Names must match the Prisma schema model names; unknown names throw.
-   */
-  readonly exemptModels?: readonly string[];
-  /**
-   * Models that declare NO org column at all — the ones the isolation extension
-   * is structurally unable to auto-scope — each with a written justification.
-   *
-   * This is REQUIRED to be exhaustive: in `Enforce` mode a model with no org
-   * column and no declaration ABORTS BOOT
-   * ({@link UndeclaredUnscopedModelsError}); in `Observe` it is a loud warning.
-   * Previously such a model was simply invisible to enforcement, so `Enforce`
-   * gave false assurance — see `../tenant-isolation/unscoped-models.ts` for the
-   * incident that motivated this.
-   *
-   * A model that is tenant-scoped in reality (owned through a foreign key) MUST
-   * also state `fencedBy` — the manual predicate its queries carry.
-   *
-   * @example
-   * ```ts
-   * unscopedModels: {
-   *   MigrationBookkeeping: 'internal bookkeeping; rows belong to no tenant',
-   *   ChangeRequest: {
-   *     reason: 'owned via projectRepositoryBindingId -> … -> OrgRepository.orgId',
-   *     fencedBy: 'projectRepositoryBinding: { orgRepository: { orgId } }',
-   *   },
-   * }
-   * ```
-   */
-  readonly unscopedModels?: UnscopedModelDeclarations;
-}
-
-/** Options bag for {@link createBiomePrismaService}. */
-export interface CreateBiomePrismaServiceOptions {
-  /** Logger name (defaults to `'PrismaService'`). */
-  readonly loggerContext?: string;
-  readonly tenantIsolation?: TenantIsolationServiceOptions;
-}
-
-/**
- * The explicit-scoping surface every biome Prisma service now carries in
- * addition to its full generated-client surface.
- */
-export interface TenantScopedApi<TClient> {
-  /**
-   * A client hard-bound to `orgId` — for jobs, workers, Temporal activities,
-   * contribution sync, and any other path with no ambient request context.
-   * ALWAYS enforces (regardless of the global mode): explicit scoping is a
-   * correctness request and is never silently degraded.
-   */
-  forOrg(orgId: string): TClient;
-  /**
-   * The raw, UNSCOPED client for legitimate cross-org system paths (boot
-   * backfills, platform-level admin surfaces). Logged at debug level once per
-   * call site so system access stays auditable without log floods.
-   */
-  asSystem(): TClient;
-}
-
-/** Instance type produced by {@link createBiomePrismaService}. */
-export type BiomePrismaServiceInstance<TClient> = TClient &
-  TenantScopedApi<TClient> &
-  OnModuleInit &
-  OnModuleDestroy;
-
-interface ExtendableClient {
-  $extends?: (extension: unknown) => unknown;
-}
-
-function lowerFirst(name: string): string {
-  return name.length === 0
-    ? name
-    : name.charAt(0).toLowerCase() + name.slice(1);
-}
-
-function normalizeOptions(
-  optionsOrLoggerContext: string | CreateBiomePrismaServiceOptions | undefined,
-): CreateBiomePrismaServiceOptions {
-  if (optionsOrLoggerContext === undefined) {
-    return {};
-  }
-  if (typeof optionsOrLoggerContext === 'string') {
-    return { loggerContext: optionsOrLoggerContext };
-  }
-  return optionsOrLoggerContext;
-}
-
-/**
- * Build the `@Injectable()` Prisma service class for a biome from ITS OWN
- * generated `PrismaClient` constructor.
- *
- * Eliminates the byte-identical `prisma.service.ts` every biome service
- * hand-writes: the ONLY per-service difference is which generated client is
- * extended. A service supplies that client and gets the schema-qualified
- * driver-adapter (via {@link createBiomePrismaAdapterFromEnv}, the package's
- * single correct adapter construction — REUSED, not reimplemented) plus the
- * Nest `OnModuleInit`/`OnModuleDestroy` `$connect`/`$disconnect` lifecycle for
- * free.
- *
- * **Tenant isolation (C3).** Org-scoped models (those declaring the org
- * column, default `orgId`) are detected from the client's runtime data model
- * at construction time, and the DEFAULT injected client routes their delegates
- * (plus `$transaction`) through a Prisma client extension that scopes every
- * operation to the AMBIENT org (`AmbientOrgContextMiddleware` /
- * `runWithAmbientOrg`) per {@link TenantIsolationMode}:
- *
- * - `Observe` (default): no query is rewritten; violations are warned.
- * - `Enforce`: org filters are injected; violations throw
- *   `TenantIsolationError`. Outside any request context, org-model access
- *   throws — use `forOrg(orgId)` / `asSystem()` (see {@link TenantScopedApi}).
- * - `Off`: passthrough kill switch (detection is deferred so `Off` can never
- *   fail a boot; `forOrg` still enforces on first use).
- *
- * Fail-fast: a failed `$connect()` at `onModuleInit` is logged and rethrown so
- * Nest aborts startup. `$disconnect()` errors at shutdown are logged but not
- * rethrown (the process is already going down; masking shutdown noise must not
- * abort an otherwise-clean teardown).
- *
- * The returned class is a concrete subclass of the supplied client, so callers
- * keep the FULL typed `PrismaClient` surface (every model delegate, every
- * `$`-method) on the resulting service — plus `forOrg`/`asSystem`.
- *
- * @example Per-service usage — the entire `prisma.service.ts` becomes:
- * ```ts
- * import { createBiomePrismaService } from '@xemahq/biome-database-nest';
- * import { PrismaClient } from '../../generated/prisma-client'; // its own
- *
- * export class PrismaService extends createBiomePrismaService(PrismaClient) {}
- * ```
- *
- * The `provide: PrismaService` factory still gates on `BIOME_DATABASE_READY`
- * exactly as before — this factory changes only how the class body is written.
- *
- * @param PrismaClientCtor the service's OWN generated `PrismaClient` constructor.
- * @param optionsOrLoggerContext either the legacy logger-context string
- *   (defaults to `'PrismaService'`) or a {@link CreateBiomePrismaServiceOptions}
- *   bag carrying `loggerContext` + `tenantIsolation`.
- */
-export function createBiomePrismaService<TClient extends BiomePrismaClient>(
-  PrismaClientCtor: BiomePrismaClientCtor<TClient>,
-  optionsOrLoggerContext?: string | CreateBiomePrismaServiceOptions,
-): Type<BiomePrismaServiceInstance<TClient>> {
-  const options = normalizeOptions(optionsOrLoggerContext);
-  const loggerContext = options.loggerContext ?? 'PrismaService';
-  const tenantOptions = options.tenantIsolation ?? {};
-  const orgField = tenantOptions.orgField ?? DEFAULT_ORG_FIELD;
-  const exemptModels = tenantOptions.exemptModels ?? [];
-  const unscopedModels = tenantOptions.unscopedModels ?? {};
-
-  @Injectable()
-  class BiomePrismaService
-    extends (PrismaClientCtor as BiomePrismaClientCtor<BiomePrismaClient>)
-    implements OnModuleInit, OnModuleDestroy
-  {
-    private readonly biomePrismaLogger = new Logger(loggerContext);
-
-    constructor() {
-      super({ adapter: createBiomePrismaAdapterFromEnv() });
-
-      // Fail-fast at construction: an invalid XEMA_TENANT_ISOLATION_MODE (or
-      // option) must abort boot, never fall back to a weaker mode.
-      const mode = resolveTenantIsolationMode(tenantOptions.mode);
-      const raw = this;
-      const tenantLogger: TenantIsolationLogger = new Logger(
-        `${loggerContext}:tenant-isolation`,
-      );
-
-      const requireExtends = (): ((extension: unknown) => unknown) => {
-        const extendsFn = (raw as ExtendableClient).$extends;
-        if (typeof extendsFn !== 'function') {
-          throw new Error(
-            '[tenant-isolation] the Prisma client has no $extends — tenant ' +
-              'isolation requires a generated @prisma/client >= 5 (this SDK peers on ^7).',
-          );
-        }
-        return extendsFn.bind(raw);
-      };
-
-      // Org-scoped-model detection reads the client's runtime data model. In
-      // Off mode it is DEFERRED (the kill switch must never be able to fail a
-      // boot); forOrg() still resolves it lazily on first use.
-      let scopedModelsCache: ReadonlySet<string> | undefined;
-      const getScopedModels = (): ReadonlySet<string> => {
-        scopedModelsCache ??= collectOrgScopedModels(
-          raw,
-          orgField,
-          exemptModels,
-        );
-        return scopedModelsCache;
-      };
-
-      // Close the blind spot BEFORE any client is handed out: a model with no
-      // org column can never be auto-scoped, so enforcement silently does not
-      // apply to it. Every such model must be DECLARED with a justification.
-      // Enforce → throws here and Nest aborts startup; Observe → one loud warn;
-      // Off → skipped with the rest of the detection (kill switch).
-      if (mode !== TenantIsolationMode.Off) {
-        assertUnscopedModelsDeclared({
-          models: readRuntimeModels(raw),
-          orgField,
-          mode,
-          unscopedModels,
-          exemptModels,
-          logger: tenantLogger,
-        });
-      }
-
-      const forOrg = (orgId: string): TClient => {
-        if (typeof orgId !== 'string' || orgId === '') {
-          throw new Error(
-            '[tenant-isolation] forOrg requires a non-empty orgId. For a ' +
-              'legitimate cross-org system path use asSystem().',
-          );
-        }
-        // Explicit scoping ALWAYS enforces, regardless of the global mode.
-        const orgScopedModels = getScopedModels();
-        return requireExtends()(
-          createTenantIsolationExtension({
-            orgScopedModels,
-            orgField,
-            mode: TenantIsolationMode.Enforce,
-            orgIdSource: () => orgId,
-            logger: tenantLogger,
-          }),
-        ) as TClient;
-      };
-
-      const seenSystemCallSites = new Set<string>();
-      const asSystem = (): TClient => {
-        // Debug-log each distinct call site ONCE (auditable, no log floods).
-        const callSite = new Error().stack?.split('\n')[2]?.trim();
-        if (callSite !== undefined && !seenSystemCallSites.has(callSite)) {
-          seenSystemCallSites.add(callSite);
-          tenantLogger.debug(
-            `[tenant-isolation] asSystem() unscoped access from ${callSite}`,
-          );
-        }
-        return raw as unknown as TClient;
-      };
-
-      if (mode === TenantIsolationMode.Off) {
-        // Kill switch: the default client is the raw client; only the
-        // explicit-scoping API is layered on.
-        return new Proxy(raw, {
-          get(target, prop, _receiver): unknown {
-            if (prop === 'forOrg') {
-              return forOrg;
-            }
-            if (prop === 'asSystem') {
-              return asSystem;
-            }
-            const value = Reflect.get(target, prop, target);
-            return typeof value === 'function' ? value.bind(target) : value;
-          },
-        });
-      }
-
-      const ambientClient = requireExtends()(
-        createTenantIsolationExtension({
-          orgScopedModels: getScopedModels(),
-          orgField,
-          mode,
-          orgIdSource: getAmbientOrgId,
-          logger: tenantLogger,
-        }),
-      ) as Record<string, unknown>;
-
-      // Delegates of org-scoped models — and $transaction, so interactive
-      // transactions get extension-applied tx clients — route through the
-      // ambient-scoped extension; everything else hits the raw client.
-      const routedProps = new Set<string>(['$transaction']);
-      for (const modelName of getScopedModels()) {
-        routedProps.add(lowerFirst(modelName));
-      }
-
-      return new Proxy(raw, {
-        get(target, prop, _receiver): unknown {
-          if (prop === 'forOrg') {
-            return forOrg;
-          }
-          if (prop === 'asSystem') {
-            return asSystem;
-          }
-          if (typeof prop === 'string' && routedProps.has(prop)) {
-            const value = ambientClient[prop];
-            return typeof value === 'function'
-              ? (value as (...args: unknown[]) => unknown).bind(ambientClient)
-              : value;
-          }
-          const value = Reflect.get(target, prop, target);
-          return typeof value === 'function' ? value.bind(target) : value;
-        },
-      });
-    }
-
-    async onModuleInit(): Promise<void> {
-      try {
-        await this.$connect();
-        this.biomePrismaLogger.log('Connected to database');
-      } catch (error) {
-        this.biomePrismaLogger.error('Failed to connect to database', error);
-        throw error;
-      }
-    }
-
-    async onModuleDestroy(): Promise<void> {
-      try {
-        await this.$disconnect();
-        this.biomePrismaLogger.log('Disconnected from database');
-      } catch (error) {
-        this.biomePrismaLogger.error(
-          'Error disconnecting from database',
-          error,
-        );
-      }
-    }
-  }
-
-  return BiomePrismaService as unknown as Type<
-    BiomePrismaServiceInstance<TClient>
-  >;
-}

package/src/lib/role-names.ts

@@ -1,77 +0,0 @@
-import {
-  fitIdentifier,
-  POSTGRES_MAX_IDENTIFIER_LENGTH,
-  sanitizeIdentifierChars,
-} from './identifier';
-
-/**
- * Per-schema Postgres access roles.
- *
- * The org database pool CREATES these roles and grants them on the schema; every
- * consumer that mints a connection asks for one of them BY NAME. Provisioner and
- * consumer therefore have to derive byte-identical names from the same schema
- * name — this module is the single place that derivation exists.
- */
-export enum SchemaRoleKind {
-  ReadWrite = 'rw',
-  ReadOnly = 'ro',
-}
-
-/** `_` + a two-character {@link SchemaRoleKind} value, e.g. `_rw`. */
-export const SCHEMA_ROLE_SUFFIX_LENGTH = 3;
-
-/**
- * Budget for the role BASE. Deliberately smaller than
- * {@link POSTGRES_MAX_IDENTIFIER_LENGTH}: the base gets a `_rw` / `_ro` suffix
- * appended, and the FULL role name is what has to fit in Postgres's 63 bytes.
- * Fitting the base to 63 would let `<63-char base>_rw` be truncated by the
- * server to the same 63 bytes as `<same base>_ro`, silently collapsing the
- * read-write and read-only roles into one.
- */
-export const SCHEMA_ROLE_BASE_MAX_LENGTH =
-  POSTGRES_MAX_IDENTIFIER_LENGTH - SCHEMA_ROLE_SUFFIX_LENGTH;
-
-export interface SchemaRoleNames {
-  readonly rwRoleName: string;
-  readonly roRoleName: string;
-}
-
-/**
- * The shared stem of a schema's role names.
- *
- * The schema name is character-sanitized but NOT collapsed or trimmed: it is
- * already a valid identifier, and collapsing would map the distinct schemas
- * `app__x` and `app_x` onto one role. Distinct schema names whose first
- * {@link SCHEMA_ROLE_BASE_MAX_LENGTH} characters collide would derive the SAME
- * role under naive truncation — causing cross-schema privilege bleed and drop
- * collisions — so an over-budget name gets a hash of the FULL schema name
- * spliced in instead.
- */
-export function schemaRoleBase(schemaName: string): string {
-  return fitIdentifier({
-    candidate: sanitizeIdentifierChars(schemaName),
-    maxLength: SCHEMA_ROLE_BASE_MAX_LENGTH,
-    hashInput: schemaName,
-  });
-}
-
-/** The name of one specific role for a schema. */
-export function schemaRoleName(
-  schemaName: string,
-  kind: SchemaRoleKind,
-): string {
-  return `${schemaRoleBase(schemaName)}_${kind}`;
-}
-
-/**
- * Read-write / read-only role names for a schema. The single source of truth for
- * role-name derivation across provisioning, migration, and every connection
- * consumer — keep all call sites routed through here so the names never drift.
- */
-export function rolesForSchema(schemaName: string): SchemaRoleNames {
-  const base = schemaRoleBase(schemaName);
-  return {
-    rwRoleName: `${base}_${SchemaRoleKind.ReadWrite}`,
-    roRoleName: `${base}_${SchemaRoleKind.ReadOnly}`,
-  };
-}

package/src/lib/schema-name.ts

@@ -1,62 +0,0 @@
-import {
-  fitIdentifier,
-  POSTGRES_MAX_IDENTIFIER_LENGTH,
-  sanitizeIdentifierSegment,
-} from './identifier';
-
-/**
- * The default database key. A biome's primary database carries no `__<key>`
- * suffix on its schema name; only additional, non-primary databases do.
- */
-export const DEFAULT_BIOME_DB_KEY = 'primary';
-
-const SCHEMA_PREFIX = 'biome';
-
-/**
- * Derive the Postgres schema name a biome's tables live in inside the shared
- * `xema_biomes` database.
- *
- * Convention:
- * - primary DB (`dbKey` omitted or `'primary'`) → `biome_<biomeId>`
- * - additional DB                               → `biome_<biomeId>__<dbKey>`
- *
- * Each part is sanitised independently (see {@link sanitizeIdentifierSegment});
- * the `__` (double underscore) is the only place two underscores survive
- * collapsing, so it unambiguously separates the biome id from the db key.
- *
- * Over-budget names are fitted by {@link fitIdentifier}, hashing the RAW
- * (pre-sanitisation) parts joined by `:` so two different inputs can never
- * collide.
- */
-export function deriveBiomeSchemaName(biomeId: string, dbKey?: string): string {
-  const sanitizedBiomeId = sanitizeIdentifierSegment(biomeId);
-  if (sanitizedBiomeId.length === 0) {
-    throw new Error(
-      `deriveBiomeSchemaName: biomeId "${biomeId}" sanitises to an empty identifier`,
-    );
-  }
-
-  const isDefaultKey =
-    dbKey === undefined || dbKey === '' || dbKey === DEFAULT_BIOME_DB_KEY;
-  const sanitizedDbKey = isDefaultKey ? '' : sanitizeIdentifierSegment(dbKey);
-
-  if (!isDefaultKey && sanitizedDbKey.length === 0) {
-    throw new Error(
-      `deriveBiomeSchemaName: dbKey "${dbKey}" sanitises to an empty identifier`,
-    );
-  }
-
-  const candidate = isDefaultKey
-    ? `${SCHEMA_PREFIX}_${sanitizedBiomeId}`
-    : `${SCHEMA_PREFIX}_${sanitizedBiomeId}__${sanitizedDbKey}`;
-
-  // The hash covers the raw parts so the disambiguating suffix is stable across
-  // calls and distinguishes inputs that sanitise to the same prefix.
-  const hashParts = isDefaultKey ? [biomeId] : [biomeId, dbKey];
-
-  return fitIdentifier({
-    candidate,
-    maxLength: POSTGRES_MAX_IDENTIFIER_LENGTH,
-    hashInput: hashParts.join(':'),
-  });
-}