@xemahq/biome-database-nest 0.12.0 → 0.12.2

package/src/lib/tenant-isolation/tenant-isolation.extension.ts

@@ -1,203 +0,0 @@
-/**
- * The Prisma client-extension face of tenant isolation: detects org-scoped
- * models from the client's runtime data model at construction time and applies
- * the pure {@link scopeArgsToOrg} transformers per operation, throwing or
- * warning per {@link TenantIsolationMode}. Framework-free (the logger is a
- * structural interface — the Nest factory injects a Nest `Logger`).
- */
-import { scopeArgsToOrg } from './org-scope';
-import {
-  TenantIsolationError,
-  TenantIsolationViolationKind,
-  formatTenantIsolationViolation,
-  type TenantIsolationViolation,
-} from './tenant-isolation-error';
-import { TenantIsolationMode } from './tenant-isolation-mode';
-
-/** The org column enforced when a model declares one (see design C3). */
-export const DEFAULT_ORG_FIELD = 'orgId';
-
-/** Structural logger so this module stays Nest-free (Nest `Logger` satisfies it). */
-export interface TenantIsolationLogger {
-  warn(message: string): void;
-  debug(message: string): void;
-}
-
-export interface RuntimeDataModelField {
-  readonly name: string;
-}
-
-export interface RuntimeDataModelModel {
-  readonly fields: readonly RuntimeDataModelField[];
-}
-
-interface RuntimeDataModelCarrier {
-  readonly _runtimeDataModel?: {
-    readonly models?: Readonly<Record<string, RuntimeDataModelModel>>;
-  };
-}
-
-/**
- * The client's runtime data model, or a hard error. Exported so the unscoped-
- * model declaration check reads the SAME source of truth as org-scoped-model
- * detection — two readers of one schema view, never two views.
- */
-export function readRuntimeModels(
-  client: unknown,
-): Readonly<Record<string, RuntimeDataModelModel>> {
-  const models = (client as RuntimeDataModelCarrier)._runtimeDataModel?.models;
-  if (models === undefined) {
-    throw new Error(
-      '[tenant-isolation] the Prisma client exposes no _runtimeDataModel.models — ' +
-        'cannot detect org-scoped models. Tenant isolation requires a generated ' +
-        '@prisma/client >= 5 (this SDK peers on ^7).',
-    );
-  }
-  return models;
-}
-
-/**
- * Detect which models are org-scoped: every model in the client's runtime data
- * model that declares a field named `orgField`, minus `exemptModels`.
- *
- * Fail-fast: an exempt name that matches NO model throws — a typo'd exemption
- * must never silently exempt nothing (or worse, look like it exempted the
- * intended model).
- */
-export function collectOrgScopedModels(
-  client: unknown,
-  orgField: string,
-  exemptModels: readonly string[],
-): ReadonlySet<string> {
-  const models = readRuntimeModels(client);
-  for (const exempt of exemptModels) {
-    if (!(exempt in models)) {
-      throw new Error(
-        `[tenant-isolation] exemptModels names unknown model "${exempt}" — ` +
-          `known models: ${Object.keys(models).join(', ')}.`,
-      );
-    }
-  }
-  const scoped = new Set<string>();
-  for (const [name, model] of Object.entries(models)) {
-    if (exemptModels.includes(name)) {
-      continue;
-    }
-    if (model.fields.some((field) => field.name === orgField)) {
-      scoped.add(name);
-    }
-  }
-  return scoped;
-}
-
-/** The shape Prisma passes to a `$allModels.$allOperations` query callback. */
-export interface TenantIsolationQueryContext {
-  readonly model?: string;
-  readonly operation: string;
-  readonly args?: Record<string, unknown>;
-  readonly query: (args: unknown) => Promise<unknown>;
-}
-
-export interface CreateTenantIsolationExtensionOptions {
-  /** Output of {@link collectOrgScopedModels}. */
-  readonly orgScopedModels: ReadonlySet<string>;
-  readonly orgField: string;
-  readonly mode: TenantIsolationMode;
-  /**
-   * Where the scope's org comes from per operation: the ambient accessor
-   * (`getAmbientOrgId`) for the default client, or a constant for
-   * `forOrg(orgId)` clients. `undefined` = no org context.
-   */
-  readonly orgIdSource: () => string | undefined;
-  readonly logger: TenantIsolationLogger;
-}
-
-/** The `$extends` argument shape produced by {@link createTenantIsolationExtension}. */
-export interface TenantIsolationExtensionDefinition {
-  readonly name: string;
-  readonly query: {
-    readonly $allModels: {
-      $allOperations(ctx: TenantIsolationQueryContext): Promise<unknown>;
-    };
-  };
-}
-
-/**
- * Build the `$extends` argument that applies org scoping to every operation on
- * every org-scoped model.
- *
- * - `Enforce`: run the rewritten args; throw {@link TenantIsolationError} on
- *   any violation (org mismatch, missing org context, unsupported operation).
- * - `Observe`: run the ORIGINAL args (zero behavior change) and warn each
- *   violation Enforce would reject.
- * - `Off`: full passthrough.
- */
-export function createTenantIsolationExtension(
-  options: CreateTenantIsolationExtensionOptions,
-): TenantIsolationExtensionDefinition {
-  const { orgScopedModels, orgField, mode, orgIdSource, logger } = options;
-
-  const handleViolations = (
-    violations: readonly TenantIsolationViolation[],
-  ): void => {
-    const [first] = violations;
-    if (first === undefined) {
-      return;
-    }
-    if (mode === TenantIsolationMode.Enforce) {
-      throw new TenantIsolationError(first);
-    }
-    for (const violation of violations) {
-      logger.warn(formatTenantIsolationViolation(violation));
-    }
-  };
-
-  return {
-    name: 'xema-tenant-isolation',
-    query: {
-      $allModels: {
-        $allOperations(ctx: TenantIsolationQueryContext): Promise<unknown> {
-          const { model, operation, args, query } = ctx;
-          if (
-            mode === TenantIsolationMode.Off ||
-            model === undefined ||
-            !orgScopedModels.has(model)
-          ) {
-            return query(args);
-          }
-
-          const orgId = orgIdSource();
-          if (orgId === undefined || orgId === '') {
-            handleViolations([
-              {
-                kind: TenantIsolationViolationKind.MissingOrgContext,
-                model,
-                operation,
-                orgField,
-              },
-            ]);
-            // Observe only — Enforce threw above.
-            return query(args);
-          }
-
-          const outcome = scopeArgsToOrg({
-            model,
-            operation,
-            args,
-            orgId,
-            orgField,
-          });
-          if (outcome.violations.length > 0) {
-            handleViolations(outcome.violations);
-            // Observe only — Enforce threw above. Run the ORIGINAL args;
-            // never a half-rewritten query.
-            return query(args);
-          }
-          return mode === TenantIsolationMode.Enforce
-            ? query(outcome.args)
-            : query(args);
-        },
-      },
-    },
-  };
-}

package/src/lib/tenant-isolation/unscoped-models.ts

@@ -1,272 +0,0 @@
-/**
- * ─────────────────────────────────────────────────────────────────────────────
- * The blind spot this module closes.
- *
- * {@link collectOrgScopedModels} treats a model as org-scoped ONLY when it
- * DECLARES the org column. A model with no org column is therefore invisible to
- * the isolation extension: every query on it passes through UNSCOPED, silently,
- * even in {@link TenantIsolationMode.Enforce}. That silence is the whole
- * problem — `Enforce` reads as "this service is isolated", but it only ever
- * covered the models that happened to carry an `orgId`.
- *
- * That is not a hypothetical. `ProjectRepositoryBinding` (scm-connector-api)
- * has no `orgId` — it is owned transitively via `orgRepositoryId ->
- * OrgRepository.orgId` — so enforcement never applied to it, and eight
- * cross-org queries lived there unnoticed, including a destructive
- * CloudEvent-driven `deleteByProjectId` and, on the sibling connector edge, a
- * cross-tenant PLAINTEXT-credential read.
- *
- * The fix is not to guess. A model with no org column can be either:
- *
- *  - GENUINELY GLOBAL — a platform catalog, a kernel-shipped registry, a
- *    bookkeeping table. Correctly unscoped.
- *  - TENANT-SCOPED-INVISIBLE — the rows DO belong to a tenant, reached through
- *    a foreign key to something that carries the org. These MUST be fenced by
- *    hand at every query (`owner: { orgId }`), and nothing in the runtime can
- *    infer that for them.
- *
- * Only the schema's author can tell those apart, so the runtime demands the
- * answer instead of assuming one: every model with no org column must be
- * DECLARED, with a written justification, via
- * {@link TenantIsolationServiceOptions.unscopedModels}. An undeclared one is a
- * boot-time error in `Enforce` and a loud warning in `Observe` — never a silent
- * pass-through.
- * ─────────────────────────────────────────────────────────────────────────────
- */
-import { TenantIsolationMode } from './tenant-isolation-mode';
-
-import type { TenantIsolationLogger } from './tenant-isolation.extension';
-
-/**
- * Why a model carries no org column, and — when it is tenant-scoped in reality
- * — how its queries are fenced instead.
- *
- * A bare string is accepted as shorthand for `{ reason }`.
- */
-export interface UnscopedModelDeclaration {
-  /**
-   * Why this model has no org column. Must be a real sentence, not a
-   * placeholder: this text is the record of a security decision and is what a
-   * future reader (or auditor) sees. Blank/whitespace is rejected.
-   */
-  readonly reason: string;
-  /**
-   * REQUIRED when the model is tenant-scoped in reality: the fence its queries
-   * carry instead of the auto-scope, e.g.
-   * `"orgRepository: { orgId } relation filter on every query"`.
-   * Omit ONLY for genuinely global models.
-   */
-  readonly fencedBy?: string;
-}
-
-/** Declaration map: Prisma model name → justification. */
-export type UnscopedModelDeclarations = Readonly<
-  Record<string, string | UnscopedModelDeclaration>
->;
-
-/** Normalized form of one declaration. */
-export interface NormalizedUnscopedModelDeclaration {
-  readonly model: string;
-  readonly reason: string;
-  readonly fencedBy?: string;
-}
-
-/**
- * Thrown when the set of models carrying no org column does not match what the
- * service declared. Fail-fast: in `Enforce` this aborts boot.
- */
-export class UndeclaredUnscopedModelsError extends Error {
-  /** Models with no org column that were never declared. */
-  readonly undeclared: readonly string[];
-  /** Declared names that no longer match a model with no org column. */
-  readonly staleDeclarations: readonly string[];
-
-  constructor(
-    undeclared: readonly string[],
-    staleDeclarations: readonly string[],
-    orgField: string,
-  ) {
-    super(
-      formatUnscopedModelReport(undeclared, staleDeclarations, orgField, true),
-    );
-    this.name = 'UndeclaredUnscopedModelsError';
-    this.undeclared = undeclared;
-    this.staleDeclarations = staleDeclarations;
-  }
-}
-
-/**
- * Every model in the client's runtime data model that does NOT declare
- * `orgField` — the set the isolation extension can never auto-scope.
- */
-export function collectUnscopableModels(
-  models: Readonly<
-    Record<string, { readonly fields: readonly { readonly name: string }[] }>
-  >,
-  orgField: string,
-): readonly string[] {
-  return Object.entries(models)
-    .filter(([, model]) => !model.fields.some((f) => f.name === orgField))
-    .map(([name]) => name)
-    .sort();
-}
-
-/**
- * Normalize + validate the declaration map on its own terms (before it is
- * compared against the schema). Fail-fast on a blank reason: an empty
- * justification is a rubber stamp, and a rubber stamp is exactly the silent
- * pass-through this mechanism exists to remove.
- */
-export function normalizeUnscopedModelDeclarations(
-  declarations: UnscopedModelDeclarations,
-): readonly NormalizedUnscopedModelDeclaration[] {
-  return Object.entries(declarations).map(([model, value]) => {
-    const declaration: UnscopedModelDeclaration =
-      typeof value === 'string' ? { reason: value } : value;
-    if (declaration.reason.trim().length === 0) {
-      throw new Error(
-        `[tenant-isolation] unscopedModels["${model}"] has a blank reason. ` +
-          'Every model with no org column must carry a written justification — ' +
-          'say whether it is genuinely global, or tenant-scoped-in-reality and ' +
-          'fenced by hand (then also set `fencedBy`).',
-      );
-    }
-    if (
-      declaration.fencedBy !== undefined &&
-      declaration.fencedBy.trim().length === 0
-    ) {
-      throw new Error(
-        `[tenant-isolation] unscopedModels["${model}"].fencedBy is blank. ` +
-          'Either describe the manual fence or omit the field entirely.',
-      );
-    }
-    return {
-      model,
-      reason: declaration.reason,
-      ...(declaration.fencedBy !== undefined
-        ? { fencedBy: declaration.fencedBy }
-        : {}),
-    };
-  });
-}
-
-/** Render the actionable boot message for a declaration mismatch. */
-export function formatUnscopedModelReport(
-  undeclared: readonly string[],
-  staleDeclarations: readonly string[],
-  orgField: string,
-  fatal: boolean,
-): string {
-  const lines: string[] = [
-    `[tenant-isolation] ${fatal ? 'REFUSING TO START' : 'UNDECLARED MODELS'} — ` +
-      `tenant isolation cannot scope every model in this schema.`,
-  ];
-  if (undeclared.length > 0) {
-    lines.push(
-      `  ${undeclared.length} model(s) declare no "${orgField}" column and were ` +
-        `not declared in tenantIsolation.unscopedModels, so every query on them ` +
-        `runs UNSCOPED and enforcement silently does not apply:`,
-      `    ${undeclared.join(', ')}`,
-      '  For EACH one, decide which it is and record the decision:',
-      '    - GENUINELY GLOBAL (platform catalog, kernel registry, bookkeeping) →',
-      '        unscopedModels: { Foo: "global catalog; rows belong to no tenant" }',
-      '    - TENANT-SCOPED via a foreign key (the dangerous case) → fence EVERY',
-      '      query by hand through the owning relation, then record how:',
-      '        unscopedModels: { Foo: { reason: "owned via barId -> Bar.orgId",',
-      '                                 fencedBy: "bar: { orgId } on every query" } }',
-      '  A model that carries the org column but must NOT be scoped belongs in',
-      '  `exemptModels` instead — that is a different decision and stays separate.',
-    );
-  }
-  if (staleDeclarations.length > 0) {
-    lines.push(
-      `  ${staleDeclarations.length} declaration(s) no longer match a model ` +
-        `without "${orgField}" — the schema moved on and the justification is ` +
-        'now misleading. Remove them (or move them to `exemptModels` if the ' +
-        'model gained an org column but must stay unscoped):',
-      `    ${staleDeclarations.join(', ')}`,
-    );
-  }
-  return lines.join('\n');
-}
-
-export interface AssertUnscopedModelsOptions {
-  /** Runtime data model of the generated client. */
-  readonly models: Readonly<
-    Record<string, { readonly fields: readonly { readonly name: string }[] }>
-  >;
-  readonly orgField: string;
-  readonly mode: TenantIsolationMode;
-  /** Declarations for models with NO org column. */
-  readonly unscopedModels: UnscopedModelDeclarations;
-  /** Models that DO carry the org column but are deliberately not scoped. */
-  readonly exemptModels: readonly string[];
-  readonly logger: TenantIsolationLogger;
-}
-
-/**
- * Compare the schema against the declarations and act per mode.
- *
- * - `Enforce` → THROW {@link UndeclaredUnscopedModelsError} (boot aborts).
- * - `Observe` → one loud `warn` carrying the same report (rollout mode keeps
- *   its promise of zero behaviour change).
- * - `Off` → nothing; the kill switch must never be able to fail a boot.
- *
- * This is a STARTUP check rather than a per-query one on purpose. Startup is
- * strictly stronger here: it sees 100% of the schema deterministically, while a
- * query-time check only fires on code paths that actually execute (and would
- * require routing every model delegate through the extension, which changes the
- * proxy surface and adds cost on models the extension has nothing to do). It
- * also fails at the earliest possible moment — a deploy, not a request.
- */
-export function assertUnscopedModelsDeclared(
-  options: AssertUnscopedModelsOptions,
-): void {
-  const { models, orgField, mode, unscopedModels, exemptModels, logger } =
-    options;
-  if (mode === TenantIsolationMode.Off) {
-    return;
-  }
-
-  const normalized = normalizeUnscopedModelDeclarations(unscopedModels);
-  const unscopable = new Set(collectUnscopableModels(models, orgField));
-
-  for (const { model } of normalized) {
-    if (!(model in models)) {
-      throw new Error(
-        `[tenant-isolation] unscopedModels names unknown model "${model}" — ` +
-          `known models: ${Object.keys(models).join(', ')}.`,
-      );
-    }
-  }
-
-  // A model listed in BOTH lists is a contradiction: `exemptModels` means "has
-  // the org column, deliberately not scoped"; `unscopedModels` means "has no
-  // org column at all". Never let one silently shadow the other.
-  const declaredUnscoped = new Set(normalized.map((d) => d.model));
-  const inBoth = exemptModels.filter((m) => declaredUnscoped.has(m));
-  if (inBoth.length > 0) {
-    throw new Error(
-      `[tenant-isolation] ${inBoth.join(', ')} appear in BOTH exemptModels and ` +
-        'unscopedModels. They answer different questions — exemptModels means ' +
-        `"declares ${orgField} but must not be auto-scoped"; unscopedModels ` +
-        `means "declares no ${orgField} at all". Pick the one that is true.`,
-    );
-  }
-
-  const undeclared = [...unscopable].filter((m) => !declaredUnscoped.has(m));
-  const stale = [...declaredUnscoped].filter((m) => !unscopable.has(m)).sort();
-
-  if (undeclared.length === 0 && stale.length === 0) {
-    logger.debug(
-      `[tenant-isolation] ${unscopable.size} model(s) carry no "${orgField}" ` +
-        'column; all are declared in unscopedModels.',
-    );
-    return;
-  }
-
-  if (mode === TenantIsolationMode.Enforce) {
-    throw new UndeclaredUnscopedModelsError(undeclared, stale, orgField);
-  }
-  logger.warn(formatUnscopedModelReport(undeclared, stale, orgField, false));
-}