@xemahq/biome-database-nest 0.9.0 → 0.10.0

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

@@ -0,0 +1,269 @@
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 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));
+}

package/dist/lib/credential-generation.d.ts

@@ -1,4 +0,0 @@
-export declare const MAX_DATABASE_CREDENTIAL_GENERATION = 2147483647;
-export declare function assertDatabaseCredentialGeneration(value: number, field: string): void;
-export declare function parseDatabaseCredentialGeneration(value: string, field: string): number;
-//# sourceMappingURL=credential-generation.d.ts.map

package/dist/lib/credential-generation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"credential-generation.d.ts","sourceRoot":"","sources":["../../src/lib/credential-generation.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kCAAkC,aAAgB,CAAC;AAIhE,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,IAAI,CAWN;AAED,wBAAgB,iCAAiC,CAC/C,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,GACZ,MAAM,CASR"}

package/dist/lib/credential-generation.js

@@ -1,24 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MAX_DATABASE_CREDENTIAL_GENERATION = void 0;
-exports.assertDatabaseCredentialGeneration = assertDatabaseCredentialGeneration;
-exports.parseDatabaseCredentialGeneration = parseDatabaseCredentialGeneration;
-exports.MAX_DATABASE_CREDENTIAL_GENERATION = 2_147_483_647;
-const CANONICAL_POSITIVE_DECIMAL = /^[1-9][0-9]*$/;
-function assertDatabaseCredentialGeneration(value, field) {
-    if (!Number.isSafeInteger(value) ||
-        value <= 0 ||
-        value > exports.MAX_DATABASE_CREDENTIAL_GENERATION) {
-        throw new Error(`${field} must be a safe positive integer no greater than ` +
-            `${exports.MAX_DATABASE_CREDENTIAL_GENERATION}.`);
-    }
-}
-function parseDatabaseCredentialGeneration(value, field) {
-    if (!CANONICAL_POSITIVE_DECIMAL.test(value)) {
-        throw new Error(`${field} value "${value}" must be a canonical positive decimal integer.`);
-    }
-    const generation = Number(value);
-    assertDatabaseCredentialGeneration(generation, field);
-    return generation;
-}
-//# sourceMappingURL=credential-generation.js.map

package/dist/lib/credential-generation.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"credential-generation.js","sourceRoot":"","sources":["../../src/lib/credential-generation.ts"],"names":[],"mappings":";;;AAIA,gFAcC;AAED,8EAYC;AAhCY,QAAA,kCAAkC,GAAG,aAAa,CAAC;AAEhE,MAAM,0BAA0B,GAAG,eAAe,CAAC;AAEnD,SAAgB,kCAAkC,CAChD,KAAa,EACb,KAAa;IAEb,IACE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC;QAC5B,KAAK,IAAI,CAAC;QACV,KAAK,GAAG,0CAAkC,EAC1C,CAAC;QACD,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,mDAAmD;YACzD,GAAG,0CAAkC,GAAG,CAC3C,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAgB,iCAAiC,CAC/C,KAAa,EACb,KAAa;IAEb,IAAI,CAAC,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,GAAG,KAAK,WAAW,KAAK,iDAAiD,CAC1E,CAAC;IACJ,CAAC;IACD,MAAM,UAAU,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,kCAAkC,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACtD,OAAO,UAAU,CAAC;AACpB,CAAC"}

package/dist/lib/external-runtime-verifier.d.ts

@@ -1,3 +0,0 @@
-import type { MigrationCompatibilityContext, MigrationCompatibilityExpectation, RuntimeDatabaseAccessExpectation, RuntimeDatabaseTarget } from './migration-mode';
-export declare function verifyExternallyManagedRuntime(runtimeUrl: string, target: RuntimeDatabaseTarget, access: RuntimeDatabaseAccessExpectation, compatibility: MigrationCompatibilityExpectation): Promise<MigrationCompatibilityContext>;
-//# sourceMappingURL=external-runtime-verifier.d.ts.map

package/dist/lib/external-runtime-verifier.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"external-runtime-verifier.d.ts","sourceRoot":"","sources":["../../src/lib/external-runtime-verifier.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAEV,6BAA6B,EAC7B,iCAAiC,EACjC,gCAAgC,EAEhC,qBAAqB,EAEtB,MAAM,kBAAkB,CAAC;AAugC1B,wBAAsB,8BAA8B,CAClD,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,gCAAgC,EACxC,aAAa,EAAE,iCAAiC,GAC/C,OAAO,CAAC,6BAA6B,CAAC,CAwfxC"}