Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -19,6 +19,14 @@ operator runbook (setup, key management, restore drill, troubleshooting).
## Environment variables
Database-backed operator commands use the restricted `hivegrid_app`
connection and require `HIVEGRID_CLI_OPERATOR_USER_ID` to contain the ID of an
existing `AdminUser`. The CLI validates that identity and binds it as
`app.user_id`; commands with `--tenant`, `--tenantId`, or `--tenant-id`
additionally bind that single tenant as `app.tenant_id`. Do not use the
migrator DSN as a CLI bypass.
Scaffolding, plugin-authoring and backup commands do not require this variable.
The CLI uses a backup-scoped S3 credential set so the backup bucket can be
isolated from the application bucket:
@@ -6,7 +6,9 @@
"sideEffects": false,
"exports": {
".": "./src/index.ts",
"./backup": "./src/commands/backup/index.ts"
"./backup": "./src/commands/backup/index.ts",
"./tenant-models": "./src/commands/tenant/models.ts",
"./tenant-derived-models": "./src/commands/tenant/derived-models.ts"
},
"bin": {
"hivegrid-cli": "./bin/hivegrid-cli.mjs"
@@ -17,23 +19,24 @@
"typecheck": "tsc -p tsconfig.json --noEmit"
},
"dependencies": {
"@aws-sdk/client-s3": "^3.1048.0",
"@aws-sdk/lib-storage": "^3.1048.0",
"@aws-sdk/client-s3": "3.1048.0",
"@aws-sdk/lib-storage": "3.1048.0",
"@hivegrid/billing": "workspace:*",
"@hivegrid/config": "workspace:*",
"@hivegrid/db": "workspace:*",
"@hivegrid/entitlements": "workspace:*",
"@hivegrid/exports": "workspace:*",
"@hivegrid/feature-flags": "workspace:*",
"@hivegrid/form-widget": "workspace:*",
"@hivegrid/foundation": "workspace:*",
"@hivegrid/plugin-runtime": "workspace:*",
"@hivegrid/search": "workspace:*",
"citty": "^0.1.6",
"consola": "^3.4.0",
"tar": "^7.4.3",
"tar": "^7.5.21",
"zod": "^3.23.8"
},
"devDependencies": {
"@types/node": "^25.0.0",
"@types/tar": "^6.1.13",
"aws-sdk-client-mock": "^4.1.0",
"typescript": "^5.3.2",
"vitest": "^3.2.4"
@@ -19,12 +19,13 @@ import type { AuditPdfEvent } from "@hivegrid/exports/audit-pdf";
*/
const findMany = vi.fn<() => Promise<unknown[]>>();
const checkpointFindMany = vi.fn<() => Promise<unknown[]>>();
const verifyAuditChain = vi.fn();
const serializeAuditEventsToPdf = vi.fn<() => Promise<Uint8Array>>();
const writeFile = vi.fn<() => Promise<void>>();
vi.mock("@hivegrid/db/client.server", () => ({
getReadDbClient: () => ({ auditEvent: { findMany } }),
getReadDbClient: () => ({ auditEvent: { findMany }, auditChainCheckpoint: { findMany: checkpointFindMany } }),
}));
vi.mock("@hivegrid/db/audit-hash", () => ({
verifyAuditChain: (...args: unknown[]) => verifyAuditChain(...(args as [])),
@@ -79,6 +80,7 @@ describe("audit verify-chain command wrapper", () => {
vi.clearAllMocks();
process.exitCode = undefined;
findMany.mockResolvedValue([]);
checkpointFindMany.mockResolvedValue([]);
verifyAuditChain.mockReturnValue({ ok: true, inspected: 0, firstBreak: undefined });
});
@@ -128,7 +130,7 @@ describe("audit verify-chain command wrapper", () => {
);
expect(verifyAuditChain).toHaveBeenCalledWith(
expect.arrayContaining([expect.objectContaining({ id: "evt_last" })]),
{},
{ initialPreviousHash: null },
);
});
@@ -185,6 +187,7 @@ describe("audit export-pdf command wrapper", () => {
vi.clearAllMocks();
process.exitCode = undefined;
findMany.mockResolvedValue([]);
checkpointFindMany.mockResolvedValue([]);
verifyAuditChain.mockReturnValue({ ok: true, inspected: 0, firstBreak: undefined });
serializeAuditEventsToPdf.mockResolvedValue(new Uint8Array([1, 2, 3, 4]));
writeFile.mockResolvedValue(undefined);
@@ -38,7 +38,7 @@ export type AuditExportPdfDependencies = {
limit: number;
}) => Promise<ReadonlyArray<AuditPdfEvent>>;
/** Compute hash-chain integrity over the loaded events. */
verify: (events: ReadonlyArray<AuditPdfEvent>) => AuditPdfIntegrity;
verify: (events: ReadonlyArray<AuditPdfEvent>) => AuditPdfIntegrity | Promise<AuditPdfIntegrity>;
/** Render the PDF document to a byte buffer. */
render: (input: AuditPdfReportInput) => Promise<Uint8Array>;
/** Write the rendered bytes to the chosen output path. */
@@ -88,7 +88,7 @@ export async function runAuditExportPdf(
const regulatoryScope = args.regulatoryScope?.trim() || null;
const events = await deps.loadEvents({ tenantId, from, to, regulatoryScope, limit: AUDIT_PDF_QUERY_LIMIT });
const integrity = deps.verify(events);
const integrity = await deps.verify(events);
const filterSummary = [
regulatoryScope ? `regulatoryScope=${regulatoryScope}` : null,
@@ -137,10 +137,11 @@ export const auditExportPdfCommand = defineCommand({
"generated-by": { type: "string", required: false, description: "Operator display name to embed on the cover page." },
},
async run({ args }) {
const [{ getReadDbClient }, { verifyAuditChain }, { serializeAuditEventsToPdf }] = await Promise.all([
const [{ getReadDbClient }, { verifyAuditChain }, { serializeAuditEventsToPdf }, { auditChainKey, loadAuditVerificationContext }] = await Promise.all([
import("@hivegrid/db/client.server"),
import("@hivegrid/db/audit-hash"),
import("@hivegrid/exports/audit-pdf"),
import("@hivegrid/db/audit-chain-checkpoint.server"),
]);
const db = getReadDbClient();
@@ -173,7 +174,7 @@ export const auditExportPdfCommand = defineCommand({
})) as unknown as ReadonlyArray<AuditPdfEvent>;
return rows;
},
verify(events) {
async verify(events) {
// Convert to AuditChainEvent-compatible shape: id + createdAt as
// strings, the rest matching AuditPdfEvent.
const chainEvents = events.map((e) => ({
@@ -197,7 +198,20 @@ export const auditExportPdfCommand = defineCommand({
previousHash: e.previousHash,
eventHash: e.eventHash,
}));
const result = verifyAuditChain(chainEvents);
const allowPartialPrefix = Boolean(args.from || args["regulatory-scope"]);
const context = await loadAuditVerificationContext(db as never, chainEvents, { allowPartialPrefix });
const key = auditChainKey(String(args.tenant) === "__platform__" ? null : String(args.tenant));
if (context.invalidCheckpointChains.has(key)) {
return {
ok: false,
inspected: 0,
firstBreakId: chainEvents[0]?.id ?? null,
reason: "checkpoint-authentication-failed",
};
}
const result = verifyAuditChain(chainEvents, {
initialPreviousHash: context.initialPreviousHashes.get(key) ?? null,
});
return {
ok: result.ok,
inspected: result.inspected,
@@ -38,11 +38,19 @@ export type AuditVerifyChainDependencies = {
/** Cursor-iterable read of events ordered by createdAt ascending. */
readRows: (args: { tenantId: string; from: Date | null; to: Date | null; batchSize: number }) => AsyncIterable<AuditVerifyChainRow>;
/** Chain verifier — usually `verifyAuditChain` from @hivegrid/db/audit-hash. */
verify: (events: ReadonlyArray<AuditVerifyChainRow>, options?: { secret?: string | null }) => VerifyAuditChainResult;
verify: (
events: ReadonlyArray<AuditVerifyChainRow>,
options?: { secret?: string | null; initialPreviousHash?: string | null },
) => VerifyAuditChainResult;
/** Output sink. Tests pass an array collector; production wires consola. */
output: { info: (msg: string) => void; json: (obj: unknown) => void; error: (msg: string) => void };
/** Optional secret override (otherwise reads AUDIT_CHAIN_SECRET env). */
secret?: string | null;
resolveInitialPreviousHash?: (input: {
tenantId: string;
rows: ReadonlyArray<AuditVerifyChainRow>;
allowPartialPrefix: boolean;
}) => Promise<string | null>;
};
export type AuditVerifyChainOutcome = {
@@ -80,7 +88,17 @@ export async function runAuditVerifyChain(
rows.push(row);
}
const result = deps.verify(rows, deps.secret !== undefined ? { secret: deps.secret } : {});
const initialPreviousHash = rows.length === 0
? null
: deps.resolveInitialPreviousHash
? await deps.resolveInitialPreviousHash({ tenantId, rows, allowPartialPrefix: from !== null })
: from !== null
? rows[0]!.previousHash
: null;
const result = deps.verify(rows, {
...(deps.secret !== undefined ? { secret: deps.secret } : {}),
initialPreviousHash,
});
if (args.json) {
deps.output.json({
@@ -112,6 +130,7 @@ export const auditVerifyChainCommand = defineCommand({
},
async run({ args }) {
const { verifyAuditChain } = await import("@hivegrid/db/audit-hash");
const { auditChainKey, loadAuditVerificationContext } = await import("@hivegrid/db/audit-chain-checkpoint.server");
const { getReadDbClient } = await import("@hivegrid/db/client.server");
const db = getReadDbClient();
const tenantId = String(args.tenant);
@@ -151,6 +170,17 @@ export const auditVerifyChainCommand = defineCommand({
{
readRows,
verify: verifyAuditChain,
resolveInitialPreviousHash: async ({ rows, allowPartialPrefix }) => {
const context = await loadAuditVerificationContext(db as never, rows.map((row) => ({
...row,
createdAt: row.createdAt,
})), { allowPartialPrefix });
const key = auditChainKey(tenantId === "__platform__" ? null : tenantId);
if (context.invalidCheckpointChains.has(key)) {
throw new Error(`Audit checkpoint authentication failed for ${key}.`);
}
return context.initialPreviousHashes.get(key) ?? null;
},
output: {
info: (msg) => consola.success(msg),
json: (obj) => consola.log(JSON.stringify(obj)),
@@ -64,6 +64,15 @@ describe("backup manifest schema", () => {
expect(() => BackupManifestSchema.parse(invalid)).toThrow();
});
it.each(["../outside.dump", "/tmp/outside.dump", "C:/outside.dump", "postgres\\dump.gz", "postgres//dump.gz", "./dump.gz"])(
"rejects unsafe component path %j",
(path) => {
expect(() => deserializeManifest(serializeManifest({ ...baseManifest, components: { postgres: { ...baseManifest.components.postgres!, path } } }))).toThrow(
/safe relative component path/u,
);
},
);
it("sha256Hex returns lowercase hex of expected length", () => {
const hex = sha256Hex("hello world");
expect(hex).toHaveLength(64);
@@ -3,6 +3,14 @@ import { z } from "zod";
export const BACKUP_MANIFEST_VERSION = 1;
function isSafeComponentPath(value: string): boolean {
if (value.includes("\0") || value.includes("\\") || value.startsWith("/") || /^[A-Za-z]:/u.test(value)) {
return false;
}
const segments = value.split("/");
return segments.every((segment) => segment.length > 0 && segment !== "." && segment !== "..");
}
export const ComponentChecksumSchema = z
.object({
algorithm: z.literal("sha256"),
@@ -12,7 +20,7 @@ export const ComponentChecksumSchema = z
export const ComponentEntrySchema = z
.object({
path: z.string().min(1),
path: z.string().min(1).refine(isSafeComponentPath, "expected a safe relative component path"),
sizeBytes: z.number().int().nonnegative(),
checksum: ComponentChecksumSchema,
metadata: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
@@ -1,7 +1,22 @@
import { EventEmitter } from "node:events";
import { createHash } from "node:crypto";
import { mkdtemp, mkdir, realpath, rm, symlink, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { PassThrough } from "node:stream";
import { describe, expect, it } from "vitest";
import { pgRestore } from "./restore.js";
import { afterEach, beforeEach, describe, expect, it } from "vitest";
import { pgRestore, verifyBackupComponent } from "./restore.js";
import type { ComponentEntry } from "./manifest.js";
let workDir = "";
beforeEach(async () => {
workDir = await mkdtemp(join(tmpdir(), "backup-restore-component-"));
});
afterEach(async () => {
await rm(workDir, { recursive: true, force: true });
});
describe("pgRestore", () => {
it("invokes pg_restore with --clean/--if-exists and the dump path last", async () => {
@@ -76,3 +91,68 @@ describe("pgRestore", () => {
await expect(pgRestore({ connectionString: "x", dumpPath: "y", spawnFn })).rejects.toThrow(/missing dump|exited/);
});
});
describe("verifyBackupComponent", () => {
async function componentFixture(contents = "verified backup component"): Promise<{ component: ComponentEntry; path: string }> {
const componentDir = join(workDir, "postgres");
await mkdir(componentDir, { recursive: true });
const path = join(componentDir, "dump.bin");
await writeFile(path, contents);
return {
path,
component: {
path: "postgres/dump.bin",
sizeBytes: Buffer.byteLength(contents),
checksum: { algorithm: "sha256", value: createHash("sha256").update(contents).digest("hex") },
},
};
}
it("returns a contained regular file after size and checksum verification", async () => {
const fixture = await componentFixture();
await expect(verifyBackupComponent(workDir, fixture.component, "Postgres dump")).resolves.toBe(await realpath(fixture.path));
});
it("rejects traversal and symlink escapes", async () => {
const outsideDir = await mkdtemp(join(tmpdir(), "backup-restore-outside-"));
try {
const outsideFile = join(outsideDir, "dump.bin");
await writeFile(outsideFile, "outside");
await symlink(outsideFile, join(workDir, "linked-dump.bin"));
const checksum = createHash("sha256").update("outside").digest("hex");
await expect(
verifyBackupComponent(
workDir,
{ path: "../outside.bin", sizeBytes: 7, checksum: { algorithm: "sha256", value: checksum } },
"Postgres dump",
),
).rejects.toThrow(/escapes/u);
await expect(
verifyBackupComponent(
workDir,
{ path: "linked-dump.bin", sizeBytes: 7, checksum: { algorithm: "sha256", value: checksum } },
"Postgres dump",
),
).rejects.toThrow(/escapes/u);
} finally {
await rm(outsideDir, { recursive: true, force: true });
}
});
it("rejects size and checksum mismatches before restore", async () => {
const fixture = await componentFixture();
await expect(verifyBackupComponent(workDir, { ...fixture.component, sizeBytes: fixture.component.sizeBytes + 1 }, "Postgres dump")).rejects.toThrow(
/size mismatch/u,
);
await expect(
verifyBackupComponent(
workDir,
{ ...fixture.component, checksum: { algorithm: "sha256", value: "0".repeat(64) } },
"Postgres dump",
),
).rejects.toThrow(/checksum mismatch/u);
});
});
@@ -1,14 +1,16 @@
import { defineCommand } from "citty";
import consola from "consola";
import { createHash } from "node:crypto";
import { createReadStream } from "node:fs";
import { spawn, type SpawnOptions } from "node:child_process";
import { mkdir, mkdtemp, readFile, readdir, rm } from "node:fs/promises";
import { lstat, mkdir, mkdtemp, readFile, readdir, realpath, rm, stat } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { isAbsolute, join, relative, resolve, sep } from "node:path";
import { extract as extractTar } from "tar";
import { S3Client } from "@aws-sdk/client-s3";
import { downloadObjectToFile } from "./s3-upload.js";
import { decryptFile } from "./encryption.js";
import { deserializeManifest, type BackupManifest } from "./manifest.js";
import { deserializeManifest, type BackupManifest, type ComponentEntry } from "./manifest.js";
import { resolveBackupConfig, type BackupEnv } from "./env.js";
export interface RunRestoreOptions {
@@ -57,29 +59,32 @@ export async function runRestoreBackup(opts: RunRestoreOptions): Promise<RunRest
if (entries.length !== 1) {
throw new Error(`Unexpected archive layout; got ${entries.length} top-level entries`);
}
const stageDir = join(extractDir, entries[0]);
const stageDir = await resolveExtractedStageDirectory(extractDir, entries[0]);
const manifestRaw = await readFile(join(stageDir, "manifest.json"), "utf8");
const manifestPath = await resolveContainedRegularFile(stageDir, "manifest.json", "backup manifest");
const manifestRaw = await readFile(manifestPath, "utf8");
const manifest = deserializeManifest(manifestRaw);
const dbUrl = opts.targetDatabaseUrl ?? config.databaseUrl;
if (manifest.components.postgres) {
const dumpPath = await verifyBackupComponent(stageDir, manifest.components.postgres, "Postgres dump");
consola.info("Restoring Postgres dump");
await pgRestore({
connectionString: dbUrl,
dumpPath: join(stageDir, manifest.components.postgres.path),
dumpPath,
binary: opts.pgRestoreBinary,
spawnFn: opts.spawnFn,
});
}
if (manifest.components.storage && !opts.skipStorage) {
const storagePath = await verifyBackupComponent(stageDir, manifest.components.storage, "storage archive", { verifySize: false });
// Storage restore is operator-driven via re-upload from the staged tar.
// Implementation lives in storage.ts in a follow-up if/when staging
// verifies the create flow against a real bucket. For now we surface
// a clear hint so the operator can manually re-import.
consola.warn(
`Storage tar at ${join(stageDir, manifest.components.storage.path)} not auto-uploaded; re-upload via aws s3 sync or use --target-bucket in a future revision.`,
`Storage tar at ${storagePath} not auto-uploaded; re-upload via aws s3 sync or use --target-bucket in a future revision.`,
);
}
@@ -89,6 +94,62 @@ export async function runRestoreBackup(opts: RunRestoreOptions): Promise<RunRest
}
}
async function resolveExtractedStageDirectory(extractDir: string, entry: string): Promise<string> {
const extractRoot = await realpath(extractDir);
const candidate = resolve(extractRoot, entry);
assertContainedPath(extractRoot, candidate, "backup stage directory");
const candidateStat = await lstat(candidate);
if (candidateStat.isSymbolicLink() || !candidateStat.isDirectory()) {
throw new Error("Backup stage entry must be a real directory");
}
const resolvedCandidate = await realpath(candidate);
assertContainedPath(extractRoot, resolvedCandidate, "backup stage directory");
return resolvedCandidate;
}
async function resolveContainedRegularFile(rootDir: string, relativePath: string, label: string): Promise<string> {
const root = await realpath(rootDir);
const candidate = resolve(root, relativePath);
assertContainedPath(root, candidate, label);
const resolvedCandidate = await realpath(candidate);
assertContainedPath(root, resolvedCandidate, label);
const candidateStat = await stat(resolvedCandidate);
if (!candidateStat.isFile()) {
throw new Error(`${label} must be a regular file`);
}
return resolvedCandidate;
}
function assertContainedPath(root: string, candidate: string, label: string): void {
const relativePath = relative(root, candidate);
if (relativePath === ".." || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
throw new Error(`${label} escapes the extracted backup directory`);
}
}
export async function verifyBackupComponent(
stageDir: string,
component: ComponentEntry,
label: string,
options: { verifySize?: boolean } = {},
): Promise<string> {
const componentPath = await resolveContainedRegularFile(stageDir, component.path, label);
const componentStat = await stat(componentPath);
if (options.verifySize !== false && componentStat.size !== component.sizeBytes) {
throw new Error(`${label} size mismatch: expected ${component.sizeBytes} bytes, got ${componentStat.size}`);
}
const hash = createHash("sha256");
for await (const chunk of createReadStream(componentPath)) {
hash.update(chunk as Buffer);
}
const actualChecksum = hash.digest("hex");
if (actualChecksum !== component.checksum.value) {
throw new Error(`${label} checksum mismatch`);
}
return componentPath;
}
async function rename(from: string, to: string): Promise<void> {
const fs = await import("node:fs/promises");
await fs.rename(from, to);
@@ -55,7 +55,7 @@ describe("feature flag set-rules command", () => {
tempDir = mkdtempSync(join(tmpdir(), "hivegrid-cli-flags-"));
vi.clearAllMocks();
process.exitCode = undefined;
dbMock.$transaction.mockResolvedValue([]);
dbMock.$transaction.mockImplementation(async (callback: (transaction: typeof dbMock) => Promise<unknown>) => callback(dbMock));
broadcastFlagInvalidationMock.mockResolvedValue(undefined);
});
@@ -129,10 +129,7 @@ describe("feature flag set-rules command", () => {
newValue: { rules: null },
},
});
expect(dbMock.$transaction).toHaveBeenCalledWith([
dbMock.featureFlag.update.mock.results[0]?.value,
dbMock.featureFlagAudit.create.mock.results[0]?.value,
]);
expect(dbMock.$transaction).toHaveBeenCalledWith(expect.any(Function));
expect(broadcastFlagInvalidationMock).toHaveBeenCalledWith("billing.beta");
expect(consoleMock.success).toHaveBeenCalledWith('Rules for "billing.beta" updated.');
});
@@ -37,12 +37,12 @@ async function applyRules(name: string, rulesJson: string): Promise<void> {
process.exitCode = 1;
return;
}
await prisma.$transaction([
prisma.featureFlag.update({
await prisma.$transaction(async (transaction) => {
await transaction.featureFlag.update({
where: { id: existing.id },
data: { rules: (parsed ?? null) as unknown as never },
}),
prisma.featureFlagAudit.create({
});
await transaction.featureFlagAudit.create({
data: {
flagId: existing.id,
actorUserId: null,
@@ -50,8 +50,8 @@ async function applyRules(name: string, rulesJson: string): Promise<void> {
oldValue: { rules: (existing.rules ?? null) as unknown as never },
newValue: { rules: (parsed ?? null) as unknown as never },
},
}),
]);
});
});
await broadcastFlagInvalidation(name);
consola.success(`Rules for "${name}" updated.`);
}
@@ -41,7 +41,7 @@ describe("feature flag toggle commands", () => {
beforeEach(() => {
vi.clearAllMocks();
process.exitCode = undefined;
dbMock.$transaction.mockResolvedValue([]);
dbMock.$transaction.mockImplementation(async (callback: (transaction: typeof dbMock) => Promise<unknown>) => callback(dbMock));
broadcastFlagInvalidationMock.mockResolvedValue(undefined);
});
@@ -94,10 +94,7 @@ describe("feature flag toggle commands", () => {
newValue: { enabled: false },
},
});
expect(dbMock.$transaction).toHaveBeenCalledWith([
dbMock.featureFlag.update.mock.results[0]?.value,
dbMock.featureFlagAudit.create.mock.results[0]?.value,
]);
expect(dbMock.$transaction).toHaveBeenCalledWith(expect.any(Function));
expect(broadcastFlagInvalidationMock).toHaveBeenCalledWith("billing.beta");
expect(consoleMock.success).toHaveBeenCalledWith('Flag "billing.beta" → disabled.');
});
@@ -23,9 +23,9 @@ async function toggleFlag(name: string, target: boolean): Promise<void> {
consola.info(`Flag "${name}" is already ${target ? "enabled" : "disabled"}; no-op.`);
return;
}
await prisma.$transaction([
prisma.featureFlag.update({ where: { id: existing.id }, data: { enabled: target } }),
prisma.featureFlagAudit.create({
await prisma.$transaction(async (transaction) => {
await transaction.featureFlag.update({ where: { id: existing.id }, data: { enabled: target } });
await transaction.featureFlagAudit.create({
data: {
flagId: existing.id,
actorUserId: null,
@@ -33,8 +33,8 @@ async function toggleFlag(name: string, target: boolean): Promise<void> {
oldValue: { enabled: existing.enabled },
newValue: { enabled: target },
},
}),
]);
});
});
await broadcastFlagInvalidation(name);
consola.success(`Flag "${name}" → ${target ? "enabled" : "disabled"}.`);
}
@@ -22,7 +22,7 @@ const dbMock = {
form: {
create: vi.fn<(args: FormCreateArgs) => Promise<{ id: string; key: string }>>(),
findMany: vi.fn<() => Promise<FormRow[]>>(),
findUnique: vi.fn<() => Promise<{ id: string; name: string } | null>>(),
findFirst: vi.fn<() => Promise<{ id: string; name: string } | null>>(),
delete: vi.fn<() => Promise<{ id: string }>>(),
},
};
@@ -120,22 +120,26 @@ describe("forms delete command", () => {
beforeEach(() => {
vi.clearAllMocks();
process.exitCode = undefined;
dbMock.form.findUnique.mockResolvedValue(null);
dbMock.form.findFirst.mockResolvedValue(null);
dbMock.form.delete.mockResolvedValue({ id: "form_1" });
});
it("hard-deletes an existing form and confirms with its name", async () => {
dbMock.form.findUnique.mockResolvedValueOnce({ id: "form_1", name: "Contact" });
dbMock.form.findFirst.mockResolvedValueOnce({ id: "form_1", name: "Contact" });
await formsDeleteCommand.run?.({ args: { id: "form_1" } } as never);
await formsDeleteCommand.run?.({ args: { id: "form_1", tenant: "tenant_1" } } as never);
expect(dbMock.form.findFirst).toHaveBeenCalledWith({
where: { id: "form_1", tenantId: "tenant_1" },
select: { id: true, name: true },
});
expect(dbMock.form.delete).toHaveBeenCalledWith({ where: { id: "form_1" } });
expect(consoleMock.success).toHaveBeenCalledWith("Form deleted: form_1 (Contact).");
expect(process.exitCode).toBeUndefined();
});
it("sets a non-zero exit code and skips the delete when the form is missing", async () => {
await formsDeleteCommand.run?.({ args: { id: "ghost" } } as never);
await formsDeleteCommand.run?.({ args: { id: "ghost", tenant: "tenant_1" } } as never);
expect(consoleMock.error).toHaveBeenCalledWith("Form ghost not found.");
expect(process.exitCode).toBe(1);
@@ -1,5 +1,5 @@
/**
* `forms delete --id <formId>` — hard-delete a form and cascade
* `forms delete --tenant <tenantId> --id <formId>` — hard-delete a form and cascade
* its FormSubmission rows. No soft-delete in Phase-1.
*/
import { defineCommand } from "citty";
@@ -8,13 +8,15 @@ import consola from "consola";
export const formsDeleteCommand = defineCommand({
meta: { name: "delete", description: "Delete a form (cascade submissions)." },
args: {
tenant: { type: "string", required: true, description: "Tenant ID." },
id: { type: "string", required: true, description: "Form ID." },
},
async run({ args }) {
const { getDbClient } = await import("@hivegrid/db/client.server");
const prisma = getDbClient();
const id = String(args.id);
const existing = await prisma.form.findUnique({ where: { id }, select: { id: true, name: true } });
const tenantId = String(args.tenant);
const existing = await prisma.form.findFirst({ where: { id, tenantId }, select: { id: true, name: true } });
if (!existing) {
consola.error(`Form ${id} not found.`);
process.exitCode = 1;
@@ -115,7 +115,7 @@ describe("leads CLI commands", () => {
lastName: 'Love, "Countess"',
phone: null,
company: "Analytical\nEngines",
source: "form",
source: " =CMD()",
status: "new",
utmSource: "newsletter",
createdAt: new Date("2026-05-25T12:00:00.000Z"),
@@ -133,6 +133,7 @@ describe("leads CLI commands", () => {
expect(csv).toContain("id,email,firstName,lastName");
expect(csv).toContain('"Love, ""Countess"""');
expect(csv).toContain('"Analytical\nEngines"');
expect(csv).toContain("' =CMD()");
expect(writeFileMock).not.toHaveBeenCalled();
expect(consoleMock.success).toHaveBeenCalledWith("Exported 1 leads.");
@@ -1,52 +0,0 @@
import { beforeEach, describe, expect, it, vi } from "vitest";
const dbMock = {
lead: {
findUnique: vi.fn<() => Promise<{ email: string } | null>>(),
delete: vi.fn<() => Promise<{ id: string }>>(),
},
};
vi.mock("@hivegrid/db/client.server", () => ({
getDbClient: () => dbMock,
}));
vi.mock("consola", () => ({
default: {
warn: vi.fn(),
success: vi.fn(),
},
}));
import consola from "consola";
import { leadsDeleteCommand } from "./delete.js";
const consoleMock = vi.mocked(consola);
describe("leads delete command", () => {
beforeEach(() => {
vi.clearAllMocks();
dbMock.lead.findUnique.mockResolvedValue(null);
dbMock.lead.delete.mockResolvedValue({ id: "lead_1" });
});
it("hard-deletes an existing lead and echoes its email for the audit trail", async () => {
dbMock.lead.findUnique.mockResolvedValueOnce({ email: "ada@example.com" });
await leadsDeleteCommand.run?.({ args: { id: "lead_1" } } as never);
expect(dbMock.lead.findUnique).toHaveBeenCalledWith({
where: { id: "lead_1" },
select: { email: true },
});
expect(dbMock.lead.delete).toHaveBeenCalledWith({ where: { id: "lead_1" } });
expect(consoleMock.success).toHaveBeenCalledWith("Deleted lead lead_1 (ada@example.com).");
});
it("warns and skips the delete when the lead does not exist", async () => {
await leadsDeleteCommand.run?.({ args: { id: "ghost" } } as never);
expect(consoleMock.warn).toHaveBeenCalledWith("Lead ghost not found.");
expect(dbMock.lead.delete).not.toHaveBeenCalled();
expect(consoleMock.success).not.toHaveBeenCalled();
});
});
@@ -1,25 +0,0 @@
/**
* `leads delete --id <leadId>` — hard-delete a single lead and its events.
* Use for DSGVO right-to-be-forgotten requests.
*/
import { defineCommand } from "citty";
import consola from "consola";
export const leadsDeleteCommand = defineCommand({
meta: { name: "delete", description: "Delete a lead (DSGVO right-to-be-forgotten)." },
args: {
id: { type: "string", required: true, description: "Lead id." },
},
async run({ args }) {
const { getDbClient } = await import("@hivegrid/db/client.server");
const prisma = getDbClient();
const id = String(args.id);
const existing = await prisma.lead.findUnique({ where: { id }, select: { email: true } });
if (!existing) {
consola.warn(`Lead ${id} not found.`);
return;
}
await prisma.lead.delete({ where: { id } });
consola.success(`Deleted lead ${id} (${existing.email}).`);
},
});
@@ -4,6 +4,7 @@
import { defineCommand } from "citty";
import consola from "consola";
import { writeFile } from "node:fs/promises";
import { neutralizeSpreadsheetFormula } from "@hivegrid/foundation/spreadsheet-safety";
const COLUMNS = [
"id",
@@ -30,11 +31,11 @@ const COLUMNS = [
function csvEscape(v: unknown): string {
if (v === null || v === undefined) return "";
const s = String(v);
if (s.includes(",") || s.includes('"') || s.includes("\n")) {
return `"${s.replace(/"/g, '""')}"`;
const safeValue = neutralizeSpreadsheetFormula(String(v));
if (safeValue.includes(",") || safeValue.includes('"') || safeValue.includes("\n") || safeValue.includes("\r")) {
return `"${safeValue.replace(/"/g, '""')}"`;
}
return s;
return safeValue;
}
export const leadsExportCommand = defineCommand({
@@ -1,16 +1,14 @@
import { defineCommand } from "citty";
import { leadsListCommand } from "./list.js";
import { leadsExportCommand } from "./export.js";
import { leadsDeleteCommand } from "./delete.js";
export const leadsCommand = defineCommand({
meta: {
name: "leads",
description: "Marketing-funnel lead inbox commands (list, export, delete).",
description: "Read-only legacy marketing lead commands for rollback and export.",
},
subCommands: {
list: leadsListCommand,
export: leadsExportCommand,
delete: leadsDeleteCommand,
},
});
@@ -137,42 +137,17 @@ describe("marketing attribution command", () => {
describe("marketing funnel command", () => {
beforeEach(() => {
vi.useFakeTimers();
vi.setSystemTime(now);
vi.clearAllMocks();
dbMock.lead.count.mockResolvedValue(0);
dbMock.tenantAcquisition.count.mockResolvedValue(0);
dbMock.lead.groupBy.mockResolvedValue([]);
});
afterEach(() => {
vi.useRealTimers();
});
it("computes the conversion rate and renders the full stage ladder", async () => {
dbMock.lead.count.mockResolvedValueOnce(200);
dbMock.tenantAcquisition.count.mockResolvedValueOnce(50);
dbMock.lead.groupBy.mockResolvedValueOnce([
{ status: "new", _count: { _all: 120 } },
{ status: "customer", _count: { _all: 50 } },
]);
it("keeps the compatibility command write-free and points operators to the native inbox", async () => {
await marketingFunnelCommand.run?.({ args: {} } as never);
expect(consoleMock.log).toHaveBeenCalledWith("Leads captured: 200");
expect(consoleMock.log).toHaveBeenCalledWith("Conversions: 50");
expect(consoleMock.log).toHaveBeenCalledWith("Conversion rate: 25.00%");
expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("new"));
expect(consoleMock.log).toHaveBeenCalledWith(expect.stringContaining("120"));
// Stages without data render a zero count rather than being skipped.
expect(consoleMock.log).toHaveBeenCalledWith(expect.stringMatching(/churned\s+0/u));
});
it("guards division by zero when no leads were captured", async () => {
await marketingFunnelCommand.run?.({ args: { days: "7" } } as never);
const since = new Date(now.getTime() - 7 * 24 * 60 * 60 * 1000);
expect(dbMock.lead.count).toHaveBeenCalledWith({ where: { createdAt: { gte: since } } });
expect(consoleMock.log).toHaveBeenCalledWith("Conversion rate: 0.00%");
expect(consoleMock.info).toHaveBeenCalledWith(
"The legacy marketing funnel is retired. Use the platform admin inbox at /leads.",
);
expect(dbMock.lead.count).not.toHaveBeenCalled();
expect(dbMock.lead.groupBy).not.toHaveBeenCalled();
expect(dbMock.tenantAcquisition.count).not.toHaveBeenCalled();
});
});
@@ -1,42 +1,16 @@
/**
* `marketing funnel [--days N]` — print conversion-rate snapshot.
* Compatibility command for the retired legacy platform-lead funnel.
*
* Mirrors the /admin/marketing-funnels report for shell-based ops.
* Keep the command name during the drain window so existing operator scripts
* fail visibly without reading the legacy Lead table. The native platform-lead
* workflow is available in the admin application at /leads.
*/
import { defineCommand } from "citty";
import consola from "consola";
export const marketingFunnelCommand = defineCommand({
meta: { name: "funnel", description: "Print marketing-funnel conversion snapshot." },
args: {
days: { type: "string", required: false, description: "Period in days (default 30)." },
},
async run({ args }) {
const { getReadDbClient } = await import("@hivegrid/db/client.server");
const prisma = getReadDbClient();
const days = Math.min(365, Math.max(1, Number(args.days ?? "30")));
const since = new Date(Date.now() - days * 24 * 60 * 60 * 1000);
const [leadCount, conversionCount, statusGroups] = await Promise.all([
prisma.lead.count({ where: { createdAt: { gte: since } } }),
prisma.tenantAcquisition.count({ where: { convertedAt: { gte: since } } }),
prisma.lead.groupBy({
by: ["status"],
_count: { _all: true },
where: { createdAt: { gte: since } },
}),
]);
const rate = leadCount > 0 ? conversionCount / leadCount : 0;
consola.log(`Period: last ${days} days (since ${since.toISOString().slice(0, 10)})`);
consola.log(`Leads captured: ${leadCount}`);
consola.log(`Conversions: ${conversionCount}`);
consola.log(`Conversion rate: ${(rate * 100).toFixed(2)}%`);
consola.log("");
consola.log("Stage distribution:");
const order = ["new", "contacted", "qualified", "trial", "customer", "churned", "disqualified"];
const counts = new Map<string, number>(statusGroups.map((g) => [String(g.status), g._count._all]));
for (const s of order) {
consola.log(` ${s.padEnd(15)} ${counts.get(s) ?? 0}`);
}
meta: { name: "funnel", description: "Show where the native platform-lead inbox is available." },
async run() {
consola.info("The legacy marketing funnel is retired. Use the platform admin inbox at /leads.");
},
});
@@ -5,7 +5,7 @@ import { marketingAttributionCommand } from "./attribution.js";
export const marketingCommand = defineCommand({
meta: {
name: "marketing",
description: "Marketing-funnel operator commands (funnel snapshot, attribution reports).",
description: "Marketing operator commands (native-inbox pointer and attribution reports).",
},
subCommands: {
funnel: marketingFunnelCommand,
@@ -12,15 +12,17 @@ import { defineCommand } from "citty";
import { opsDoctorCommand } from "./doctor.js";
import { opsImpersonateCommand } from "./impersonate.js";
import { opsMigrateTenantCommand } from "./migrate-tenant.js";
import { productAcquisitionRecoveryCommand } from "./product-acquisition-recovery.js";
export const opsCommand = defineCommand({
meta: {
name: "ops",
description: "Operator commands: doctor (health), migrate-tenant, impersonate (audit-logged).",
description: "Operator commands: doctor, migrate-tenant, impersonate, product-acquisition recovery.",
},
subCommands: {
doctor: opsDoctorCommand,
"migrate-tenant": opsMigrateTenantCommand,
impersonate: opsImpersonateCommand,
"product-acquisition-recovery": productAcquisitionRecoveryCommand,
},
});
@@ -0,0 +1,290 @@
import { describe, expect, it, vi } from "vitest";
import {
PRODUCT_ACQUISITION_RECOVERY_CLEANUP,
PRODUCT_ACQUISITION_RECOVERY_RELEASED,
runProductAcquisitionRecovery,
type ProductAcquisitionRecoveryClient,
type ProductAcquisitionRecoveryDependencies,
} from "./product-acquisition-recovery.js";
const NOW = new Date("2026-08-10T12:00:00.000Z");
function acquisition(overrides: Record<string, unknown> = {}) {
return {
id: "acquisition_1",
tenantId: "tenant_1",
subscriptionProductId: "product_1",
subscriptionPriceId: "price_1",
productKind: "recurring_add_on",
scopeKey: "portal:add-on",
status: "provider_pending",
version: 7,
providerAttempt: 2,
providerPaymentId: null,
providerStartedAt: new Date("2026-07-01T00:00:00.000Z"),
reservationExpiresAt: new Date("2026-07-19T00:00:00.000Z"),
failureCode: "reconciler.provider_payment_missing",
invoiceExternalId: "invoice_1",
lagoSubscriptionId: "lago_subscription_1",
...overrides,
};
}
function harness(overrides: {
row?: ReturnType<typeof acquisition>;
payment?: { providerPaymentId: string } | null;
payments?: Array<{ providerPaymentId: string } | null>;
cleanupFailure?: Error;
firstUpdateCount?: number;
} = {}) {
let row = overrides.row ?? acquisition();
const updateHistory: Array<Record<string, unknown>> = [];
let updateCalls = 0;
const updateMany = vi.fn(async ({ where, data }: { where: Record<string, unknown>; data: Record<string, unknown> }) => {
updateCalls += 1;
if (updateCalls === 1 && overrides.firstUpdateCount === 0) return { count: 0 };
if (
where.id !== row.id ||
where.tenantId !== row.tenantId ||
(where.status !== undefined && where.status !== row.status) ||
(where.version !== undefined && where.version !== row.version) ||
(where.providerAttempt !== undefined && where.providerAttempt !== row.providerAttempt) ||
(where.providerPaymentId !== undefined && where.providerPaymentId !== row.providerPaymentId) ||
(where.failureCode !== undefined && where.failureCode !== row.failureCode)
) {
return { count: 0 };
}
updateHistory.push(data);
const versionData = data.version as { increment?: number } | undefined;
row = {
...row,
...data,
version: row.version + (versionData?.increment ?? 0),
} as typeof row;
return { count: 1 };
});
const transaction = {
tenantProductAcquisition: {
findFirst: vi.fn(async () => row),
updateMany,
},
};
const client = {
...transaction,
tenantSubscription: {
findUnique: vi.fn(async () => ({ mollieCustomerId: "customer_1" })),
},
$transaction: vi.fn(async (operation: (tx: typeof transaction) => Promise<unknown>) => operation(transaction)),
} as unknown as ProductAcquisitionRecoveryClient;
const output = { log: vi.fn(), warn: vi.fn(), error: vi.fn(), json: vi.fn() };
const audit = vi.fn(async () => undefined);
const acquireLocks = vi.fn(async () => undefined);
const terminateSubscription = overrides.cleanupFailure
? vi.fn(async () => { throw overrides.cleanupFailure; })
: vi.fn(async () => null);
const updateInvoicePaymentStatus = vi.fn(async () => {
if (overrides.cleanupFailure) throw overrides.cleanupFailure;
return {} as never;
});
const payments = [...(overrides.payments ?? [])];
const deps: ProductAcquisitionRecoveryDependencies = {
client,
mollie: {
findCustomerPaymentByExternalIdExhaustive: vi.fn(async () => payments.shift() ?? overrides.payment ?? null) as never,
},
lago: { terminateSubscription, updateInvoicePaymentStatus },
output,
acquireLocks,
audit,
};
return {
deps,
output,
audit,
acquireLocks,
terminateSubscription,
updateInvoicePaymentStatus,
updateHistory,
get row() { return row; },
};
}
function input(overrides: Record<string, unknown> = {}) {
return {
tenantId: "tenant_1",
acquisitionId: "acquisition_1",
actorUserId: "operator_1",
now: NOW,
...overrides,
};
}
describe("ambiguous product-acquisition operator recovery", () => {
it("proves provider absence without mutating or cleaning up by default", async () => {
const state = harness();
await expect(runProductAcquisitionRecovery(input(), state.deps)).resolves.toMatchObject({
exitCode: 0,
status: "absence_verified",
attemptReference: "acquisition_1:attempt:2",
});
expect(state.deps.mollie.findCustomerPaymentByExternalIdExhaustive).toHaveBeenCalledWith(
"customer_1",
"acquisition_1:attempt:2",
);
expect(state.updateHistory).toEqual([]);
expect(state.terminateSubscription).not.toHaveBeenCalled();
});
it("blocks the ledger, cleans the exact Lago target, audits, and only then releases a retry", async () => {
const state = harness();
await expect(
runProductAcquisitionRecovery(
input({
apply: true,
confirmAttempt: "acquisition_1:attempt:2",
reason: "Mollie operator search confirmed that no payment exists.",
}),
state.deps,
),
).resolves.toMatchObject({ exitCode: 0, status: "released_for_retry" });
expect(state.updateHistory.map((entry) => entry.failureCode)).toEqual([
PRODUCT_ACQUISITION_RECOVERY_CLEANUP,
PRODUCT_ACQUISITION_RECOVERY_RELEASED,
]);
expect(state.terminateSubscription).toHaveBeenCalledWith("lago_subscription_1");
expect(state.audit).toHaveBeenNthCalledWith(1, expect.anything(), expect.objectContaining({ action: "started" }));
expect(state.audit).toHaveBeenNthCalledWith(2, expect.anything(), expect.objectContaining({ action: "released" }));
expect(state.row).toMatchObject({ status: "failed", failureCode: PRODUCT_ACQUISITION_RECOVERY_RELEASED, version: 9 });
});
it("marks the exact one-time Lago invoice failed before releasing its retry", async () => {
const state = harness({
row: acquisition({ productKind: "one_time_setup", lagoSubscriptionId: null }),
});
await expect(
runProductAcquisitionRecovery(
input({
apply: true,
confirmAttempt: "acquisition_1:attempt:2",
reason: "Mollie operator search confirmed that no payment exists.",
}),
state.deps,
),
).resolves.toMatchObject({ status: "released_for_retry" });
expect(state.updateInvoicePaymentStatus).toHaveBeenCalledWith("invoice_1", "failed");
expect(state.terminateSubscription).not.toHaveBeenCalled();
});
it("never releases or cleans up when Mollie still has the exact attempt", async () => {
const state = harness({ payment: { providerPaymentId: "tr_existing" } });
await expect(
runProductAcquisitionRecovery(
input({ apply: true, confirmAttempt: "acquisition_1:attempt:2", reason: "Investigating an ambiguous provider attempt." }),
state.deps,
),
).resolves.toMatchObject({ exitCode: 1, status: "provider_payment_found" });
expect(state.updateHistory).toEqual([]);
expect(state.terminateSubscription).not.toHaveBeenCalled();
});
it("keeps the retry block when Mollie exposes the attempt after the claim CAS", async () => {
const state = harness({ payments: [null, { providerPaymentId: "tr_late_visible" }] });
await expect(
runProductAcquisitionRecovery(
input({
apply: true,
confirmAttempt: "acquisition_1:attempt:2",
reason: "Mollie operator search initially found no provider payment.",
}),
state.deps,
),
).resolves.toMatchObject({ exitCode: 1, status: "provider_payment_found" });
expect(state.row).toMatchObject({ status: "failed", failureCode: PRODUCT_ACQUISITION_RECOVERY_CLEANUP });
expect(state.terminateSubscription).not.toHaveBeenCalled();
expect(state.updateHistory).toHaveLength(1);
});
it("keeps automatic reconciliation in control until the immutable window has elapsed", async () => {
const state = harness({
row: acquisition({
providerStartedAt: new Date("2026-08-01T00:00:00.000Z"),
reservationExpiresAt: new Date("2026-08-19T00:00:00.000Z"),
}),
});
await expect(runProductAcquisitionRecovery(input(), state.deps)).resolves.toMatchObject({
exitCode: 1,
status: "refused",
message: expect.stringContaining("window is still open"),
});
expect(state.deps.mollie.findCustomerPaymentByExternalIdExhaustive).not.toHaveBeenCalled();
});
it("leaves a durable retry block when Lago cleanup fails", async () => {
const failure = new Error("Lago unavailable");
const state = harness({ cleanupFailure: failure });
await expect(
runProductAcquisitionRecovery(
input({
apply: true,
confirmAttempt: "acquisition_1:attempt:2",
reason: "Mollie operator search confirmed that no payment exists.",
}),
state.deps,
),
).rejects.toBe(failure);
expect(state.row).toMatchObject({ status: "failed", failureCode: PRODUCT_ACQUISITION_RECOVERY_CLEANUP });
expect(state.updateHistory).toHaveLength(1);
expect(state.audit).toHaveBeenCalledOnce();
expect(state.audit).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ action: "started" }));
});
it("resumes an interrupted cleanup idempotently and releases only after cleanup succeeds", async () => {
const state = harness({
row: acquisition({
status: "failed",
failureCode: PRODUCT_ACQUISITION_RECOVERY_CLEANUP,
reservationExpiresAt: NOW,
}),
});
await expect(
runProductAcquisitionRecovery(
input({
apply: true,
confirmAttempt: "acquisition_1:attempt:2",
reason: "Resuming the exact interrupted provider cleanup safely.",
}),
state.deps,
),
).resolves.toMatchObject({ status: "released_for_retry" });
expect(state.updateHistory.map((entry) => entry.failureCode)).toEqual([PRODUCT_ACQUISITION_RECOVERY_RELEASED]);
expect(state.audit).toHaveBeenCalledOnce();
expect(state.audit).toHaveBeenCalledWith(expect.anything(), expect.objectContaining({ action: "released" }));
});
it("does not call Lago when the initial claim CAS races", async () => {
const state = harness({ firstUpdateCount: 0 });
await expect(
runProductAcquisitionRecovery(
input({
apply: true,
confirmAttempt: "acquisition_1:attempt:2",
reason: "Mollie operator search confirmed that no payment exists.",
}),
state.deps,
),
).resolves.toMatchObject({ exitCode: 1, status: "raced" });
expect(state.terminateSubscription).not.toHaveBeenCalled();
expect(state.audit).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,496 @@
import { defineCommand } from "citty";
import consola from "consola";
import {
createLagoBillingGateway,
createMolliePaymentGateway,
MAX_MOLLIE_PAYMENT_LIFETIME_MS,
MOLLIE_RECONCILIATION_GRACE_MS,
type BillingGateway,
type ExhaustiveCustomerPaymentGateway,
} from "@hivegrid/billing";
import { loadApiConfig } from "@hivegrid/config";
import { publishAuditEventViaOutbox } from "@hivegrid/db/audit-events.server";
import { acquireProductAcquisitionPaymentLock } from "@hivegrid/db/billing-sync.server";
import { getDbClient } from "@hivegrid/db/client.server";
import { acquirePortalDomainBillingActivationLocks, portalDomainClaimIdFromBillingScope } from "@hivegrid/db/portal-domain-billing-fence.server";
import { resolveOpsEnv } from "./_env.js";
export const PRODUCT_ACQUISITION_RECOVERY_CLEANUP = "cleanup.operator_provider_non_creation_confirmed" as const;
export const PRODUCT_ACQUISITION_RECOVERY_RELEASED = "operator.provider_non_creation_confirmed" as const;
type RecoveryAcquisition = {
readonly id: string;
readonly tenantId: string;
readonly subscriptionProductId: string;
readonly subscriptionPriceId: string | null;
readonly productKind: string;
readonly scopeKey: string;
readonly status: string;
readonly version: number;
readonly providerAttempt: number;
readonly providerPaymentId: string | null;
readonly providerStartedAt: Date | null;
readonly reservationExpiresAt: Date | null;
readonly failureCode: string | null;
readonly invoiceExternalId: string | null;
readonly lagoSubscriptionId: string | null;
};
type RecoveryTransaction = {
tenantProductAcquisition: {
findFirst(args: { where: { id: string; tenantId: string } }): Promise<RecoveryAcquisition | null>;
updateMany(args: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<{ count: number }>;
};
};
export type ProductAcquisitionRecoveryClient = RecoveryTransaction & {
tenantSubscription: {
findUnique(args: { where: { tenantId: string }; select: { mollieCustomerId: true } }): Promise<{ mollieCustomerId: string | null } | null>;
};
$transaction<T>(operation: (transaction: RecoveryTransaction) => Promise<T>): Promise<T>;
};
export type ProductAcquisitionRecoveryOutput = {
log(message: string): void;
warn(message: string): void;
error(message: string): void;
json(payload: unknown): void;
};
export type ProductAcquisitionRecoveryDependencies = {
readonly client: ProductAcquisitionRecoveryClient;
readonly mollie: Pick<ExhaustiveCustomerPaymentGateway, "findCustomerPaymentByExternalIdExhaustive">;
readonly lago: Pick<BillingGateway, "terminateSubscription" | "updateInvoicePaymentStatus">;
readonly output: ProductAcquisitionRecoveryOutput;
readonly acquireLocks?: (transaction: RecoveryTransaction, acquisition: RecoveryAcquisition) => Promise<void>;
readonly audit?: (
transaction: RecoveryTransaction,
input: {
readonly action: "started" | "released";
readonly actorUserId: string;
readonly acquisition: RecoveryAcquisition;
readonly reason: string;
readonly observedAt: Date;
}
) => Promise<void>;
};
export type ProductAcquisitionRecoveryResult = {
readonly exitCode: 0 | 1;
readonly status: "absence_verified" | "released_for_retry" | "provider_payment_found" | "not_found" | "refused" | "raced";
readonly acquisitionId: string;
readonly attemptReference?: string;
readonly observedAt?: string;
readonly message?: string;
};
export async function runProductAcquisitionRecovery(
input: {
readonly tenantId: string;
readonly acquisitionId: string;
readonly actorUserId: string;
readonly apply?: boolean;
readonly confirmAttempt?: string | null;
readonly reason?: string | null;
readonly json?: boolean;
readonly now?: Date;
},
dependencies: ProductAcquisitionRecoveryDependencies
): Promise<ProductAcquisitionRecoveryResult> {
const tenantId = requireIdentifier(input.tenantId, "--tenant");
const acquisitionId = requireIdentifier(input.acquisitionId, "--acquisition-id");
const actorUserId = requireIdentifier(input.actorUserId, "HIVEGRID_CLI_OPERATOR_USER_ID");
const observedAt = input.now ?? new Date();
const acquisition = await dependencies.client.tenantProductAcquisition.findFirst({
where: { id: acquisitionId, tenantId },
});
if (!acquisition) {
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "not_found",
acquisitionId,
message: "Product acquisition was not found in the bound tenant.",
});
}
const refusal = validateRecoveryCandidate(acquisition, observedAt);
if (refusal) {
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "refused",
acquisitionId,
message: refusal,
});
}
const attemptReference = providerAttemptReference(acquisition);
const subscription = await dependencies.client.tenantSubscription.findUnique({
where: { tenantId },
select: { mollieCustomerId: true },
});
const mollieCustomerId = subscription?.mollieCustomerId?.trim();
if (!mollieCustomerId) {
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "refused",
acquisitionId,
attemptReference,
message: "The tenant has no Mollie customer id; provider non-creation cannot be proven.",
});
}
const providerPayment = await dependencies.mollie.findCustomerPaymentByExternalIdExhaustive(mollieCustomerId, attemptReference);
if (providerPayment) {
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "provider_payment_found",
acquisitionId,
attemptReference,
observedAt: observedAt.toISOString(),
message: "Mollie still has the exact provider attempt. Do not release or retry it; let reconciliation finish or investigate the payment.",
});
}
if (!input.apply) {
return emitResult(dependencies.output, input.json, {
exitCode: 0,
status: "absence_verified",
acquisitionId,
attemptReference,
observedAt: observedAt.toISOString(),
message: "The exhaustive live Mollie lookup found no payment. Re-run with --apply and the exact --confirm-attempt value to release a new attempt.",
});
}
if ((input.confirmAttempt ?? "").trim() !== attemptReference) {
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "refused",
acquisitionId,
attemptReference,
message: "--confirm-attempt must exactly match the current provider attempt reference.",
});
}
const reason = requireReason(input.reason);
const acquireLocks = dependencies.acquireLocks ?? acquireRecoveryLocks;
const audit = dependencies.audit ?? publishRecoveryAudit;
let cleanupState: RecoveryAcquisition;
try {
cleanupState = await dependencies.client.$transaction(async (transaction) => {
await acquireLocks(transaction, acquisition);
const fresh = await transaction.tenantProductAcquisition.findFirst({ where: { id: acquisitionId, tenantId } });
if (!fresh || validateRecoveryCandidate(fresh, observedAt) || providerAttemptReference(fresh) !== attemptReference) {
throw new RecoveryRaceError();
}
if (fresh.status === "failed" && fresh.failureCode === PRODUCT_ACQUISITION_RECOVERY_CLEANUP) {
return fresh;
}
const updated = await transaction.tenantProductAcquisition.updateMany({
where: {
id: fresh.id,
tenantId: fresh.tenantId,
status: "provider_pending",
version: fresh.version,
providerAttempt: fresh.providerAttempt,
providerPaymentId: null,
failureCode: fresh.failureCode,
},
data: {
status: "failed",
failedAt: observedAt,
checkoutUrl: null,
failureCode: PRODUCT_ACQUISITION_RECOVERY_CLEANUP,
reservationExpiresAt: observedAt,
version: { increment: 1 },
},
});
if (updated.count !== 1) throw new RecoveryRaceError();
const blocked = { ...fresh, status: "failed", failureCode: PRODUCT_ACQUISITION_RECOVERY_CLEANUP, version: fresh.version + 1 };
await audit(transaction, { action: "started", actorUserId, acquisition: blocked, reason, observedAt });
return blocked;
});
} catch (error) {
if (!(error instanceof RecoveryRaceError)) throw error;
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "raced",
acquisitionId,
attemptReference,
message: "The acquisition changed while recovery was being claimed. Inspect it again before any retry.",
});
}
// Close the remaining provider/DB race after the durable retry block is in
// place. If Mollie exposes the attempt between the first proof and our CAS,
// keep cleanup.* intact and do not touch Lago or release a new charge.
const postClaimProviderPayment = await dependencies.mollie.findCustomerPaymentByExternalIdExhaustive(mollieCustomerId, attemptReference);
if (postClaimProviderPayment) {
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "provider_payment_found",
acquisitionId,
attemptReference,
observedAt: observedAt.toISOString(),
message: "Mollie exposed the exact attempt after the retry block was claimed. The cleanup state remains locked; do not retry or clean up Lago.",
});
}
await cleanUpLagoAttempt(dependencies.lago, cleanupState);
try {
await dependencies.client.$transaction(async (transaction) => {
await acquireLocks(transaction, cleanupState);
const fresh = await transaction.tenantProductAcquisition.findFirst({ where: { id: acquisitionId, tenantId } });
if (
!fresh ||
fresh.status !== "failed" ||
fresh.failureCode !== PRODUCT_ACQUISITION_RECOVERY_CLEANUP ||
fresh.providerPaymentId !== null ||
providerAttemptReference(fresh) !== attemptReference
) {
throw new RecoveryRaceError();
}
const updated = await transaction.tenantProductAcquisition.updateMany({
where: {
id: fresh.id,
tenantId: fresh.tenantId,
status: "failed",
version: fresh.version,
providerAttempt: fresh.providerAttempt,
providerPaymentId: null,
failureCode: PRODUCT_ACQUISITION_RECOVERY_CLEANUP,
},
data: {
failureCode: PRODUCT_ACQUISITION_RECOVERY_RELEASED,
version: { increment: 1 },
},
});
if (updated.count !== 1) throw new RecoveryRaceError();
await audit(transaction, {
action: "released",
actorUserId,
acquisition: { ...fresh, failureCode: PRODUCT_ACQUISITION_RECOVERY_RELEASED, version: fresh.version + 1 },
reason,
observedAt,
});
});
} catch (error) {
if (!(error instanceof RecoveryRaceError)) throw error;
return emitResult(dependencies.output, input.json, {
exitCode: 1,
status: "raced",
acquisitionId,
attemptReference,
message: "Lago cleanup completed, but the final release CAS raced. Re-run the command; the cleanup state remains retry-blocking.",
});
}
return emitResult(dependencies.output, input.json, {
exitCode: 0,
status: "released_for_retry",
acquisitionId,
attemptReference,
observedAt: observedAt.toISOString(),
message: "Mollie non-creation was proven and the exact Lago attempt was cleaned up. A user may now start the next idempotent provider attempt.",
});
}
class RecoveryRaceError extends Error {}
function validateRecoveryCandidate(acquisition: RecoveryAcquisition, now: Date): string | null {
const inCleanup = acquisition.status === "failed" && acquisition.failureCode === PRODUCT_ACQUISITION_RECOVERY_CLEANUP;
if (acquisition.status !== "provider_pending" && !inCleanup) {
return "Only an ambiguous provider_pending acquisition or its retry-blocking cleanup state can be recovered.";
}
if (acquisition.providerPaymentId) return "The acquisition already has a provider payment id; retry release is forbidden.";
if (!inCleanup && !isAmbiguousMollieFailure(acquisition.failureCode)) {
return "The acquisition is not marked as an ambiguous Mollie payment attempt.";
}
if (acquisition.productKind !== "recurring_add_on" && acquisition.productKind !== "one_time_setup") {
return "The acquisition kind has no payable Mollie recovery contract.";
}
const startedAt = acquisition.providerStartedAt;
if (!startedAt || !Number.isFinite(startedAt.getTime())) return "The provider attempt has no valid start timestamp.";
const immutableCeiling = new Date(startedAt.getTime() + MAX_MOLLIE_PAYMENT_LIFETIME_MS + MOLLIE_RECONCILIATION_GRACE_MS);
if (immutableCeiling > now || !acquisition.reservationExpiresAt || acquisition.reservationExpiresAt > now) {
return "The immutable provider-recovery window is still open; automatic reconciliation must retain ownership.";
}
if (acquisition.productKind === "recurring_add_on" && !acquisition.lagoSubscriptionId?.trim()) {
return "The exact Lago subscription target is missing; cleanup cannot be proven.";
}
if (acquisition.productKind === "one_time_setup" && !acquisition.invoiceExternalId?.trim()) {
return "The exact Lago invoice target is missing; cleanup cannot be proven.";
}
return null;
}
function isAmbiguousMollieFailure(failureCode: string | null): boolean {
const code = failureCode?.trim() ?? "";
return (
code.startsWith("ambiguous.") ||
code === "provider.payment_recovery_pending" ||
code === "reconciler.provider_payment_missing" ||
code === "reconciler.provider_lookup_failed"
);
}
async function acquireRecoveryLocks(transaction: RecoveryTransaction, acquisition: RecoveryAcquisition): Promise<void> {
await acquirePortalDomainBillingActivationLocks(transaction as never, {
tenantId: acquisition.tenantId,
claimId: portalDomainClaimIdFromBillingScope(acquisition.scopeKey),
});
await acquireProductAcquisitionPaymentLock(transaction as never, {
tenantId: acquisition.tenantId,
acquisitionId: acquisition.id,
});
}
async function publishRecoveryAudit(
transaction: RecoveryTransaction,
input: {
readonly action: "started" | "released";
readonly actorUserId: string;
readonly acquisition: RecoveryAcquisition;
readonly reason: string;
readonly observedAt: Date;
}
): Promise<void> {
await publishAuditEventViaOutbox(transaction as never, {
tenantId: input.acquisition.tenantId,
actorId: input.actorUserId,
actorType: "admin",
action: `billing.product_acquisition.operator_recovery_${input.action}`,
targetType: "TenantProductAcquisition",
targetId: input.acquisition.id,
sourceModule: "billing",
outcome: "success",
dataSensitivity: "internal",
metadata: {
reason: input.reason,
providerAttempt: input.acquisition.providerAttempt,
observedAt: input.observedAt.toISOString(),
},
});
}
async function cleanUpLagoAttempt(
lago: Pick<BillingGateway, "terminateSubscription" | "updateInvoicePaymentStatus">,
acquisition: RecoveryAcquisition
): Promise<void> {
if (acquisition.productKind === "recurring_add_on") {
await lago.terminateSubscription(acquisition.lagoSubscriptionId!);
return;
}
await lago.updateInvoicePaymentStatus(acquisition.invoiceExternalId!, "failed");
}
function providerAttemptReference(acquisition: Pick<RecoveryAcquisition, "id" | "providerAttempt">): string {
const attempt = Number.isSafeInteger(acquisition.providerAttempt) && acquisition.providerAttempt > 0 ? acquisition.providerAttempt : 1;
return attempt === 1 ? acquisition.id : `${acquisition.id}:attempt:${attempt}`;
}
function requireIdentifier(value: string, label: string): string {
const normalized = value.trim();
if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{2,190}$/u.test(normalized)) {
throw new Error(`${label} must be a valid database identifier`);
}
return normalized;
}
function requireReason(value: string | null | undefined): string {
const normalized = value?.trim() ?? "";
if (normalized.length < 10 || normalized.length > 500 || /[\u0000-\u001f\u007f]/u.test(normalized)) {
throw new Error("--reason must contain 10 to 500 printable characters");
}
return normalized;
}
function emitResult(
output: ProductAcquisitionRecoveryOutput,
json: boolean | undefined,
result: ProductAcquisitionRecoveryResult
): ProductAcquisitionRecoveryResult {
if (json) {
output.json({ ok: result.exitCode === 0, ...result });
} else if (result.exitCode === 0) {
output.log(`${result.status}: ${result.message ?? "ok"}${result.attemptReference ? ` Attempt: ${result.attemptReference}` : ""}`);
} else {
output.error(`${result.status}: ${result.message ?? "refused"}`);
}
return result;
}
function commandOutput(json: boolean): ProductAcquisitionRecoveryOutput {
return {
log: (message) => (json ? undefined : consola.success(message)),
warn: (message) => (json ? undefined : consola.warn(message)),
error: (message) => (json ? undefined : consola.error(message)),
json: (payload) => consola.log(JSON.stringify(payload)),
};
}
export const productAcquisitionRecoveryCommand = defineCommand({
meta: {
name: "product-acquisition-recovery",
description: "Prove an ambiguous Mollie attempt absent, clean its exact Lago target, and release one safe retry.",
},
args: {
tenant: { type: "string", required: true, description: "Tenant id bound into the operator RLS context." },
"acquisition-id": { type: "string", required: true, description: "Ambiguous TenantProductAcquisition id." },
apply: { type: "boolean", required: false, default: false, description: "Apply cleanup and release; default is provider-proof only." },
"confirm-attempt": { type: "string", required: false, description: "Exact attempt reference printed by the proof-only run." },
reason: { type: "string", required: false, description: "Audited operator reason (10-500 characters)." },
json: { type: "boolean", required: false, default: false, description: "Emit machine-readable JSON." },
},
async run({ args }) {
const json = Boolean(args.json);
const output = commandOutput(json);
try {
const env = resolveOpsEnv().env;
const config = loadApiConfig(env).config;
if (!config.lago.apiUrl || !config.lago.apiKey || !config.mollie.apiKey) {
throw new Error("LAGO_API_URL, LAGO_API_KEY and MOLLIE_API_KEY are required");
}
const result = await runProductAcquisitionRecovery(
{
tenantId: args.tenant,
acquisitionId: args["acquisition-id"],
actorUserId: env.HIVEGRID_CLI_OPERATOR_USER_ID ?? "",
apply: Boolean(args.apply),
confirmAttempt: args["confirm-attempt"],
reason: args.reason,
json,
},
{
client: getDbClient() as unknown as ProductAcquisitionRecoveryClient,
mollie: createMolliePaymentGateway({
apiKey: config.mollie.apiKey,
profileId: config.mollie.profileId,
timeoutMs: config.mollie.timeoutMs,
}),
lago: createLagoBillingGateway({
apiUrl: config.lago.apiUrl,
apiKey: config.lago.apiKey,
timeoutMs: config.lago.timeoutMs,
}),
output,
}
);
process.exitCode = result.exitCode;
} catch (error) {
const message = safeCommandError(error);
if (json) output.json({ ok: false, status: "exception", message });
else output.error(`product acquisition recovery failed: ${message}`);
process.exitCode = 1;
}
},
});
function safeCommandError(error: unknown): string {
const record = error && typeof error === "object" ? (error as { name?: unknown; code?: unknown; status?: unknown }) : null;
const name = typeof record?.name === "string" && /^[A-Za-z][A-Za-z0-9_.-]{0,79}$/u.test(record.name) ? record.name : "Error";
const code = typeof record?.code === "string" && /^[A-Z][A-Z0-9_]{0,79}$/u.test(record.code) ? record.code : null;
const status = typeof record?.status === "number" && Number.isInteger(record.status) && record.status >= 100 && record.status <= 599 ? record.status : null;
return [name, code, status === null ? null : `HTTP_${status}`].filter(Boolean).join(":");
}
@@ -16,15 +16,13 @@ export type OutboxRequeueStatus = "PENDING" | "PROCESSING" | "DONE" | "FAILED" |
* worked on by the dispatcher (PROCESSING) or that's still waiting in
* the queue (PENDING). Doing so would double-deliver the work.
*/
export const OUTBOX_REQUEUE_REFUSED_STATUSES: ReadonlySet<OutboxRequeueStatus> = new Set(["PENDING", "PROCESSING"]);
export const OUTBOX_REQUEUE_REFUSED_STATUSES: ReadonlySet<OutboxRequeueStatus> = new Set(["PENDING", "PROCESSING", "DONE"]);
/**
* Acceptable statuses for re-queue. DONE is included because the
* operator may want to replay a side-effect (e.g. resend a billing
* notification email that was lost in the receiver). The CLI emits a
* warning for DONE so it's never an accident.
* Acceptable statuses for re-queue. DONE only proves enqueue, not consumer
* completion, so replaying it could overlap an active delivery.
*/
export const OUTBOX_REQUEUE_ALLOWED_STATUSES: ReadonlySet<OutboxRequeueStatus> = new Set(["FAILED", "DONE", "CANCELLED"]);
export const OUTBOX_REQUEUE_ALLOWED_STATUSES: ReadonlySet<OutboxRequeueStatus> = new Set(["FAILED", "CANCELLED"]);
export interface OutboxRequeueEventRow {
id: string;
@@ -32,6 +30,7 @@ export interface OutboxRequeueEventRow {
status: OutboxRequeueStatus;
tenantId: string | null;
retries: number;
deliveryGeneration: number;
createdAt: Date;
}
@@ -41,12 +40,13 @@ export interface OutboxRequeueEventRow {
*/
export interface OutboxRequeueClient {
outboxEvent: {
findUnique(args: { where: { id: string } }): Promise<OutboxRequeueEventRow | null>;
findFirst(args: { where: { id: string; tenantId: string } }): Promise<OutboxRequeueEventRow | null>;
update(args: {
where: { id: string };
data: {
status: OutboxRequeueStatus;
retries: number;
deliveryGeneration: { increment: number };
lastError: string | null;
scheduledAt: Date;
lockedUntil: null;
@@ -56,18 +56,25 @@ export interface OutboxRequeueClient {
findMany(args: {
where: {
eventType: string;
tenantId: string;
createdAt: { gte: Date };
status: { in: OutboxRequeueStatus[] };
};
select: { id: true; eventType: true; status: true; tenantId: true; retries: true; createdAt: true };
select: { id: true; eventType: true; status: true; tenantId: true; retries: true; deliveryGeneration: true; createdAt: true };
orderBy: { createdAt: "asc" };
take: number;
}): Promise<OutboxRequeueEventRow[]>;
updateMany(args: {
where: { id: { in: string[] } };
where: {
id: { in: string[] };
tenantId: string;
status?: { in: OutboxRequeueStatus[] };
deliveryGeneration?: number;
};
data: {
status: OutboxRequeueStatus;
retries: number;
deliveryGeneration: { increment: number };
lastError: string | null;
scheduledAt: Date;
lockedUntil: null;
@@ -85,6 +92,7 @@ export interface OutboxRequeueOutput {
}
export interface OutboxRequeueByIdArgs {
tenantId: string;
eventId: string;
json?: boolean;
now?: Date;
@@ -103,6 +111,14 @@ export function normalizeStatus(value: unknown): OutboxRequeueStatus {
throw new Error(`Unrecognised OutboxStatus value ${JSON.stringify(value)}`);
}
export function normalizeTenantId(value: unknown): string {
const normalized = typeof value === "string" ? value.trim() : "";
if (normalized.length === 0 || normalized.length > 191 || normalized.includes("\u0000")) {
throw new Error("--tenant must be a non-empty database identifier");
}
return normalized;
}
/**
* Re-queue a single event by id. Refuses to act on events that are
* currently PENDING or PROCESSING — re-queueing them would double-
@@ -113,8 +129,9 @@ export async function runOutboxRequeueById(
args: OutboxRequeueByIdArgs,
deps: { client: OutboxRequeueClient; output: OutboxRequeueOutput }
): Promise<OutboxRequeueByIdOutcome> {
const tenantId = normalizeTenantId(args.tenantId);
const now = args.now ?? new Date();
const existing = await deps.client.outboxEvent.findUnique({ where: { id: args.eventId } });
const existing = await deps.client.outboxEvent.findFirst({ where: { id: args.eventId, tenantId } });
if (!existing) {
if (args.json) {
deps.output.json({ ok: false, reason: "not_found", eventId: args.eventId });
@@ -143,21 +160,32 @@ export async function runOutboxRequeueById(
return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message };
}
if (status === "DONE") {
deps.output.warn(`outbox event ${args.eventId} is DONE; re-queueing will replay the side effect`);
}
await deps.client.outboxEvent.update({
where: { id: args.eventId },
const requeued = await deps.client.outboxEvent.updateMany({
where: {
id: { in: [args.eventId] },
tenantId,
status: { in: [status] },
deliveryGeneration: existing.deliveryGeneration,
},
data: {
status: "PENDING",
retries: 0,
deliveryGeneration: { increment: 1 },
lastError: null,
scheduledAt: now,
lockedUntil: null,
processedAt: null,
},
});
if (requeued.count !== 1) {
const message = `outbox event ${args.eventId} changed while it was being re-queued; retry from fresh state`;
if (args.json) {
deps.output.json({ ok: false, reason: "refused", eventId: args.eventId, status });
} else {
deps.output.error(message);
}
return { exitCode: 1, status: "refused", eventId: args.eventId, previousStatus: status, message };
}
if (args.json) {
deps.output.json({ ok: true, eventId: args.eventId, previousStatus: status });
@@ -168,13 +196,14 @@ export async function runOutboxRequeueById(
}
export interface OutboxRequeueBulkArgs {
tenantId: string;
type: string;
since: string;
/** Optional cap to avoid runaway re-queues. Default 10_000. */
limit?: number;
/** `true` ⇒ confirm, perform the writes; `false` ⇒ dry-run summary only. */
apply?: boolean;
/** Include DONE events too. Off by default for safety. */
/** Legacy flag. DONE replay is refused until consumer completion receipts exist. */
includeDone?: boolean;
json?: boolean;
now?: Date;
@@ -197,6 +226,7 @@ export async function runOutboxRequeueBulk(
args: OutboxRequeueBulkArgs,
deps: { client: OutboxRequeueClient; output: OutboxRequeueOutput }
): Promise<OutboxRequeueBulkOutcome> {
const tenantId = normalizeTenantId(args.tenantId);
const limit = Math.max(1, Math.min(args.limit ?? OUTBOX_REQUEUE_BULK_DEFAULT_LIMIT, 100_000));
if (!OUTBOX_EVENT_TYPE_PATTERN.test(args.type)) {
const message = `--type must match <domain>.<entity>.<verb> (got ${JSON.stringify(args.type)})`;
@@ -207,6 +237,12 @@ export async function runOutboxRequeueBulk(
}
return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message };
}
if (args.includeDone) {
const message = "--include-done is unsafe without a consumer completion receipt and is no longer supported";
if (args.json) deps.output.json({ ok: false, reason: "invalid_args", message });
else deps.output.error(message);
return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message };
}
const since = new Date(args.since);
if (Number.isNaN(since.getTime())) {
const message = `--since must be a valid ISO-8601 timestamp (got ${JSON.stringify(args.since)})`;
@@ -218,14 +254,15 @@ export async function runOutboxRequeueBulk(
return { exitCode: 1, status: "invalid_args", matched: 0, applied: 0, eventType: args.type, since: null, message };
}
const statusFilter: OutboxRequeueStatus[] = args.includeDone ? ["FAILED", "DONE", "CANCELLED"] : ["FAILED", "CANCELLED"];
const statusFilter: OutboxRequeueStatus[] = ["FAILED", "CANCELLED"];
const candidates = await deps.client.outboxEvent.findMany({
where: {
eventType: args.type,
tenantId,
createdAt: { gte: since },
status: { in: statusFilter },
},
select: { id: true, eventType: true, status: true, tenantId: true, retries: true, createdAt: true },
select: { id: true, eventType: true, status: true, tenantId: true, retries: true, deliveryGeneration: true, createdAt: true },
orderBy: { createdAt: "asc" },
take: limit,
});
@@ -258,21 +295,31 @@ export async function runOutboxRequeueBulk(
}
const now = args.now ?? new Date();
const result = await deps.client.outboxEvent.updateMany({
where: { id: { in: candidates.map((c) => c.id) } },
data: {
status: "PENDING",
retries: 0,
lastError: null,
scheduledAt: now,
lockedUntil: null,
processedAt: null,
},
});
if (args.json) {
deps.output.json({ ok: true, applied: result.count, matched: candidates.length, eventType: args.type, since: since.toISOString() });
} else {
deps.output.log(`outbox requeue: ${result.count} event(s) re-queued (type=${args.type} since=${since.toISOString()})`);
let applied = 0;
for (const candidate of candidates) {
const result = await deps.client.outboxEvent.updateMany({
where: {
id: { in: [candidate.id] },
tenantId,
status: { in: [candidate.status] },
deliveryGeneration: candidate.deliveryGeneration,
},
data: {
status: "PENDING",
retries: 0,
deliveryGeneration: { increment: 1 },
lastError: null,
scheduledAt: now,
lockedUntil: null,
processedAt: null,
},
});
applied += result.count;
}
return { exitCode: 0, status: "requeued", matched: candidates.length, applied: result.count, eventType: args.type, since };
if (args.json) {
deps.output.json({ ok: true, applied, matched: candidates.length, eventType: args.type, since: since.toISOString() });
} else {
deps.output.log(`outbox requeue: ${applied} event(s) re-queued (type=${args.type} since=${since.toISOString()})`);
}
return { exitCode: 0, status: "requeued", matched: candidates.length, applied, eventType: args.type, since };
}
@@ -8,6 +8,11 @@ const runBulk = vi.fn();
vi.mock("./_lib.js", () => ({
runOutboxRequeueById: (...args: unknown[]) => runById(...args),
runOutboxRequeueBulk: (...args: unknown[]) => runBulk(...args),
normalizeTenantId: (value: unknown) => {
const tenantId = typeof value === "string" ? value.trim() : "";
if (!tenantId) throw new Error("--tenant must be a non-empty database identifier");
return tenantId;
},
}));
vi.mock("@hivegrid/db/client.server", () => ({
getDbClient: () => ({ outboxEvent: {} }),
@@ -59,10 +64,10 @@ describe("outbox requeue command wrapper", () => {
it("delegates single-event mode and adopts the lib outcome exit code", async () => {
runById.mockResolvedValueOnce({ exitCode: 0 });
await outboxRequeueCommand.run?.({ args: { "event-id": "evt-1" } } as never);
await outboxRequeueCommand.run?.({ args: { tenant: "tenant-1", "event-id": "evt-1" } } as never);
expect(runById).toHaveBeenCalledWith(
{ eventId: "evt-1", json: false },
{ tenantId: "tenant-1", eventId: "evt-1", json: false },
expect.objectContaining({ client: expect.anything(), output: expect.anything() }),
);
expect(runBulk).not.toHaveBeenCalled();
@@ -75,6 +80,7 @@ describe("outbox requeue command wrapper", () => {
await outboxRequeueCommand.run?.({
args: {
type: "billing.subscription.ended",
tenant: "tenant-1",
since: "2026-05-01T00:00:00Z",
apply: true,
"include-done": true,
@@ -84,6 +90,7 @@ describe("outbox requeue command wrapper", () => {
expect(runBulk).toHaveBeenCalledWith(
{
tenantId: "tenant-1",
type: "billing.subscription.ended",
since: "2026-05-01T00:00:00Z",
apply: true,
@@ -98,12 +105,12 @@ describe("outbox requeue command wrapper", () => {
it("omits limit from the bulk payload when not parseable", async () => {
await outboxRequeueCommand.run?.({
args: { type: "a.b.c", since: "2026-05-01T00:00:00Z", limit: "not-a-number" },
args: { tenant: "tenant-1", type: "a.b.c", since: "2026-05-01T00:00:00Z", limit: "not-a-number" },
} as never);
const payload = runBulk.mock.calls[0]?.[0] as Record<string, unknown>;
expect(payload).not.toHaveProperty("limit");
expect(payload).toMatchObject({ apply: false, includeDone: false, json: false });
expect(payload).toMatchObject({ tenantId: "tenant-1", apply: false, includeDone: false, json: false });
});
it("routes the lib output sink through consola (text mode)", async () => {
@@ -115,7 +122,7 @@ describe("outbox requeue command wrapper", () => {
return { exitCode: 0 };
});
await outboxRequeueCommand.run?.({ args: { "event-id": "evt-1" } } as never);
await outboxRequeueCommand.run?.({ args: { tenant: "tenant-1", "event-id": "evt-1" } } as never);
expect(consoleMock.success).toHaveBeenCalledWith("done");
expect(consoleMock.warn).toHaveBeenCalledWith("careful");
@@ -131,7 +138,7 @@ describe("outbox requeue command wrapper", () => {
return { exitCode: 0 };
});
await outboxRequeueCommand.run?.({ args: { "event-id": "evt-1", json: true } } as never);
await outboxRequeueCommand.run?.({ args: { tenant: "tenant-1", "event-id": "evt-1", json: true } } as never);
expect(consoleMock.success).not.toHaveBeenCalled();
expect(consoleMock.error).not.toHaveBeenCalled();
@@ -141,7 +148,7 @@ describe("outbox requeue command wrapper", () => {
it("catches lib exceptions and reports a human error in text mode", async () => {
runById.mockRejectedValueOnce(new Error("db down"));
await outboxRequeueCommand.run?.({ args: { "event-id": "evt-1" } } as never);
await outboxRequeueCommand.run?.({ args: { tenant: "tenant-1", "event-id": "evt-1" } } as never);
expect(consoleMock.error).toHaveBeenCalledWith("outbox requeue failed: db down");
expect(process.exitCode).toBe(1);
@@ -151,7 +158,7 @@ describe("outbox requeue command wrapper", () => {
runBulk.mockRejectedValueOnce("boom");
await outboxRequeueCommand.run?.({
args: { type: "a.b.c", since: "2026-05-01T00:00:00Z", json: true },
args: { tenant: "tenant-1", type: "a.b.c", since: "2026-05-01T00:00:00Z", json: true },
} as never);
expect(consoleMock.log).toHaveBeenCalledWith(
@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from "vitest";
import {
normalizeStatus,
normalizeTenantId,
runOutboxRequeueById,
runOutboxRequeueBulk,
type OutboxRequeueClient,
@@ -16,29 +17,58 @@ describe("normalizeStatus", () => {
});
});
describe("normalizeTenantId", () => {
it("trims the tenant identifier shared with the CLI RLS context", () => {
expect(normalizeTenantId(" tenant-1 ")).toBe("tenant-1");
});
it("rejects empty and NUL-containing tenant identifiers", () => {
expect(() => normalizeTenantId(" ")).toThrow(/--tenant/);
expect(() => normalizeTenantId("tenant\u0000other")).toThrow(/--tenant/);
});
});
interface FakeState {
byId: Map<string, OutboxRequeueEventRow>;
updates: Array<{ id: string; data: Record<string, unknown> }>;
updateMany: Array<{ ids: string[]; data: Record<string, unknown> }>;
updateMany: Array<{
ids: string[];
tenantId: string;
status?: OutboxRequeueStatus[];
deliveryGeneration?: number;
data: Record<string, unknown>;
}>;
}
function fakeClient(state: FakeState): OutboxRequeueClient {
return {
outboxEvent: {
async findUnique({ where }) {
return state.byId.get(where.id) ?? null;
async findFirst({ where }) {
const row = state.byId.get(where.id);
return row?.tenantId === where.tenantId ? row : null;
},
async update({ where, data }) {
const row = state.byId.get(where.id);
if (!row) throw new Error(`no row ${where.id}`);
const next: OutboxRequeueEventRow = { ...row, status: data.status, retries: data.retries };
const next: OutboxRequeueEventRow = {
...row,
status: data.status,
retries: data.retries,
deliveryGeneration: row.deliveryGeneration + data.deliveryGeneration.increment,
};
state.byId.set(where.id, next);
state.updates.push({ id: where.id, data: data as unknown as Record<string, unknown> });
return next;
},
async findMany({ where, take }) {
const all = Array.from(state.byId.values())
.filter((r) => r.eventType === where.eventType && r.createdAt >= where.createdAt.gte && where.status.in.includes(r.status))
.filter(
(r) =>
r.tenantId === where.tenantId &&
r.eventType === where.eventType &&
r.createdAt >= where.createdAt.gte &&
where.status.in.includes(r.status)
)
.sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
.slice(0, take);
return all;
@@ -48,11 +78,25 @@ function fakeClient(state: FakeState): OutboxRequeueClient {
for (const id of where.id.in) {
const row = state.byId.get(id);
if (row) {
state.byId.set(id, { ...row, status: data.status, retries: data.retries });
if (row.tenantId !== where.tenantId) continue;
if (where.status && !where.status.in.includes(row.status)) continue;
if (where.deliveryGeneration !== undefined && row.deliveryGeneration !== where.deliveryGeneration) continue;
state.byId.set(id, {
...row,
status: data.status,
retries: data.retries,
deliveryGeneration: row.deliveryGeneration + data.deliveryGeneration.increment,
});
count += 1;
}
}
state.updateMany.push({ ids: where.id.in, data: data as unknown as Record<string, unknown> });
state.updateMany.push({
ids: where.id.in,
tenantId: where.tenantId,
...(where.status ? { status: where.status.in } : {}),
...(where.deliveryGeneration !== undefined ? { deliveryGeneration: where.deliveryGeneration } : {}),
data: data as unknown as Record<string, unknown>,
});
return { count };
},
},
@@ -88,6 +132,7 @@ function row(id: string, overrides: Partial<OutboxRequeueEventRow> = {}): Outbox
status: "FAILED",
tenantId: "tenant-1",
retries: 3,
deliveryGeneration: 0,
createdAt: new Date("2026-05-20T08:00:00Z"),
...overrides,
};
@@ -101,13 +146,24 @@ describe("runOutboxRequeueById", () => {
updateMany: [],
};
const output = makeOutput();
const outcome = await runOutboxRequeueById({ eventId: "evt-1", now: new Date("2026-05-25T00:00:00Z") }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueById(
{ tenantId: " tenant-1 ", eventId: "evt-1", now: new Date("2026-05-25T00:00:00Z") },
{ client: fakeClient(state), output }
);
expect(outcome.exitCode).toBe(0);
expect(outcome.status).toBe("requeued");
expect(state.updates).toHaveLength(1);
const update = state.updates[0]!.data as { status: OutboxRequeueStatus; retries: number; lastError: string | null };
expect(state.updateMany).toHaveLength(1);
const update = state.updateMany[0]!.data as {
status: OutboxRequeueStatus;
retries: number;
deliveryGeneration: { increment: number };
lastError: string | null;
};
expect(update.status).toBe("PENDING");
expect(update.retries).toBe(0);
expect(update.deliveryGeneration).toEqual({ increment: 1 });
expect(state.byId.get("evt-1")?.deliveryGeneration).toBe(1);
expect(state.updateMany[0]).toMatchObject({ tenantId: "tenant-1", status: ["FAILED"], deliveryGeneration: 0 });
expect(update.lastError).toBeNull();
expect(output.logs.some((m) => m.includes("re-queued"))).toBe(true);
});
@@ -119,7 +175,7 @@ describe("runOutboxRequeueById", () => {
updateMany: [],
};
const output = makeOutput();
await runOutboxRequeueById({ eventId: "evt-2", json: true }, { client: fakeClient(state), output });
await runOutboxRequeueById({ tenantId: "tenant-1", eventId: "evt-2", json: true }, { client: fakeClient(state), output });
expect(output.jsons[0]).toEqual({ ok: true, eventId: "evt-2", previousStatus: "FAILED" });
expect(output.logs).toEqual([]);
});
@@ -131,7 +187,7 @@ describe("runOutboxRequeueById", () => {
updateMany: [],
};
const output = makeOutput();
const outcome = await runOutboxRequeueById({ eventId: "evt-3" }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueById({ tenantId: "tenant-1", eventId: "evt-3" }, { client: fakeClient(state), output });
expect(outcome.exitCode).toBe(1);
expect(outcome.status).toBe("refused");
expect(state.updates).toEqual([]);
@@ -145,28 +201,29 @@ describe("runOutboxRequeueById", () => {
updateMany: [],
};
const output = makeOutput();
const outcome = await runOutboxRequeueById({ eventId: "evt-4" }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueById({ tenantId: "tenant-1", eventId: "evt-4" }, { client: fakeClient(state), output });
expect(outcome.exitCode).toBe(1);
expect(state.updates).toEqual([]);
});
it("re-queues DONE events but warns the operator", async () => {
it("refuses DONE events because enqueue does not prove consumer completion", async () => {
const state: FakeState = {
byId: new Map([["evt-5", row("evt-5", { status: "DONE", retries: 0 })]]),
updates: [],
updateMany: [],
};
const output = makeOutput();
const outcome = await runOutboxRequeueById({ eventId: "evt-5" }, { client: fakeClient(state), output });
expect(outcome.exitCode).toBe(0);
expect(state.updates).toHaveLength(1);
expect(output.warns[0]).toMatch(/will replay/);
const outcome = await runOutboxRequeueById({ tenantId: "tenant-1", eventId: "evt-5" }, { client: fakeClient(state), output });
expect(outcome.exitCode).toBe(1);
expect(outcome.status).toBe("refused");
expect(state.updateMany).toHaveLength(0);
expect(output.errors[0]).toMatch(/double-deliver/);
});
it("returns not_found when the event does not exist", async () => {
const state: FakeState = { byId: new Map(), updates: [], updateMany: [] };
const output = makeOutput();
const outcome = await runOutboxRequeueById({ eventId: "ghost" }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueById({ tenantId: "tenant-1", eventId: "ghost" }, { client: fakeClient(state), output });
expect(outcome.exitCode).toBe(1);
expect(outcome.status).toBe("not_found");
expect(output.errors[0]).toMatch(/not found/);
@@ -175,11 +232,29 @@ describe("runOutboxRequeueById", () => {
it("emits JSON for not_found lookups when --json is set", async () => {
const state: FakeState = { byId: new Map(), updates: [], updateMany: [] };
const output = makeOutput();
const outcome = await runOutboxRequeueById({ eventId: "ghost", json: true }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueById({ tenantId: "tenant-1", eventId: "ghost", json: true }, { client: fakeClient(state), output });
expect(outcome.status).toBe("not_found");
expect(output.jsons[0]).toEqual({ ok: false, reason: "not_found", eventId: "ghost" });
expect(output.errors).toEqual([]);
});
it("does not reveal or update an event owned by another tenant", async () => {
const state: FakeState = {
byId: new Map([["evt-cross-tenant", row("evt-cross-tenant", { tenantId: "tenant-2" })]]),
updates: [],
updateMany: [],
};
const output = makeOutput();
const outcome = await runOutboxRequeueById(
{ tenantId: "tenant-1", eventId: "evt-cross-tenant" },
{ client: fakeClient(state), output }
);
expect(outcome.status).toBe("not_found");
expect(state.updateMany).toEqual([]);
expect(state.byId.get("evt-cross-tenant")?.status).toBe("FAILED");
});
});
describe("runOutboxRequeueBulk", () => {
@@ -192,6 +267,7 @@ describe("runOutboxRequeueBulk", () => {
["d", row("d", { status: "PENDING", createdAt: new Date("2026-05-22T00:00:00Z") })],
["e", row("e", { status: "FAILED", createdAt: new Date("2026-05-19T00:00:00Z") })],
["f", row("f", { eventType: "billing.subscription.cancelled", status: "FAILED", createdAt: new Date("2026-05-22T00:00:00Z") })],
["g", row("g", { tenantId: "tenant-2", status: "FAILED", createdAt: new Date("2026-05-22T00:00:00Z") })],
]),
updates: [],
updateMany: [],
@@ -201,7 +277,10 @@ describe("runOutboxRequeueBulk", () => {
it("previews matched count without writing when --apply is omitted", async () => {
const state = bulkState();
const output = makeOutput();
const outcome = await runOutboxRequeueBulk({ type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z" }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueBulk(
{ tenantId: " tenant-1 ", type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z" },
{ client: fakeClient(state), output }
);
expect(outcome.exitCode).toBe(0);
expect(outcome.status).toBe("previewed");
expect(outcome.matched).toBe(2);
@@ -214,35 +293,47 @@ describe("runOutboxRequeueBulk", () => {
const state = bulkState();
const output = makeOutput();
const outcome = await runOutboxRequeueBulk(
{ type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, now: new Date("2026-05-25T00:00:00Z") },
{ tenantId: "tenant-1", type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, now: new Date("2026-05-25T00:00:00Z") },
{ client: fakeClient(state), output }
);
expect(outcome.exitCode).toBe(0);
expect(outcome.status).toBe("requeued");
expect(outcome.applied).toBe(2);
expect(state.updateMany).toHaveLength(1);
expect(state.updateMany).toHaveLength(2);
expect(state.updateMany).toEqual(
expect.arrayContaining([
expect.objectContaining({ tenantId: "tenant-1", status: ["FAILED"], deliveryGeneration: 0 }),
])
);
// FAILED rows a + b should have flipped to PENDING.
expect(state.byId.get("a")?.status).toBe("PENDING");
expect(state.byId.get("b")?.status).toBe("PENDING");
expect(state.byId.get("a")?.deliveryGeneration).toBe(1);
expect(state.byId.get("b")?.deliveryGeneration).toBe(1);
expect(state.byId.get("c")?.status).toBe("DONE");
expect(state.byId.get("d")?.status).toBe("PENDING"); // already pending, untouched
expect(state.byId.get("g")?.status).toBe("FAILED"); // same event type, different tenant
});
it("includes DONE events when --include-done is set", async () => {
it("rejects --include-done until consumer completion receipts exist", async () => {
const state = bulkState();
const output = makeOutput();
const outcome = await runOutboxRequeueBulk(
{ type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, includeDone: true },
{ tenantId: "tenant-1", type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, includeDone: true },
{ client: fakeClient(state), output }
);
expect(outcome.applied).toBe(3);
expect(state.byId.get("c")?.status).toBe("PENDING");
expect(outcome.exitCode).toBe(1);
expect(outcome.status).toBe("invalid_args");
expect(state.byId.get("c")?.status).toBe("DONE");
});
it("rejects malformed event type", async () => {
const state = bulkState();
const output = makeOutput();
const outcome = await runOutboxRequeueBulk({ type: "notavalidtype", since: "2026-05-20T00:00:00Z" }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueBulk(
{ tenantId: "tenant-1", type: "notavalidtype", since: "2026-05-20T00:00:00Z" },
{ client: fakeClient(state), output }
);
expect(outcome.exitCode).toBe(1);
expect(outcome.status).toBe("invalid_args");
expect(output.errors[0]).toMatch(/must match/);
@@ -251,7 +342,10 @@ describe("runOutboxRequeueBulk", () => {
it("rejects malformed --since", async () => {
const state = bulkState();
const output = makeOutput();
const outcome = await runOutboxRequeueBulk({ type: "billing.subscription.ended", since: "not-a-date" }, { client: fakeClient(state), output });
const outcome = await runOutboxRequeueBulk(
{ tenantId: "tenant-1", type: "billing.subscription.ended", since: "not-a-date" },
{ client: fakeClient(state), output }
);
expect(outcome.exitCode).toBe(1);
expect(outcome.status).toBe("invalid_args");
expect(output.errors[0]).toMatch(/ISO-8601/);
@@ -261,7 +355,7 @@ describe("runOutboxRequeueBulk", () => {
const state = bulkState();
const output = makeOutput();
await runOutboxRequeueBulk(
{ type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, json: true },
{ tenantId: "tenant-1", type: "billing.subscription.ended", since: "2026-05-20T00:00:00Z", apply: true, json: true },
{ client: fakeClient(state), output }
);
expect(output.jsons[0]).toMatchObject({ ok: true, applied: 2, matched: 2, eventType: "billing.subscription.ended" });
@@ -280,7 +374,10 @@ describe("runOutboxRequeueBulk", () => {
};
const output = makeOutput();
await runOutboxRequeueBulk({ type: "billing.subscription.ended", since: "2026-05-01T00:00:00Z", json: true }, { client: fakeClient(state), output });
await runOutboxRequeueBulk(
{ tenantId: "tenant-1", type: "billing.subscription.ended", since: "2026-05-01T00:00:00Z", json: true },
{ client: fakeClient(state), output }
);
expect(output.jsons[0]).toMatchObject({ ok: true, applied: 0, matched: 12 });
expect((output.jsons[0] as { preview: unknown[] }).preview).toHaveLength(10);
@@ -291,7 +388,7 @@ describe("runOutboxRequeueBulk", () => {
const state = bulkState();
const output = makeOutput();
const outcome = await runOutboxRequeueBulk(
{ type: "billing.subscription.ended", since: "2030-01-01T00:00:00Z", apply: true },
{ tenantId: "tenant-1", type: "billing.subscription.ended", since: "2030-01-01T00:00:00Z", apply: true },
{ client: fakeClient(state), output }
);
expect(outcome.exitCode).toBe(0);
@@ -316,7 +413,7 @@ describe("OutboxRequeueClient narrowness", () => {
// adjacent; we keep one runtime assertion to keep vitest happy.
const minimal: OutboxRequeueClient = {
outboxEvent: {
findUnique: vi.fn(async () => null),
findFirst: vi.fn(async () => null),
update: vi.fn(
async (): Promise<OutboxRequeueEventRow> => ({
id: "x",
@@ -324,6 +421,7 @@ describe("OutboxRequeueClient narrowness", () => {
status: "PENDING" as OutboxRequeueStatus,
tenantId: null,
retries: 0,
deliveryGeneration: 0,
createdAt: new Date(),
})
),
@@ -20,6 +20,7 @@ import consola from "consola";
import {
runOutboxRequeueById,
runOutboxRequeueBulk,
normalizeTenantId,
type OutboxRequeueClient,
type OutboxRequeueOutput,
} from "./_lib.js";
@@ -39,6 +40,11 @@ export const outboxRequeueCommand = defineCommand({
description: "Re-queue a single FAILED/DONE outbox event by id, or bulk-re-queue by eventType + since timestamp.",
},
args: {
tenant: {
type: "string",
required: true,
description: "Tenant id whose outbox rows may be inspected or changed.",
},
"event-id": {
type: "string",
required: false,
@@ -95,14 +101,17 @@ export const outboxRequeueCommand = defineCommand({
return;
}
const { getDbClient } = await import("@hivegrid/db/client.server");
const prisma = getDbClient() as unknown as OutboxRequeueClient;
const output = makeOutput(json);
try {
// The process-level CLI RLS wrapper binds the same `--tenant` value.
// Normalise it again here so every query/CAS carries the exact GUC scope.
const tenantId = normalizeTenantId(args.tenant);
const { getDbClient } = await import("@hivegrid/db/client.server");
const prisma = getDbClient() as unknown as OutboxRequeueClient;
if (eventId) {
const outcome = await runOutboxRequeueById(
{ eventId, json },
{ tenantId, eventId, json },
{ client: prisma, output }
);
process.exitCode = outcome.exitCode;
@@ -112,6 +121,7 @@ export const outboxRequeueCommand = defineCommand({
const limit = typeof args.limit === "string" && args.limit.length > 0 ? Number.parseInt(args.limit, 10) : undefined;
const outcome = await runOutboxRequeueBulk(
{
tenantId,
type: typeArg!,
since: sinceArg!,
apply: Boolean(args.apply),
@@ -20,6 +20,7 @@ vi.mock("@hivegrid/db/client.server", () => ({
}));
vi.mock("consola", () => ({
default: {
error: vi.fn(),
info: vi.fn(),
log: vi.fn(),
success: vi.fn(),
@@ -37,7 +38,7 @@ describe("plugins list command", () => {
dbMock.plugin.findMany.mockResolvedValue([]);
});
it("lists all rows with ON/OFF state when no filters are supplied", async () => {
it("lists one tenant's rows with ON/OFF state", async () => {
dbMock.plugin.findMany.mockResolvedValueOnce([
{
id: "row_1",
@@ -47,20 +48,12 @@ describe("plugins list command", () => {
enabled: true,
installedAt: new Date("2026-05-01T00:00:00.000Z"),
},
{
id: "row_2",
tenantId: "tenant_b",
pluginId: "com.acme.forms",
version: "0.9.0",
enabled: false,
installedAt: new Date("2026-05-02T00:00:00.000Z"),
},
]);
await pluginsListCommand.run?.({ args: {} } as never);
await pluginsListCommand.run?.({ args: { tenantId: "tenant_a" } } as never);
expect(dbMock.plugin.findMany).toHaveBeenCalledWith({
where: {},
where: { tenantId: "tenant_a" },
orderBy: [{ tenantId: "asc" }, { pluginId: "asc" }],
select: {
id: true,
@@ -72,8 +65,7 @@ describe("plugins list command", () => {
},
});
expect(consoleMock.log).toHaveBeenCalledWith(expect.stringMatching(/^ON .*tenant_a.*com\.acme\.crm.*v1\.2\.3/u));
expect(consoleMock.log).toHaveBeenCalledWith(expect.stringMatching(/^OFF.*tenant_b.*com\.acme\.forms.*v0\.9\.0/u));
expect(consoleMock.success).toHaveBeenCalledWith("2 plugin row(s) listed.");
expect(consoleMock.success).toHaveBeenCalledWith("1 plugin row(s) listed.");
});
it("narrows the query to a single tenant and only-enabled rows", async () => {
@@ -96,17 +88,18 @@ describe("plugins list command", () => {
});
it("filters to disabled rows when enabled=false", async () => {
await pluginsListCommand.run?.({ args: { enabled: "false" } } as never);
await pluginsListCommand.run?.({ args: { tenantId: "tenant_a", enabled: "false" } } as never);
expect(dbMock.plugin.findMany).toHaveBeenCalledWith(
expect.objectContaining({ where: { enabled: false } }),
expect.objectContaining({ where: { tenantId: "tenant_a", enabled: false } }),
);
});
it("ignores a blank tenantId and an unrecognised enabled value", async () => {
it("rejects a blank tenantId", async () => {
await pluginsListCommand.run?.({ args: { tenantId: "", enabled: "maybe" } } as never);
expect(dbMock.plugin.findMany).toHaveBeenCalledWith(expect.objectContaining({ where: {} }));
expect(consoleMock.error).toHaveBeenCalledWith("--tenantId is required.");
expect(dbMock.plugin.findMany).not.toHaveBeenCalled();
});
it("prints an info message and no summary when nothing matches", async () => {
@@ -1,6 +1,6 @@
/**
* `plugins list` — print every installed plugin row across all tenants
* (or filtered to one).
* `plugins list --tenantId <id>` — print installed plugin rows for one
* explicitly selected tenant.
*/
import { defineCommand } from "citty";
import consola from "consola";
@@ -13,7 +13,8 @@ export const pluginsListCommand = defineCommand({
args: {
tenantId: {
type: "string",
description: "Filter to a single tenant.",
required: true,
description: "Tenant id.",
},
enabled: {
type: "string",
@@ -23,10 +24,13 @@ export const pluginsListCommand = defineCommand({
async run({ args }) {
const { getDbClient } = await import("@hivegrid/db/client.server");
const prisma = getDbClient();
const where: Record<string, unknown> = {};
if (typeof args.tenantId === "string" && args.tenantId.length > 0) {
where.tenantId = args.tenantId;
const tenantId = typeof args.tenantId === "string" ? args.tenantId.trim() : "";
if (!tenantId) {
consola.error("--tenantId is required.");
process.exitCode = 1;
return;
}
const where: Record<string, unknown> = { tenantId };
if (args.enabled === "true") where.enabled = true;
if (args.enabled === "false") where.enabled = false;
const rows = await prisma.plugin.findMany({
@@ -27,12 +27,12 @@ describe("selectIndexes", () => {
(name) => !(BULK_REINDEX_SUPPORTED_INDEX_NAMES as readonly string[]).includes(name)
);
// `files`, `tasks`, `hr-directory` and `hr-locations` are cataloged in
// `chat-messages`, `files`, `tasks`, `hr-directory` and `hr-locations` are cataloged in
// ALL_SEARCH_INDEXES but intentionally have no bulk-reindex pager (not in
// BULK_REINDEX_SUPPORTED_INDEX_NAMES), so they must reject in selectIndexes.
// HR (P17 — AK-P17a) follows the same per-event-only pattern as `tasks`; a
// bulk-reindex pager for HR would be follow-up work.
expect(unsupportedCatalogNames).toEqual(["files", "tasks", "hr-directory", "hr-locations"]);
// Chat (P15) and HR (P17 — AK-P17a) follow the same per-event-only pattern
// as `tasks`; bulk-reindex pagers remain separate follow-up work.
expect(unsupportedCatalogNames).toEqual(["chat-messages", "files", "tasks", "hr-directory", "hr-locations"]);
for (const name of unsupportedCatalogNames) {
expect(() => selectIndexes(name)).toThrow(/Unsupported search reindex target/);
}
@@ -85,7 +85,11 @@ export const searchReindexCommand = defineCommand({
// Lazy-load the Prisma-backed publish so the CLI binary does not pull
// in @prisma/client at import time. Imports happen here, inside the
// run handler, after argument parsing.
const [{ getDbClient }, dbOutbox] = await Promise.all([import("@hivegrid/db/client.server"), import("@hivegrid/db/outbox")]);
const [{ getDbClient }, { runWithRlsContext }, dbOutbox] = await Promise.all([
import("@hivegrid/db/client.server"),
import("@hivegrid/db/rls-context.server"),
import("@hivegrid/db/outbox"),
]);
const prisma = getDbClient();
const tenantIds = await resolveTenantIds(prisma, tenantArg);
if (tenantIds.length === 0) {
@@ -94,13 +98,15 @@ export const searchReindexCommand = defineCommand({
}
const publish = async (event: { tenantId: string; type: string; payload: Record<string, unknown> }) => {
await prisma.$transaction(async (tx: unknown) => {
await dbOutbox.publishOutboxEvent(tx as Parameters<typeof dbOutbox.publishOutboxEvent>[0], {
tenantId: event.tenantId,
type: event.type,
payload: event.payload as Parameters<typeof dbOutbox.publishOutboxEvent>[1]["payload"],
});
});
await runWithRlsContext({ tenantId: event.tenantId }, () =>
prisma.$transaction(async (tx: unknown) => {
await dbOutbox.publishOutboxEvent(tx as Parameters<typeof dbOutbox.publishOutboxEvent>[0], {
tenantId: event.tenantId,
type: event.type,
payload: event.payload as Parameters<typeof dbOutbox.publishOutboxEvent>[1]["payload"],
});
}),
);
};
const results = await enqueueReindexEvents({ indexes, tenantIds, publish });
@@ -58,7 +58,7 @@ describe("anonymize", () => {
FULL_ANONYMIZED_PROFILE,
"TenantUserInvitation",
{ email: "alice@example.com", firstName: "Alice", lastName: "Wonderland" },
ctx,
ctx
);
expect(row.email).toMatch(/@anonymized\.test$/u);
expect(row.firstName).not.toBe("Alice");
@@ -66,12 +66,7 @@ describe("anonymize", () => {
});
it("masks IP to 127.0.0.x", () => {
const row = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"TenantIpAddress",
{ ip: "203.0.113.42", fromUrl: "https://example.com" },
ctx,
);
const row = anonymizeRow(FULL_ANONYMIZED_PROFILE, "TenantIpAddress", { ip: "203.0.113.42", fromUrl: "https://example.com" }, ctx);
expect(row.ip).toMatch(/^127\.0\.0\.\d{1,3}$/u);
expect(row.fromUrl).toMatch(/^https:\/\/anonymized\.test\//u);
});
@@ -81,44 +76,95 @@ describe("anonymize", () => {
FULL_ANONYMIZED_PROFILE,
"TenantSubscription",
{ billingProviderCustomerId: "cus_real", billingProviderSubscriptionId: "sub_real" },
ctx,
ctx
);
expect(row.billingProviderCustomerId).toMatch(/^cus_anon[0-9a-f]{8}$/u);
expect(row.billingProviderSubscriptionId).toMatch(/^sub_anon[0-9a-f]{8}$/u);
});
it("redacts secrets to [REDACTED]", () => {
const row = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"WorkflowCredential",
{ secret: "very-secret-token", apiKey: "sk_live_real" },
ctx,
);
const row = anonymizeRow(FULL_ANONYMIZED_PROFILE, "WorkflowCredential", { secret: "very-secret-token", apiKey: "sk_live_real" }, ctx);
expect(row.secret).toBe("[REDACTED]");
expect(row.apiKey).toBe("[REDACTED]");
});
it("leaves unrelated fields untouched", () => {
const row = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"TenantSubscription",
{ billingProviderCustomerId: "cus_real", planTier: "pro", active: true },
ctx,
);
const row = anonymizeRow(FULL_ANONYMIZED_PROFILE, "TenantSubscription", { billingProviderCustomerId: "cus_real", planTier: "pro", active: true }, ctx);
expect(row.planTier).toBe("pro");
expect(row.active).toBe(true);
});
it("passes null/undefined fields through without invocation", () => {
const row = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"UserNotificationPreference",
{ email: null, phone: undefined },
ctx,
);
const row = anonymizeRow(FULL_ANONYMIZED_PROFILE, "UserNotificationPreference", { email: null, phone: undefined }, ctx);
expect(row.email).toBeNull();
expect(row.phone).toBeUndefined();
});
it("scrubs PII, portal credentials, and payloads carried by lifecycle children", () => {
const email = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"Email",
{
messageId: "provider-message-123",
subject: "Private customer request",
fromEmail: "alice@example.com",
fromName: "Alice Customer",
toEmail: "support@company.test",
toName: "Support Team",
textBody: "My private message",
htmlBody: "<p>My private message</p>",
},
ctx
);
const article = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"KnowledgeBaseArticle",
{ description: "Customer-specific notes", contentDraft: "Secret draft" },
ctx
);
const portalUser = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"PortalUser",
{
email: "portal@example.com",
emailNormalized: "portal@example.com",
firstName: "Portal",
lastName: "Customer",
passwordHash: "$argon2id$portal-secret",
privacyNoticeAcknowledgedAt: new Date("2026-07-18T12:00:00.000Z"),
privacyNoticeAcknowledgedUrl: "https://portal.example.test/datenschutz",
},
ctx
);
const portalToken = anonymizeRow(FULL_ANONYMIZED_PROFILE, "PortalToken", { tokenHash: "hashed-portal-token", requestedIpHash: "hashed-request-ip" }, ctx);
const workflowRun = anonymizeRow(
FULL_ANONYMIZED_PROFILE,
"WorkflowBlockExecution",
{ input: "customer@example.com", output: "private result", error: "token=secret" },
ctx
);
const attachment = anonymizeRow(FULL_ANONYMIZED_PROFILE, "EmailAttachment", { name: "Alice-Mueller-Vertrag.pdf", content: "private file" }, ctx);
expect(JSON.stringify(email)).not.toContain("alice@example.com");
expect(email.fromEmail).toMatch(/@anonymized\.test$/u);
expect(email.subject).toBe("[REDACTED]");
expect(email.textBody).toBe("[REDACTED]");
expect(attachment.name).toMatch(/^anon-[0-9a-f]{16}$/u);
expect(JSON.stringify(attachment)).not.toContain("Alice-Mueller");
expect(article).toMatchObject({ description: "[REDACTED]", contentDraft: "[REDACTED]" });
expect(portalUser.email).toMatch(/@anonymized\.test$/u);
expect(portalUser.emailNormalized).toMatch(/@anonymized\.test$/u);
expect(portalUser.passwordHash).toBeNull();
expect(portalUser.privacyNoticeAcknowledgedAt).toBeNull();
expect(portalUser.privacyNoticeAcknowledgedUrl).toBeNull();
expect(portalToken.tokenHash).toMatch(/^[0-9a-f]{64}$/u);
expect(portalToken.requestedIpHash).toMatch(/^[0-9a-f]{64}$/u);
expect(workflowRun).toMatchObject({
input: "[REDACTED]",
output: "[REDACTED]",
error: "[REDACTED]",
});
});
});
describe("minimal-anonymized profile", () => {
@@ -127,7 +173,7 @@ describe("anonymize", () => {
MINIMAL_ANONYMIZED_PROFILE,
"TenantUserInvitation",
{ email: "alice@example.com", firstName: "Alice", lastName: "Wonderland" },
{ ...ctx, profileName: "minimal-anonymized" },
{ ...ctx, profileName: "minimal-anonymized" }
);
expect(row.firstName).toBe("Alice");
expect(row.lastName).toBe("Wonderland");
@@ -138,18 +184,13 @@ describe("anonymize", () => {
MINIMAL_ANONYMIZED_PROFILE,
"TenantUserInvitation",
{ email: "alice@example.com" },
{ ...ctx, profileName: "minimal-anonymized" },
{ ...ctx, profileName: "minimal-anonymized" }
);
expect(row.email).toMatch(/@anonymized\.test$/u);
});
it("still scrubs IP address", () => {
const row = anonymizeRow(
MINIMAL_ANONYMIZED_PROFILE,
"TenantIpAddress",
{ ip: "203.0.113.42" },
{ ...ctx, profileName: "minimal-anonymized" },
);
const row = anonymizeRow(MINIMAL_ANONYMIZED_PROFILE, "TenantIpAddress", { ip: "203.0.113.42" }, { ...ctx, profileName: "minimal-anonymized" });
expect(row.ip).toMatch(/^127\.0\.0\.\d{1,3}$/u);
});
});
@@ -172,11 +213,7 @@ describe("anonymize", () => {
});
it("truncate-32 trims to 32 chars with ellipsis", () => {
const result = applyStrategy(
"truncate-32",
"a very long string that exceeds thirty two characters",
ctx,
);
const result = applyStrategy("truncate-32", "a very long string that exceeds thirty two characters", ctx);
expect(String(result).length).toBe(32);
expect(String(result)).toMatch(/\.\.\.$/u);
});
@@ -186,6 +223,11 @@ describe("anonymize", () => {
expect(result).toMatch(/^anon-[0-9a-f]{16}$/u);
});
it("sha256-hex preserves database hash constraints", () => {
const result = applyStrategy("sha256-hex", "some-original", ctx);
expect(result).toMatch(/^[0-9a-f]{64}$/u);
});
it("avatar-url returns an anonymized.test url", () => {
const result = applyStrategy("avatar-url", "https://example.com/me.png", ctx);
expect(result).toMatch(/^https:\/\/anonymized\.test\/avatar\/[0-9a-f]{8}\.png$/u);
@@ -38,6 +38,7 @@ export type FieldStrategy =
| "avatar-url"
| "redact"
| "sha256-prefix"
| "sha256-hex"
| "truncate-32";
export type ProfileName = "full-anonymized" | "minimal-anonymized" | "none";
@@ -73,7 +74,7 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
metadata: "redact",
},
ApiKey: {
name: "truncate-32",
name: "sha256-prefix",
description: "redact",
hash: "sha256-prefix",
prefix: "sha256-prefix",
@@ -91,7 +92,12 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
// event-shaped payload). Catches plaintext emails and identifiers
// that callers stuff in for debugging.
data: "redact",
description: "truncate-32",
description: "redact",
},
EventWebhookAttempt: {
endpoint: "url-rewrite",
message: "redact",
body: "redact",
},
Log: {
error: "redact",
@@ -101,6 +107,9 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
fromEmail: "email",
fromName: "full-name",
replyToEmail: "email",
subject: "redact",
htmlBody: "redact",
textBody: "redact",
},
EmailSender: {
fromEmail: "email",
@@ -112,15 +121,42 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
address: "email",
forwardTo: "email",
},
Email: {
messageId: "sha256-prefix",
subject: "redact",
fromEmail: "email",
fromName: "full-name",
toEmail: "email",
toName: "full-name",
textBody: "redact",
htmlBody: "redact",
},
EmailCc: {
toEmail: "email",
toName: "full-name",
},
EmailAttachment: {
name: "sha256-prefix",
content: "redact",
publicUrl: "url-rewrite",
},
OutboundEmail: {
email: "email",
fromEmail: "email",
fromName: "full-name",
toEmail: "email",
replyToEmail: "email",
subject: "truncate-32",
subject: "redact",
htmlBody: "redact",
textBody: "redact",
},
OutboundEmailClick: {
link: "url-rewrite",
},
EmailSequenceStepDelivery: {
providerMessageId: "sha256-prefix",
errorMessage: "redact",
},
TenantSubscription: {
billingProviderCustomerId: "billing-customer-id",
billingProviderSubscriptionId: "billing-subscription-id",
@@ -136,6 +172,7 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
apiKey: "redact",
accessToken: "redact",
refreshToken: "redact",
value: "redact",
},
Workflow: {
webhookSecret: "redact",
@@ -143,6 +180,27 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
WorkflowExecution: {
contextJson: "redact",
errorMessage: "redact",
input: "redact",
output: "redact",
error: "redact",
},
WorkflowBlock: {
description: "redact",
input: "redact",
},
WorkflowBlockCondition: {
value: "redact",
},
WorkflowBlockToBlock: {
condition: "redact",
},
WorkflowInputExample: {
input: "redact",
},
WorkflowBlockExecution: {
input: "redact",
output: "redact",
error: "redact",
},
DataConnection: {
accessToken: "redact",
@@ -167,18 +225,33 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
SupportTicket: {
// Schema fields are `subject` and `message`, not `title`/`description`
// (the previous map referenced nonexistent fields — see B7 verify).
subject: "truncate-32",
subject: "redact",
message: "redact",
fromEmail: "email",
fromUrl: "url-rewrite",
},
Portal: {
customDomain: "url-rewrite",
domain: "url-rewrite",
},
PortalUser: {
email: "email",
emailNormalized: "email",
firstName: "first-name",
lastName: "last-name",
passwordHash: "null",
privacyNoticeAcknowledgedAt: "null",
privacyNoticeAcknowledgedUrl: "null",
},
PortalSession: {
tokenHash: "sha256-prefix",
ipAddressHash: "sha256-prefix",
},
PortalToken: {
tokenHash: "sha256-hex",
requestedIpHash: "sha256-hex",
},
PortalPage: {
attributes: "redact",
},
NotificationDelivery: {
payload: "redact",
@@ -197,6 +270,55 @@ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = {
KnowledgeBase: {
description: "redact",
},
KnowledgeBaseCategory: {
description: "redact",
},
KnowledgeBaseCategorySection: {
description: "redact",
},
KnowledgeBaseArticle: {
description: "redact",
contentDraft: "redact",
contentPublished: "redact",
contentPublishedAsText: "redact",
},
KnowledgeBaseViews: {
userAnalyticsId: "sha256-prefix",
},
KnowledgeBaseArticleViews: {
userAnalyticsId: "sha256-prefix",
},
KnowledgeBaseArticleUpvotes: {
userAnalyticsId: "sha256-prefix",
},
KnowledgeBaseArticleDownvotes: {
userAnalyticsId: "sha256-prefix",
},
AnalyticsUniqueVisitor: {
cookie: "sha256-prefix",
httpReferrer: "url-rewrite",
city: "redact",
fromUrl: "url-rewrite",
},
AnalyticsPageView: {
url: "url-rewrite",
},
AnalyticsEvent: {
label: "redact",
value: "redact",
url: "url-rewrite",
},
OnboardingSessionAction: {
value: "redact",
},
PluginUserConfig: {
configJson: "redact",
},
TenantSubscriptionProduct: {
billingProviderSubscriptionId: "billing-subscription-id",
lagoSubscriptionId: "payment-id-generic",
fromCheckoutSessionId: "payment-id-generic",
},
/**
* Global rows extracted alongside the tenant slice. These rows are
* referenced by tenant-scoped FKs and otherwise break restore into an
@@ -264,25 +386,54 @@ export interface AnonymizationContext {
}
const FIRST_NAMES = [
"Alex", "Sam", "Jordan", "Taylor", "Morgan", "Casey", "Avery", "Riley",
"Quinn", "Reese", "Skyler", "Drew", "Elliot", "Hayden", "Jamie", "Kai",
"Logan", "Parker", "Robin", "Sage", "Tatum", "River", "Phoenix", "Rowan",
"Alex",
"Sam",
"Jordan",
"Taylor",
"Morgan",
"Casey",
"Avery",
"Riley",
"Quinn",
"Reese",
"Skyler",
"Drew",
"Elliot",
"Hayden",
"Jamie",
"Kai",
"Logan",
"Parker",
"Robin",
"Sage",
"Tatum",
"River",
"Phoenix",
"Rowan",
];
const LAST_NAMES = [
"Smith", "Johnson", "Lee", "Patel", "Garcia", "Mueller", "Schmidt", "Nguyen",
"Kim", "Davis", "Brown", "Wilson", "Mendez", "Rossi", "Andersen", "Becker",
"Smith",
"Johnson",
"Lee",
"Patel",
"Garcia",
"Mueller",
"Schmidt",
"Nguyen",
"Kim",
"Davis",
"Brown",
"Wilson",
"Mendez",
"Rossi",
"Andersen",
"Becker",
];
const STREET_NAMES = [
"Main", "Oak", "Pine", "Maple", "Elm", "Cedar", "Birch", "Willow", "Cherry",
"Hauptstrasse", "Bahnhofstrasse",
];
const STREET_NAMES = ["Main", "Oak", "Pine", "Maple", "Elm", "Cedar", "Birch", "Willow", "Cherry", "Hauptstrasse", "Bahnhofstrasse"];
const CITIES = [
"Springfield", "Riverton", "Oakville", "Lakeside", "Hillview", "Mapleton",
"Pinehurst", "Bergstadt", "Seedorf",
];
const CITIES = ["Springfield", "Riverton", "Oakville", "Lakeside", "Hillview", "Mapleton", "Pinehurst", "Bergstadt", "Seedorf"];
const COUNTRIES = ["AT", "DE", "CH", "NL", "PT", "IE", "FI", "SE"];
@@ -295,7 +446,7 @@ export function anonymizeRow(
profile: AnonymizationProfile,
modelName: string,
row: Record<string, unknown>,
ctx: AnonymizationContext,
ctx: AnonymizationContext
): Record<string, unknown> {
const mapping = profile[modelName];
if (!mapping) return { ...row };
@@ -310,11 +461,7 @@ export function anonymizeRow(
}
/** Apply a single field strategy. Exported for unit tests. */
export function applyStrategy(
strategy: FieldStrategy,
value: unknown,
ctx: AnonymizationContext,
): unknown {
export function applyStrategy(strategy: FieldStrategy, value: unknown, ctx: AnonymizationContext): unknown {
switch (strategy) {
case "keep":
return value;
@@ -359,6 +506,8 @@ export function applyStrategy(
return `https://anonymized.test/avatar/${seededHex(value, ctx, 8)}.png`;
case "sha256-prefix":
return `anon-${seedHex(stringify(value), ctx).slice(0, 16)}`;
case "sha256-hex":
return seedHex(stringify(value), ctx);
case "truncate-32": {
const s = stringify(value);
return s.length > 32 ? `${s.slice(0, 29)}...` : s;
@@ -0,0 +1,308 @@
import { describe, expect, it } from "vitest";
import { readdirSync, readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import {
DERIVED_GLOBAL_REFERENCED_MODELS,
TENANT_DERIVED_MODELS,
TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS,
TENANT_LIFECYCLE_MODELS,
isTenantDerivedModel,
tenantWhereForLifecycleModel,
} from "./derived-models.js";
const here = dirname(fileURLToPath(import.meta.url));
const repoRoot = join(here, "..", "..", "..", "..", "..");
const schemaDir = join(repoRoot, "prisma", "schema");
function derivedManifestModels(): string[] {
const source = readFileSync(join(repoRoot, "prisma", "tenant-scope-manifest.mjs"), "utf8");
const group = /"derived-child": Object\.freeze\(\[([\s\S]*?)\]\),/u.exec(source)?.[1];
if (!group) throw new Error("tenant-scope manifest has no derived-child group");
return Array.from(group.matchAll(/"([A-Za-z0-9_]+)"/gu), (match) => match[1]!);
}
function schemaModels(): Map<string, { schema: string; body: string; relations: ReadonlyMap<string, string> }> {
const models = new Map<string, { schema: string; body: string; relations: ReadonlyMap<string, string> }>();
for (const schema of readdirSync(schemaDir).filter((file) => file.endsWith(".prisma"))) {
const source = readFileSync(join(schemaDir, schema), "utf8");
for (const match of source.matchAll(/model\s+(\w+)\s*\{([\s\S]*?)\n\}/gu)) {
const body = match[2]!;
const relations = new Map<string, string>();
for (const line of body.split("\n")) {
const relation = /^(\w+)\s+(\w+)\??\s+.*@relation/u.exec(line.trim());
if (relation) relations.set(relation[1]!, relation[2]!);
}
models.set(match[1]!, { schema, body, relations });
}
}
return models;
}
function position(model: string): number {
return TENANT_LIFECYCLE_MODELS.findIndex((entry) => entry.model === model);
}
describe("TENANT_DERIVED_MODELS", () => {
it("covers every model classified as a derived child in the scope manifest", () => {
expect(new Set(TENANT_DERIVED_MODELS.map((entry) => entry.model))).toEqual(new Set(derivedManifestModels()));
});
it("matches the owning paths and combination rules in the RLS policy contract", async () => {
type ContractPath = {
readonly relations: readonly string[];
readonly allowGlobalRead?: boolean;
readonly allowGlobalWrite?: boolean;
};
type ContractEntry = {
readonly anyOf: readonly ContractPath[];
readonly allOf: readonly ContractPath[];
readonly optionalAllOf: readonly ContractPath[];
};
const policyModule = (await import(pathToFileURL(join(repoRoot, "prisma", "tenant-policy-contract.mjs")).href)) as {
DERIVED_OWNERSHIP_CONTRACT: Readonly<Record<string, ContractEntry>>;
};
const contract = policyModule.DERIVED_OWNERSHIP_CONTRACT;
const lifecyclePath = (path: ContractPath): ContractPath => ({
relations: path.relations,
...(path.allowGlobalWrite === true ? { allowGlobalRead: true, allowGlobalWrite: true } : {}),
});
for (const entry of TENANT_DERIVED_MODELS) {
const direct = entry.tenantPaths.map((relations) => ({ relations }));
const actual: { anyOf: ContractPath[]; allOf: ContractPath[]; optionalAllOf: ContractPath[] } = {
anyOf: [],
allOf: [],
optionalAllOf: [],
};
if (direct.length > 1 && entry.tenantPathMode !== "all") actual.anyOf.push(...direct);
else actual.allOf.push(...direct);
actual.allOf.push(
...(entry.tenantOrGlobalPaths ?? []).map((relations) => ({
relations,
allowGlobalRead: true,
allowGlobalWrite: true,
}))
);
actual.optionalAllOf.push(
...(entry.optionalTenantPaths ?? []).map(({ path: relations }) => ({ relations })),
...(entry.optionalTenantOrGlobalPaths ?? []).map(({ path: relations }) => ({
relations,
allowGlobalRead: true,
allowGlobalWrite: true,
}))
);
expect(actual, entry.model).toEqual({
anyOf: contract[entry.model]?.anyOf.map(lifecyclePath),
allOf: contract[entry.model]?.allOf.map(lifecyclePath),
optionalAllOf: contract[entry.model]?.optionalAllOf.map(lifecyclePath),
});
}
expect(new Set(Object.keys(contract))).toEqual(new Set(TENANT_DERIVED_MODELS.map((entry) => entry.model)));
});
it("contains only existing models without a tenantId scalar", () => {
const models = schemaModels();
const violations = TENANT_DERIVED_MODELS.flatMap((entry) => {
const model = models.get(entry.model);
if (!model) return [`${entry.model}: missing schema model`];
if (model.schema !== entry.schema) return [`${entry.model}: expected ${entry.schema}, got ${model.schema}`];
if (/^\s*tenantId\s+String/mu.test(model.body)) return [`${entry.model}: has direct tenantId`];
return [];
});
expect(violations).toEqual([]);
});
it("declares unique names, non-empty paths, and known dependencies", () => {
const names = TENANT_DERIVED_MODELS.map((entry) => entry.model);
const lifecycleNames = new Set(TENANT_LIFECYCLE_MODELS.map((entry) => entry.model));
const models = schemaModels();
const invalidPaths: string[] = [];
expect(new Set(names).size).toBe(names.length);
for (const entry of TENANT_DERIVED_MODELS) {
expect(entry.tenantPaths.length).toBeGreaterThan(0);
expect(entry.tenantPaths.every((path) => path.length > 0)).toBe(true);
const paths = [
...entry.tenantPaths,
...(entry.optionalTenantPaths ?? []).map((optional) => optional.path),
...(entry.tenantOrGlobalPaths ?? []),
...(entry.optionalTenantOrGlobalPaths ?? []).map((optional) => optional.path),
];
for (const path of paths) {
let current = entry.model;
for (const relation of path) {
const target = models.get(current)?.relations.get(relation);
if (!target) {
invalidPaths.push(`${entry.model}: ${current}.${relation} is not a relation`);
break;
}
current = target;
}
if (!/^\s*tenantId\s+String/mu.test(models.get(current)?.body ?? "")) {
invalidPaths.push(`${entry.model}: ${path.join(".")} ends at ${current} without tenantId`);
}
}
for (const optional of [...(entry.optionalTenantPaths ?? []), ...(entry.optionalTenantOrGlobalPaths ?? [])]) {
const body = models.get(entry.model)?.body ?? "";
const field = new RegExp(`^\\s*${optional.foreignKey}\\s+\\w+\\?`, "mu");
if (!field.test(body)) {
invalidPaths.push(`${entry.model}: ${optional.foreignKey} is not a nullable FK scalar`);
}
}
expect(entry.dependsOn.every((dependency) => lifecycleNames.has(dependency))).toBe(true);
expect((entry.restoreBefore ?? []).every((target) => lifecycleNames.has(target))).toBe(true);
expect(isTenantDerivedModel(entry.model)).toBe(true);
}
expect(invalidPaths).toEqual([]);
expect(isTenantDerivedModel("TenantUser")).toBe(false);
});
it("builds focused Email, KnowledgeBase, Workflow, and Portal relation filters", () => {
const byModel = new Map(TENANT_LIFECYCLE_MODELS.map((entry) => [entry.model, entry]));
expect(tenantWhereForLifecycleModel(byModel.get("EmailRead")!, "tenant_1")).toEqual({
email: { tenantInboundAddress: { tenantId: "tenant_1" } },
});
expect(tenantWhereForLifecycleModel(byModel.get("AnalyticsUniqueVisitor")!, "tenant_1")).toEqual({
AND: [
{
OR: [{ portal: { tenantId: "tenant_1" } }, { portalUser: { tenantId: "tenant_1" } }],
},
{ OR: [{ portalId: null }, { portal: { tenantId: "tenant_1" } }] },
{ OR: [{ portalUserId: null }, { portalUser: { tenantId: "tenant_1" } }] },
],
});
expect(tenantWhereForLifecycleModel(byModel.get("KnowledgeBaseArticle")!, "tenant_1")).toEqual({
AND: [
{ knowledgeBase: { tenantId: "tenant_1" } },
{
OR: [{ categoryId: null }, { category: { knowledgeBase: { tenantId: "tenant_1" } } }],
},
{
OR: [{ sectionId: null }, { section: { category: { knowledgeBase: { tenantId: "tenant_1" } } } }],
},
],
});
expect(tenantWhereForLifecycleModel(byModel.get("WorkflowBlockCondition")!, "tenant_1")).toEqual({
workflowBlockConditionGroup: {
workflowBlock: { workflow: { tenantId: "tenant_1" } },
},
});
expect(tenantWhereForLifecycleModel(byModel.get("WorkflowBlockExecution")!, "tenant_1")).toEqual({
AND: [
{ workflowExecution: { tenantId: "tenant_1" } },
{
OR: [{ workflowBlock: { workflow: { tenantId: "tenant_1" } } }, { workflowBlock: { workflow: { tenantId: null } } }],
},
{
OR: [
{ fromWorkflowBlockId: null },
{ fromWorkflowBlock: { workflow: { tenantId: "tenant_1" } } },
{ fromWorkflowBlock: { workflow: { tenantId: null } } },
],
},
],
});
expect(tenantWhereForLifecycleModel(byModel.get("PortalPage")!, "tenant_1")).toEqual({
portal: { tenantId: "tenant_1" },
});
});
it("orders every dependency before its child and WorkflowBlock before WorkflowExecution", () => {
for (const entry of TENANT_DERIVED_MODELS) {
for (const dependency of entry.dependsOn) {
expect(position(dependency), `${dependency} must precede ${entry.model}`).toBeLessThan(position(entry.model));
}
for (const target of entry.restoreBefore ?? []) {
expect(position(entry.model), `${entry.model} must precede ${target}`).toBeLessThan(position(target));
}
}
expect(position("WorkflowBlock")).toBeLessThan(position("WorkflowExecution"));
expect(position("KnowledgeBaseArticle")).toBeLessThan(position("KnowledgeBaseRelatedArticle"));
});
it("orders every lifecycle FK parent before its child", () => {
const lifecycleNames = new Set(TENANT_LIFECYCLE_MODELS.map((entry) => entry.model));
const models = schemaModels();
const violations: string[] = [];
for (const [child, model] of models) {
if (!lifecycleNames.has(child)) continue;
for (const line of model.body.split("\n")) {
const relation = /^(\w+)\s+(\w+)(?:\?|\[\])?\s+.*@relation\s*\(([^)]*)\)/u.exec(line.trim());
if (!relation || !/fields\s*:/u.test(relation[3]!)) continue;
const parent = relation[2]!;
if (!lifecycleNames.has(parent) || parent === child) continue;
if (position(parent) >= position(child)) violations.push(`${parent} -> ${child}`);
}
}
expect(violations).toEqual([]);
expect(position("ApiKey")).toBeLessThan(position("TenantIpAddress"));
expect(position("RecipientSegment")).toBeLessThan(position("Campaign"));
});
it("merges User references discovered only in derived rows", () => {
expect(DERIVED_GLOBAL_REFERENCED_MODELS.find((entry) => entry.model === "User")).toEqual(
expect.objectContaining({
referencedBy: expect.arrayContaining([
{ model: "AnalyticsUniqueVisitor", fkColumn: "userId" },
{ model: "EmailRead", fkColumn: "userId" },
{ model: "GroupUser", fkColumn: "userId" },
{ model: "KnowledgeBaseArticle", fkColumn: "createdByUserId" },
]),
})
);
const user = TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS.find((entry) => entry.model === "User");
expect(user?.referencedBy).toEqual(expect.arrayContaining([{ model: "EmailRead", fkColumn: "userId" }]));
expect(TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS.map((entry) => entry.model)).toEqual([
"User",
"McpOAuthClient",
"Role",
"Permission",
"RolePermission",
"Workflow",
"WorkflowBlock",
"WorkflowBlockConditionGroup",
"WorkflowBlockCondition",
"WorkflowBlockToBlock",
"WorkflowInputExample",
"EmailSequence",
"FeatureFlag",
"FeatureFlagFilter",
]);
expect(TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS.find((entry) => entry.model === "Workflow")).toEqual(
expect.objectContaining({ where: { tenantId: null } })
);
});
it("declares valid global reference columns in FK-safe restore order", () => {
const models = schemaModels();
const globalPosition = new Map(TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS.map((entry, index) => [entry.model, index]));
const violations: string[] = [];
for (const target of TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS) {
for (const ref of target.referencedBy) {
const source = models.get(ref.model);
if (!source) {
violations.push(`${target.model}: missing source model ${ref.model}`);
continue;
}
const field = new RegExp(`^\\s*${ref.fkColumn}\\s+\\w+`, "mu");
if (!field.test(source.body)) {
violations.push(`${target.model}: missing ${ref.model}.${ref.fkColumn}`);
}
}
}
for (const [sourceName, source] of models) {
const sourceIndex = globalPosition.get(sourceName);
if (sourceIndex === undefined) continue;
for (const line of source.body.split("\n")) {
const relation = /^(\w+)\s+(\w+)(?:\?|\[\])?\s+.*@relation\s*\(([^)]*)\)/u.exec(line.trim());
if (!relation || !/fields\s*:/u.test(relation[3]!)) continue;
const targetName = relation[2]!;
const targetIndex = globalPosition.get(targetName);
if (targetIndex !== undefined && targetName !== sourceName && targetIndex >= sourceIndex) {
violations.push(`${targetName} must precede ${sourceName}`);
}
}
}
expect(violations).toEqual([]);
});
});
@@ -0,0 +1,593 @@
import {
GLOBAL_REFERENCED_MODELS,
TENANT_SCOPED_MODELS,
type GlobalReferencedModel,
type TenantScopedModel,
} from "./models.js";
export interface TenantDerivedModel {
/** Prisma model name (PascalCase as written in the schema). */
readonly model: string;
/** Schema file the model lives in, for diagnostics. */
readonly schema: string;
/**
* To-one relation paths that reach a model with a tenantId column.
* Multiple paths default to OR; `tenantPathMode` can require all of them.
*/
readonly tenantPaths: ReadonlyArray<readonly string[]>;
readonly tenantPathMode?: "any" | "all";
/** Nullable relations must be absent or resolve back to the same tenant. */
readonly optionalTenantPaths?: ReadonlyArray<{
readonly foreignKey: string;
readonly path: readonly string[];
}>;
/** Required relations whose owner may be tenant-specific or global. */
readonly tenantOrGlobalPaths?: ReadonlyArray<readonly string[]>;
/** Nullable variant of tenantOrGlobalPaths. */
readonly optionalTenantOrGlobalPaths?: ReadonlyArray<{
readonly foreignKey: string;
readonly path: readonly string[];
}>;
/** Models that must already exist when this model is restored. */
readonly dependsOn: readonly string[];
/**
* Direct tenant models that reference this derived model. This is rare,
* but it matters for FK-safe restore/delete ordering.
*/
readonly restoreBefore?: readonly string[];
/** Cursor metadata for models whose stable unique key is not `id`. */
readonly cursor?: {
readonly fields: readonly string[];
readonly compoundField: string;
};
}
/**
* Tenant-owned models whose scope is inherited exclusively through an FK.
*
* The declaration order is parents-first. `TENANT_LIFECYCLE_MODELS` combines
* this registry with direct tenant models and applies the explicit dependency
* edges below, so snapshot/restore and hard-delete share one safe ordering.
*/
export const TENANT_DERIVED_MODELS: readonly TenantDerivedModel[] = [
// analytics.prisma
{
model: "AnalyticsUniqueVisitor",
schema: "analytics.prisma",
tenantPaths: [["portal"], ["portalUser"]],
optionalTenantPaths: [
{ foreignKey: "portalId", path: ["portal"] },
{ foreignKey: "portalUserId", path: ["portalUser"] },
],
dependsOn: ["Portal", "PortalUser"],
},
{
model: "AnalyticsPageView",
schema: "analytics.prisma",
tenantPaths: [["uniqueVisitor", "portal"], ["uniqueVisitor", "portalUser"]],
optionalTenantPaths: [
{ foreignKey: "portalId", path: ["portal"] },
{ foreignKey: "portalUserId", path: ["portalUser"] },
],
dependsOn: ["AnalyticsUniqueVisitor", "Portal", "PortalUser"],
},
{
model: "AnalyticsEvent",
schema: "analytics.prisma",
tenantPaths: [["uniqueVisitor", "portal"], ["uniqueVisitor", "portalUser"]],
optionalTenantPaths: [
{ foreignKey: "portalId", path: ["portal"] },
{ foreignKey: "portalUserId", path: ["portalUser"] },
],
dependsOn: ["AnalyticsUniqueVisitor", "FeatureFlag", "Portal", "PortalUser"],
},
// core.prisma
{
model: "EventWebhookAttempt",
schema: "core.prisma",
tenantPaths: [["event"]],
dependsOn: ["Event"],
},
// email.prisma
{
model: "Email",
schema: "email.prisma",
tenantPaths: [["tenantInboundAddress"]],
dependsOn: ["TenantInboundAddress"],
},
{
model: "EmailRead",
schema: "email.prisma",
tenantPaths: [["email", "tenantInboundAddress"]],
dependsOn: ["Email"],
},
{
model: "EmailCc",
schema: "email.prisma",
tenantPaths: [["email", "tenantInboundAddress"]],
dependsOn: ["Email"],
},
{
model: "EmailAttachment",
schema: "email.prisma",
tenantPaths: [["email", "tenantInboundAddress"]],
dependsOn: ["Email"],
},
{
model: "OutboundEmailOpen",
schema: "email.prisma",
tenantPaths: [["outboundEmail"]],
dependsOn: ["OutboundEmail"],
},
{
model: "OutboundEmailClick",
schema: "email.prisma",
tenantPaths: [["outboundEmail"]],
dependsOn: ["OutboundEmail"],
},
// emailSequences.prisma
{
model: "EmailSequenceStepDelivery",
schema: "emailSequences.prisma",
tenantPaths: [["run"]],
dependsOn: ["EmailSequenceRun"],
},
// featureFlags.prisma
{
model: "FeatureFlagFilter",
schema: "featureFlags.prisma",
tenantPaths: [["featureFlag"]],
dependsOn: ["FeatureFlag"],
},
{
model: "FeatureFlagAudit",
schema: "featureFlags.prisma",
tenantPaths: [["flag"]],
dependsOn: ["FeatureFlag"],
},
// knowledgeBase.prisma. Category/article FKs default to RESTRICT, so the
// explicit order is required for both restore and reverse-order deletion.
{
model: "KnowledgeBaseCategory",
schema: "knowledgeBase.prisma",
tenantPaths: [["knowledgeBase"]],
dependsOn: ["KnowledgeBase"],
},
{
model: "KnowledgeBaseCategorySection",
schema: "knowledgeBase.prisma",
tenantPaths: [["category", "knowledgeBase"]],
dependsOn: ["KnowledgeBaseCategory"],
},
{
model: "KnowledgeBaseArticle",
schema: "knowledgeBase.prisma",
tenantPaths: [["knowledgeBase"]],
optionalTenantPaths: [
{ foreignKey: "categoryId", path: ["category", "knowledgeBase"] },
{ foreignKey: "sectionId", path: ["section", "category", "knowledgeBase"] },
],
dependsOn: ["KnowledgeBase", "KnowledgeBaseCategory", "KnowledgeBaseCategorySection"],
},
{
model: "KnowledgeBaseRelatedArticle",
schema: "knowledgeBase.prisma",
tenantPaths: [["article", "knowledgeBase"], ["relatedArticle", "knowledgeBase"]],
tenantPathMode: "all",
dependsOn: ["KnowledgeBaseArticle"],
},
{
model: "KnowledgeBaseViews",
schema: "knowledgeBase.prisma",
tenantPaths: [["knowledgeBase"]],
dependsOn: ["KnowledgeBase"],
},
{
model: "KnowledgeBaseArticleViews",
schema: "knowledgeBase.prisma",
tenantPaths: [["knowledgeBaseArticle", "knowledgeBase"]],
dependsOn: ["KnowledgeBaseArticle"],
cursor: {
fields: ["knowledgeBaseArticleId", "userAnalyticsId"],
compoundField: "knowledgeBaseArticleId_userAnalyticsId",
},
},
{
model: "KnowledgeBaseArticleUpvotes",
schema: "knowledgeBase.prisma",
tenantPaths: [["knowledgeBaseArticle", "knowledgeBase"]],
dependsOn: ["KnowledgeBaseArticle"],
cursor: {
fields: ["knowledgeBaseArticleId", "userAnalyticsId"],
compoundField: "knowledgeBaseArticleId_userAnalyticsId",
},
},
{
model: "KnowledgeBaseArticleDownvotes",
schema: "knowledgeBase.prisma",
tenantPaths: [["knowledgeBaseArticle", "knowledgeBase"]],
dependsOn: ["KnowledgeBaseArticle"],
cursor: {
fields: ["knowledgeBaseArticleId", "userAnalyticsId"],
compoundField: "knowledgeBaseArticleId_userAnalyticsId",
},
},
// onboarding.prisma
{
model: "OnboardingSessionAction",
schema: "onboarding.prisma",
tenantPaths: [["onboardingSession"]],
dependsOn: ["OnboardingSession"],
},
{
model: "OnboardingSessionFilterMatch",
schema: "onboarding.prisma",
tenantPaths: [["onboardingSession"]],
dependsOn: ["OnboardingSession"],
},
{
model: "OnboardingSessionStep",
schema: "onboarding.prisma",
tenantPaths: [["onboardingSession"]],
dependsOn: ["OnboardingSession"],
},
// permissions.prisma
{
model: "RolePermission",
schema: "permissions.prisma",
tenantPaths: [["role"]],
dependsOn: ["Role"],
},
{
model: "GroupUser",
schema: "permissions.prisma",
tenantPaths: [["group"]],
dependsOn: ["Group"],
},
// plugins.prisma
{
model: "PluginUserConfig",
schema: "plugins.prisma",
tenantPaths: [["plugin"]],
dependsOn: ["Plugin"],
},
// portals.prisma
{ model: "PortalPage", schema: "portals.prisma", tenantPaths: [["portal"]], dependsOn: ["Portal"] },
// subscriptions.prisma
{
model: "TenantSubscriptionProduct",
schema: "subscriptions.prisma",
tenantPaths: [["tenantSubscription"]],
dependsOn: ["TenantSubscription"],
// TenantProductAcquisition optionally links the granted product. Restore
// the derived entitlement row first whenever that link is populated.
restoreBefore: ["TenantProductAcquisition"],
},
{
model: "TenantSubscriptionProductPrice",
schema: "subscriptions.prisma",
tenantPaths: [["tenantSubscriptionProduct", "tenantSubscription"]],
dependsOn: ["TenantSubscriptionProduct"],
},
// workflows.prisma
{
model: "WorkflowBlock",
schema: "workflows.prisma",
tenantPaths: [["workflow"]],
dependsOn: ["Workflow"],
// WorkflowExecution.waitingBlockId uses the default RESTRICT action.
restoreBefore: ["WorkflowExecution"],
},
{
model: "WorkflowBlockConditionGroup",
schema: "workflows.prisma",
tenantPaths: [["workflowBlock", "workflow"]],
dependsOn: ["WorkflowBlock"],
},
{
model: "WorkflowBlockCondition",
schema: "workflows.prisma",
tenantPaths: [["workflowBlockConditionGroup", "workflowBlock", "workflow"]],
dependsOn: ["WorkflowBlockConditionGroup"],
},
{
model: "WorkflowBlockToBlock",
schema: "workflows.prisma",
tenantPaths: [["fromBlock", "workflow"], ["toBlock", "workflow"]],
tenantPathMode: "all",
dependsOn: ["WorkflowBlock"],
},
{
model: "WorkflowInputExample",
schema: "workflows.prisma",
tenantPaths: [["workflow"]],
dependsOn: ["Workflow"],
},
{
model: "WorkflowBlockExecution",
schema: "workflows.prisma",
tenantPaths: [["workflowExecution"]],
tenantOrGlobalPaths: [["workflowBlock", "workflow"]],
optionalTenantOrGlobalPaths: [
{ foreignKey: "fromWorkflowBlockId", path: ["fromWorkflowBlock", "workflow"] },
],
dependsOn: ["WorkflowBlock", "WorkflowExecution"],
},
];
export interface DirectTenantLifecycleModel extends TenantScopedModel {
readonly scope: "direct";
}
export interface DerivedTenantLifecycleModel extends TenantDerivedModel {
readonly scope: "derived-child";
}
export type TenantLifecycleModel = DirectTenantLifecycleModel | DerivedTenantLifecycleModel;
function buildTenantLifecycleModels(): readonly TenantLifecycleModel[] {
const direct: DirectTenantLifecycleModel[] = TENANT_SCOPED_MODELS.map((entry) => ({
...entry,
scope: "direct",
}));
const derived: DerivedTenantLifecycleModel[] = TENANT_DERIVED_MODELS.map((entry) => ({
...entry,
scope: "derived-child",
}));
const nodes: TenantLifecycleModel[] = [...direct, ...derived];
const index = new Map(nodes.map((entry, position) => [entry.model, position]));
if (index.size !== nodes.length) {
throw new Error("Tenant lifecycle registry contains duplicate model names.");
}
const outgoing = new Map<string, Set<string>>();
const indegree = new Map(nodes.map((entry) => [entry.model, 0]));
const addEdge = (parent: string, child: string): void => {
if (!index.has(parent) || !index.has(child)) {
throw new Error(`Tenant lifecycle dependency references an unknown model: ${parent} -> ${child}.`);
}
const children = outgoing.get(parent) ?? new Set<string>();
if (children.has(child)) return;
children.add(child);
outgoing.set(parent, children);
indegree.set(child, (indegree.get(child) ?? 0) + 1);
};
// Preserve the existing direct-model order while allowing a derived model
// to be inserted before a direct model that points back to it.
for (let i = 1; i < direct.length; i += 1) {
addEdge(direct[i - 1]!.model, direct[i]!.model);
}
for (const entry of derived) {
for (const dependency of entry.dependsOn) addEdge(dependency, entry.model);
for (const target of entry.restoreBefore ?? []) addEdge(entry.model, target);
}
const ready = nodes.filter((entry) => indegree.get(entry.model) === 0);
const ordered: TenantLifecycleModel[] = [];
while (ready.length > 0) {
ready.sort((a, b) => index.get(a.model)! - index.get(b.model)!);
const current = ready.shift()!;
ordered.push(current);
for (const child of outgoing.get(current.model) ?? []) {
const next = (indegree.get(child) ?? 0) - 1;
indegree.set(child, next);
if (next === 0) ready.push(nodes[index.get(child)!]!);
}
}
if (ordered.length !== nodes.length) {
const blocked = nodes.filter((entry) => !ordered.includes(entry)).map((entry) => entry.model);
throw new Error(`Tenant lifecycle registry contains a dependency cycle: ${blocked.join(", ")}.`);
}
return ordered;
}
/** Parents-first order for snapshot and restore; reverse it for hard-delete. */
export const TENANT_LIFECYCLE_MODELS: readonly TenantLifecycleModel[] = buildTenantLifecycleModels();
const DERIVED_BY_MODEL = new Map(TENANT_DERIVED_MODELS.map((entry) => [entry.model, entry]));
export function isTenantDerivedModel(model: string): boolean {
return DERIVED_BY_MODEL.has(model);
}
export function tenantWhereForLifecycleModel(
entry: TenantLifecycleModel,
tenantId: string,
): Record<string, unknown> {
if (entry.scope === "direct") return { [entry.tenantField]: tenantId };
const filters = entry.tenantPaths.map((path) => relationPathWhere(path, tenantId));
const primary =
filters.length === 1
? filters[0]!
: entry.tenantPathMode === "all"
? { AND: filters }
: { OR: filters };
const optional = (entry.optionalTenantPaths ?? []).map(({ foreignKey, path }) => ({
OR: [
{ [foreignKey]: null },
relationPathWhere(path, tenantId),
],
}));
const tenantOrGlobal = (entry.tenantOrGlobalPaths ?? []).map((path) => ({
OR: [relationPathWhere(path, tenantId), relationPathWhere(path, null)],
}));
const optionalTenantOrGlobal = (entry.optionalTenantOrGlobalPaths ?? []).map(
({ foreignKey, path }) => ({
OR: [
{ [foreignKey]: null },
relationPathWhere(path, tenantId),
relationPathWhere(path, null),
],
}),
);
const guards = [...optional, ...tenantOrGlobal, ...optionalTenantOrGlobal];
return guards.length === 0 ? primary : { AND: [primary, ...guards] };
}
function relationPathWhere(path: readonly string[], tenantId: string | null): Record<string, unknown> {
if (path.length === 0) throw new Error("Tenant relation path must not be empty.");
return path.reduceRight<Record<string, unknown>>(
(nested, relation) => ({ [relation]: nested }),
{ tenantId },
);
}
export interface TenantLifecycleGlobalReferencedModel extends GlobalReferencedModel {
/** Extra predicate for hybrid models where only the global (tenantId NULL) row is copied. */
readonly where?: Readonly<Record<string, unknown>>;
/** Do not fetch an id already present in this model's tenant JSONL slice. */
readonly excludeIdsPresentInTenantSlice?: boolean;
/** Self-referential FK columns that require parent-first row ordering. */
readonly selfParentFields?: readonly string[];
/** Functional child rows that must accompany a referenced global parent. */
readonly children?: ReadonlyArray<{
readonly model: string;
readonly foreignKey: string;
}>;
}
/**
* Global and hybrid rows referenced by the complete tenant lifecycle slice.
* These are deliberately separate from the direct tenant registry: hybrid
* rows keep tenantId=NULL and derived globals have no tenantId at all.
*/
export const DERIVED_GLOBAL_REFERENCED_MODELS: readonly TenantLifecycleGlobalReferencedModel[] = [
{
model: "User",
schema: "accounts.prisma",
referencedBy: [
{ model: "AnalyticsUniqueVisitor", fkColumn: "userId" },
{ model: "EmailRead", fkColumn: "userId" },
{ model: "GroupUser", fkColumn: "userId" },
{ model: "KnowledgeBaseArticle", fkColumn: "createdByUserId" },
],
},
{
model: "Role",
schema: "permissions.prisma",
where: { tenantId: null },
excludeIdsPresentInTenantSlice: true,
children: [{ model: "RolePermission", foreignKey: "roleId" }],
referencedBy: [{ model: "UserRole", fkColumn: "roleId" }],
},
{
model: "Permission",
schema: "permissions.prisma",
referencedBy: [{ model: "RolePermission", fkColumn: "permissionId" }],
},
{
model: "RolePermission",
schema: "permissions.prisma",
referencedBy: [],
},
{
model: "Workflow",
schema: "workflows.prisma",
where: { tenantId: null },
excludeIdsPresentInTenantSlice: true,
children: [
{ model: "WorkflowBlock", foreignKey: "workflowId" },
{ model: "WorkflowInputExample", foreignKey: "workflowId" },
],
referencedBy: [
{ model: "WorkflowExecution", fkColumn: "workflowId" },
// A referenced global block can belong to a different global workflow.
{ model: "WorkflowBlock", fkColumn: "workflowId" },
],
},
{
model: "WorkflowBlock",
schema: "workflows.prisma",
where: { workflow: { tenantId: null } },
excludeIdsPresentInTenantSlice: true,
children: [
{ model: "WorkflowBlockConditionGroup", foreignKey: "workflowBlockId" },
{ model: "WorkflowBlockToBlock", foreignKey: "fromBlockId" },
],
referencedBy: [
{ model: "WorkflowExecution", fkColumn: "waitingBlockId" },
{ model: "WorkflowBlockExecution", fkColumn: "workflowBlockId" },
{ model: "WorkflowBlockExecution", fkColumn: "fromWorkflowBlockId" },
{ model: "WorkflowBlockToBlock", fkColumn: "fromBlockId" },
{ model: "WorkflowBlockToBlock", fkColumn: "toBlockId" },
],
},
{
model: "WorkflowBlockConditionGroup",
schema: "workflows.prisma",
children: [
{ model: "WorkflowBlockCondition", foreignKey: "workflowBlockConditionGroupId" },
],
referencedBy: [],
},
{
model: "WorkflowBlockCondition",
schema: "workflows.prisma",
referencedBy: [],
},
{
model: "WorkflowBlockToBlock",
schema: "workflows.prisma",
referencedBy: [],
},
{
model: "WorkflowInputExample",
schema: "workflows.prisma",
referencedBy: [],
},
{
model: "EmailSequence",
schema: "emailSequences.prisma",
where: { tenantId: null },
excludeIdsPresentInTenantSlice: true,
referencedBy: [{ model: "EmailSequenceRun", fkColumn: "sequenceId" }],
},
{
model: "FeatureFlag",
schema: "featureFlags.prisma",
where: { tenantId: null },
excludeIdsPresentInTenantSlice: true,
selfParentFields: ["parentFlagId"],
children: [{ model: "FeatureFlagFilter", foreignKey: "featureFlagId" }],
referencedBy: [
{ model: "AnalyticsEvent", fkColumn: "featureFlagId" },
// Follow the complete global dependency chain for an empty target.
{ model: "FeatureFlag", fkColumn: "parentFlagId" },
],
},
{
model: "FeatureFlagFilter",
schema: "featureFlags.prisma",
referencedBy: [],
},
];
function mergeGlobalReferences(): readonly TenantLifecycleGlobalReferencedModel[] {
const byModel = new Map<
string,
Omit<TenantLifecycleGlobalReferencedModel, "referencedBy"> & {
referencedBy: Array<{ model: string; fkColumn: string }>;
}
>();
for (const entry of [...GLOBAL_REFERENCED_MODELS, ...DERIVED_GLOBAL_REFERENCED_MODELS]) {
const current = byModel.get(entry.model) ?? { ...entry, referencedBy: [] };
current.referencedBy.push(...entry.referencedBy);
byModel.set(entry.model, current);
}
return Array.from(byModel.values());
}
export const TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS: readonly TenantLifecycleGlobalReferencedModel[] =
mergeGlobalReferences();
@@ -6,15 +6,32 @@ import { collectAndWriteGlobals, type GlobalsPrismaRunner } from "./globals-runn
function makeRunner(rows: Record<string, Record<string, unknown>[]>): {
runner: GlobalsPrismaRunner;
calls: Array<{ model: string; ids: readonly string[] }>;
calls: Array<{
model: string;
ids: readonly string[];
foreignKey?: string;
where?: Readonly<Record<string, unknown>>;
}>;
} {
const calls: Array<{ model: string; ids: readonly string[] }> = [];
const calls: Array<{
model: string;
ids: readonly string[];
foreignKey?: string;
where?: Readonly<Record<string, unknown>>;
}> = [];
const runner: GlobalsPrismaRunner = {
async findManyByIds(modelName, ids) {
calls.push({ model: modelName, ids });
async findManyByIds(modelName, ids, where) {
calls.push(where ? { model: modelName, ids, where } : { model: modelName, ids });
const table = rows[modelName] ?? [];
return table.filter((r) => typeof r.id === "string" && ids.includes(r.id as string));
},
async findManyByForeignKeys(modelName, foreignKey, ids, where) {
calls.push({ model: modelName, ids, foreignKey, ...(where ? { where } : {}) });
const table = rows[modelName] ?? [];
return table.filter(
(row) => typeof row[foreignKey] === "string" && ids.includes(row[foreignKey] as string),
);
},
};
return { runner, calls };
}
@@ -48,7 +65,22 @@ describe("collectAndWriteGlobals", () => {
ctx: { salt: "deadbeef", profileName: "full-anonymized" },
});
expect(result.entries).toHaveLength(2); // User + McpOAuthClient today
expect(result.entries.map((entry) => entry.model)).toEqual([
"User",
"McpOAuthClient",
"Role",
"Permission",
"RolePermission",
"Workflow",
"WorkflowBlock",
"WorkflowBlockConditionGroup",
"WorkflowBlockCondition",
"WorkflowBlockToBlock",
"WorkflowInputExample",
"EmailSequence",
"FeatureFlag",
"FeatureFlagFilter",
]);
const userEntry = result.entries.find((e) => e.model === "User");
expect(userEntry).toBeDefined();
expect(userEntry?.rowCount).toBe(0);
@@ -142,6 +174,176 @@ describe("collectAndWriteGlobals", () => {
expect(result.entries.find((e) => e.model === "User")?.rowCount).toBe(4);
});
it("collects User ids referenced only by FK-derived tenant children", async () => {
await writeFile(
join(postgresDir, "EmailRead.jsonl"),
`${JSON.stringify({ id: "read_1", emailId: "email_1", userId: "u_email" })}\n`,
);
await writeFile(
join(postgresDir, "KnowledgeBaseArticle.jsonl"),
`${JSON.stringify({ id: "article_1", knowledgeBaseId: "kb_1", createdByUserId: "u_kb" })}\n`,
);
const { runner, calls } = makeRunner({
User: [
{ id: "u_email", email: "mail@x.org", firstName: "Mail", lastName: "User" },
{ id: "u_kb", email: "kb@x.org", firstName: "KB", lastName: "User" },
],
});
const result = await collectAndWriteGlobals({
postgresDir,
globalsDir,
prisma: runner,
profile: "full-anonymized",
ctx: { salt: "x", profileName: "full-anonymized" },
});
expect(calls).toHaveLength(1);
expect(new Set(calls[0]?.ids)).toEqual(new Set(["u_email", "u_kb"]));
expect(result.entries.find((entry) => entry.model === "User")?.rowCount).toBe(2);
});
it("closes hybrid global references and writes parent rows in restore-safe order", async () => {
await writeFile(
join(postgresDir, "Workflow.jsonl"),
`${JSON.stringify({ id: "wf_tenant", tenantId: "t1", createdByUserId: "u_tenant" })}\n`,
);
await writeFile(
join(postgresDir, "WorkflowExecution.jsonl"),
[
{ id: "run_global", tenantId: "t1", workflowId: "wf_global", waitingBlockId: "block_global", createdByUserId: "u_exec" },
{ id: "run_tenant", tenantId: "t1", workflowId: "wf_tenant" },
].map((row) => JSON.stringify(row)).join("\n") + "\n",
);
await writeFile(
join(postgresDir, "WorkflowBlock.jsonl"),
`${JSON.stringify({ id: "block_tenant", workflowId: "wf_tenant" })}\n`,
);
await writeFile(
join(postgresDir, "WorkflowBlockExecution.jsonl"),
`${JSON.stringify({ id: "block_run", workflowBlockId: "block_global", fromWorkflowBlockId: "block_other" })}\n`,
);
await writeFile(
join(postgresDir, "Role.jsonl"),
`${JSON.stringify({ id: "role_tenant", tenantId: "t1" })}\n`,
);
await writeFile(
join(postgresDir, "UserRole.jsonl"),
[
{ id: "user_role_global", tenantId: "t1", roleId: "role_global" },
{ id: "user_role_tenant", tenantId: "t1", roleId: "role_tenant" },
].map((row) => JSON.stringify(row)).join("\n") + "\n",
);
await writeFile(
join(postgresDir, "EmailSequence.jsonl"),
`${JSON.stringify({ id: "sequence_tenant", tenantId: "t1" })}\n`,
);
await writeFile(
join(postgresDir, "EmailSequenceRun.jsonl"),
[
{ id: "sequence_run_global", sequenceId: "sequence_global", tenantId: "t1" },
{ id: "sequence_run_tenant", sequenceId: "sequence_tenant", tenantId: "t1" },
].map((row) => JSON.stringify(row)).join("\n") + "\n",
);
await writeFile(
join(postgresDir, "FeatureFlag.jsonl"),
`${JSON.stringify({ id: "flag_tenant", tenantId: "t1" })}\n`,
);
await writeFile(
join(postgresDir, "AnalyticsEvent.jsonl"),
`${JSON.stringify({ id: "event_1", featureFlagId: "flag_child" })}\n`,
);
const { runner, calls } = makeRunner({
User: [
{ id: "u_tenant", email: "tenant@example.org" },
{ id: "u_exec", email: "exec@example.org" },
{ id: "u_workflow", email: "workflow@example.org" },
],
Workflow: [
{ id: "wf_tenant", tenantId: "t1" },
{ id: "wf_global", tenantId: null, createdByUserId: "u_workflow" },
{ id: "wf_other", tenantId: null },
],
WorkflowBlock: [
{ id: "block_tenant", workflowId: "wf_tenant" },
{ id: "block_global", workflowId: "wf_global" },
{ id: "block_other", workflowId: "wf_other" },
],
WorkflowBlockConditionGroup: [
{ id: "condition_group", workflowBlockId: "block_global", index: 0, type: "AND" },
],
WorkflowBlockCondition: [
{
id: "condition_1",
workflowBlockConditionGroupId: "condition_group",
index: 0,
variable: "status",
operator: "equals",
value: "open",
},
],
WorkflowBlockToBlock: [
{ id: "edge_1", fromBlockId: "block_global", toBlockId: "block_other" },
],
WorkflowInputExample: [
{ id: "input_1", workflowId: "wf_global", title: "Example", input: "{}" },
],
Role: [
{ id: "role_tenant", tenantId: "t1" },
{ id: "role_global", tenantId: null, name: "Member" },
],
RolePermission: [
{ id: "role_permission_1", roleId: "role_global", permissionId: "permission_1" },
],
Permission: [{ id: "permission_1", name: "crm.read" }],
EmailSequence: [
{ id: "sequence_tenant", tenantId: "t1" },
{ id: "sequence_global", tenantId: null },
],
FeatureFlag: [
{ id: "flag_child", tenantId: null, parentFlagId: "flag_parent" },
{ id: "flag_parent", tenantId: null, parentFlagId: null },
],
FeatureFlagFilter: [
{ id: "filter_1", featureFlagId: "flag_child", type: "percentage", value: "50" },
],
});
const result = await collectAndWriteGlobals({
postgresDir,
globalsDir,
prisma: runner,
profile: "none",
ctx: { salt: "x", profileName: "none" },
});
expect(
calls.find((call) => call.model === "Workflow" && call.ids.includes("wf_global"))?.where,
).toEqual({ tenantId: null });
expect(calls.some((call) => call.model === "Workflow" && call.ids.includes("wf_tenant"))).toBe(false);
expect(calls.some((call) => call.model === "EmailSequence" && call.ids.includes("sequence_tenant"))).toBe(false);
expect(result.entries.find((entry) => entry.model === "Workflow")?.rowCount).toBe(2);
expect(result.entries.find((entry) => entry.model === "WorkflowBlock")?.rowCount).toBe(2);
expect(
result.entries.find((entry) => entry.model === "WorkflowBlockCondition")?.rowCount,
).toBe(1);
expect(result.entries.find((entry) => entry.model === "WorkflowBlockToBlock")?.rowCount).toBe(1);
expect(result.entries.find((entry) => entry.model === "WorkflowInputExample")?.rowCount).toBe(1);
expect(result.entries.find((entry) => entry.model === "Role")?.rowCount).toBe(1);
expect(result.entries.find((entry) => entry.model === "Permission")?.rowCount).toBe(1);
expect(result.entries.find((entry) => entry.model === "RolePermission")?.rowCount).toBe(1);
expect(result.entries.find((entry) => entry.model === "EmailSequence")?.rowCount).toBe(1);
expect(result.entries.find((entry) => entry.model === "FeatureFlag")?.rowCount).toBe(2);
expect(result.entries.find((entry) => entry.model === "FeatureFlagFilter")?.rowCount).toBe(1);
const flags = (await readFile(join(globalsDir, "FeatureFlag.jsonl"), "utf8"))
.trim()
.split("\n")
.map((line) => JSON.parse(line) as { id: string });
expect(flags.map((row) => row.id)).toEqual(["flag_parent", "flag_child"]);
const users = await readFile(join(globalsDir, "User.jsonl"), "utf8");
expect(users).toContain("u_workflow");
});
it("warns and continues when a referenced id is missing from the source DB", async () => {
await writeFile(
join(postgresDir, "TenantUser.jsonl"),
@@ -13,13 +13,10 @@
*
* Design notes
* ------------
* - Two-pass against the source: pass one (`findManyByTenant`) is the
* existing tenant-scoped extractor; pass two streams those rows
* through `collectGlobalIds()` to build the FK-id sets, then issues
* chunked `findManyByIds()` calls against the Prisma client. We do
* NOT re-issue the tenant queries — we read the JSONL files we just
* wrote so the pass-two memory footprint is bounded by chunk size
* regardless of tenant size.
* - Two-pass against the source: pass one is the existing tenant lifecycle
* extractor; pass two streams those JSONL files to seed referenced ids,
* then follows global-to-global references to closure. This includes
* hybrid NULL-tenant parents such as system workflows and sequences.
* - Anonymization is applied to the global rows using the same
* per-snapshot salt as the tenant slice. Determinism: if two tenant
* rows reference the same user, both restored rows still see the
@@ -45,7 +42,7 @@ import {
type ProfileName,
} from "./anonymize.js";
import { snapshotReplacer } from "./json-codec.js";
import { GLOBAL_REFERENCED_MODELS } from "./models.js";
import { TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS } from "./derived-models.js";
import type { TenantManifestGlobalsEntry } from "./manifest.js";
/**
@@ -59,7 +56,17 @@ export interface GlobalsPrismaRunner {
* pages the ids in chunks; this method must not perform its own
* pagination on top.
*/
findManyByIds(modelName: string, ids: readonly string[]): Promise<Record<string, unknown>[]>;
findManyByIds(
modelName: string,
ids: readonly string[],
where?: Readonly<Record<string, unknown>>,
): Promise<Record<string, unknown>[]>;
findManyByForeignKeys(
modelName: string,
foreignKey: string,
ids: readonly string[],
where?: Readonly<Record<string, unknown>>,
): Promise<Record<string, unknown>[]>;
}
/**
@@ -112,6 +119,67 @@ export interface CollectGlobalsResult {
readonly missingByModel: Readonly<Record<string, number>>;
}
function collectFkIdsFromRows(
rows: Iterable<Readonly<Record<string, unknown>>>,
fkColumns: readonly string[],
): Set<string> {
const ids = new Set<string>();
for (const row of rows) {
for (const column of fkColumns) {
const value = row[column];
if (typeof value === "string" && value.length > 0) ids.add(value);
}
}
return ids;
}
function orderSelfReferencedRows(
model: string,
rows: readonly Record<string, unknown>[],
parentFields: readonly string[],
): readonly Record<string, unknown>[] {
if (parentFields.length === 0 || rows.length < 2) return rows;
const rowById = new Map<string, Record<string, unknown>>();
const sourcePosition = new Map<string, number>();
rows.forEach((row, position) => {
const id = row["id"];
if (typeof id !== "string" || id.length === 0) {
throw new Error(`Globals: ${model} row has no string id.`);
}
rowById.set(id, row);
sourcePosition.set(id, position);
});
const children = new Map<string, Set<string>>();
const indegree = new Map(Array.from(rowById.keys(), (id) => [id, 0]));
for (const [childId, row] of rowById) {
for (const field of parentFields) {
const parentId = row[field];
if (typeof parentId !== "string" || parentId === childId || !rowById.has(parentId)) continue;
const descendants = children.get(parentId) ?? new Set<string>();
if (descendants.has(childId)) continue;
descendants.add(childId);
children.set(parentId, descendants);
indegree.set(childId, (indegree.get(childId) ?? 0) + 1);
}
}
const ready = Array.from(rowById.keys()).filter((id) => indegree.get(id) === 0);
const ordered: Record<string, unknown>[] = [];
while (ready.length > 0) {
ready.sort((a, b) => sourcePosition.get(a)! - sourcePosition.get(b)!);
const id = ready.shift()!;
ordered.push(rowById.get(id)!);
for (const childId of children.get(id) ?? []) {
const next = (indegree.get(childId) ?? 0) - 1;
indegree.set(childId, next);
if (next === 0) ready.push(childId);
}
}
if (ordered.length !== rows.length) {
throw new Error(`Globals: ${model} contains a self-reference cycle and cannot be restored FK-safely.`);
}
return ordered;
}
/**
* Walk every tenant-scoped JSONL file in `postgresDir`, harvest FK ids
* for each global model, fetch the rows from Prisma in chunks, run the
@@ -127,10 +195,47 @@ export async function collectAndWriteGlobals(
const entries: TenantManifestGlobalsEntry[] = [];
const missingByModel: Record<string, number> = {};
for (const global of GLOBAL_REFERENCED_MODELS) {
// 1. Build the union of referenced ids across every source model.
const referencedIds = new Set<string>();
// Group columns by source model so we read each JSONL file at most once.
const globals = TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS;
const referencedByModel = new Map(globals.map((entry) => [entry.model, new Set<string>()]));
const excludedByModel = new Map(globals.map((entry) => [entry.model, new Set<string>()]));
const rowsByModel = new Map(
globals.map((entry) => [entry.model, new Map<string, Record<string, unknown>>()]),
);
const attemptedByModel = new Map(globals.map((entry) => [entry.model, new Set<string>()]));
const expandedChildrenByModel = new Map(globals.map((entry) => [entry.model, new Set<string>()]));
const globalByModel = new Map(globals.map((entry) => [entry.model, entry]));
const storeAndDiscover = (
model: string,
rows: readonly Record<string, unknown>[],
): void => {
const targetRows = rowsByModel.get(model);
if (!targetRows) throw new Error(`Globals: child model ${model} is not registered.`);
const excluded = excludedByModel.get(model)!;
for (const row of rows) {
const id = row["id"];
if (typeof id !== "string" || id.length === 0) {
throw new Error(`Globals: ${model} lookup returned a row without a string id.`);
}
if (!excluded.has(id)) {
targetRows.set(id, row);
attemptedByModel.get(model)!.add(id);
}
}
for (const target of globals) {
const columns = target.referencedBy
.filter((ref) => ref.model === model)
.map((ref) => ref.fkColumn);
if (columns.length === 0) continue;
const discovered = collectFkIdsFromRows(rows, columns);
const targetIds = referencedByModel.get(target.model)!;
for (const id of discovered) targetIds.add(id);
}
};
// 1. Seed referenced ids from the already-written tenant lifecycle JSONL.
for (const global of globals) {
const referencedIds = referencedByModel.get(global.model)!;
const columnsBySource = new Map<string, string[]>();
for (const ref of global.referencedBy) {
const arr = columnsBySource.get(ref.model) ?? [];
@@ -142,40 +247,90 @@ export async function collectAndWriteGlobals(
const ids = await collectFkIdsFromJsonl(filePath, cols);
for (const id of ids) referencedIds.add(id);
}
if (global.excludeIdsPresentInTenantSlice) {
const localIds = await collectFkIdsFromJsonl(
join(opts.postgresDir, `${global.model}.jsonl`),
["id"],
);
const excluded = excludedByModel.get(global.model)!;
for (const id of localIds) excluded.add(id);
}
}
// 2. Fetch the rows in chunks and stream-write the JSONL.
// 2. Resolve the global reference graph to closure. Rows fetched for one
// global can introduce ids for another global (Workflow -> User) or itself
// (FeatureFlag -> parent FeatureFlag).
let madeProgress = true;
while (madeProgress) {
madeProgress = false;
for (const global of globals) {
const referenced = referencedByModel.get(global.model)!;
const excluded = excludedByModel.get(global.model)!;
const attempted = attemptedByModel.get(global.model)!;
const ids = Array.from(referenced).filter((id) => !excluded.has(id) && !attempted.has(id));
if (ids.length > 0) {
madeProgress = true;
for (const id of ids) attempted.add(id);
logger?.info(`Globals: ${global.model} → ${ids.length} new referenced ids`);
for (let i = 0; i < ids.length; i += chunkSize) {
const chunk = ids.slice(i, i + chunkSize);
const rows = await opts.prisma.findManyByIds(global.model, chunk, global.where);
storeAndDiscover(global.model, rows);
}
}
const expanded = expandedChildrenByModel.get(global.model)!;
const parentIds = Array.from(rowsByModel.get(global.model)!.keys()).filter(
(id) => !expanded.has(id),
);
if (parentIds.length === 0 || (global.children ?? []).length === 0) continue;
madeProgress = true;
for (const id of parentIds) expanded.add(id);
for (const child of global.children ?? []) {
const childConfig = globalByModel.get(child.model);
if (!childConfig) {
throw new Error(`Globals: ${global.model} child ${child.model} is not registered.`);
}
for (let i = 0; i < parentIds.length; i += chunkSize) {
const parentChunk = parentIds.slice(i, i + chunkSize);
const rows = await opts.prisma.findManyByForeignKeys(
child.model,
child.foreignKey,
parentChunk,
childConfig.where,
);
storeAndDiscover(child.model, rows);
}
}
}
}
// 3. Write in declared, FK-safe restore order after closure is complete.
for (const global of globals) {
const outPath = join(opts.globalsDir, `${global.model}.jsonl`);
const hash = createHash("sha256");
const writeStream = createWriteStream(outPath, { encoding: "utf8" });
let rowCount = 0;
let missing = 0;
const idArr = Array.from(referencedIds);
if (idArr.length > 0) {
logger?.info(`Globals: ${global.model} → ${idArr.length} referenced ids`);
}
for (let i = 0; i < idArr.length; i += chunkSize) {
const chunk = idArr.slice(i, i + chunkSize);
const rows = await opts.prisma.findManyByIds(global.model, chunk);
const foundIds = new Set<string>();
for (const row of rows) {
const id = row["id"];
if (typeof id === "string") foundIds.add(id);
const anonymized = anonymizeRow(profile, global.model, row, opts.ctx);
const line = `${JSON.stringify(anonymized, snapshotReplacer)}\n`;
hash.update(line);
rowCount += 1;
if (!writeStream.write(line)) {
await new Promise<void>((resolve) => writeStream.once("drain", () => resolve()));
}
}
for (const requested of chunk) {
if (!foundIds.has(requested)) missing += 1;
const fetched = rowsByModel.get(global.model)!;
const orderedRows = orderSelfReferencedRows(
global.model,
Array.from(fetched.values()),
global.selfParentFields ?? [],
);
for (const row of orderedRows) {
const anonymized = anonymizeRow(profile, global.model, row, opts.ctx);
const line = `${JSON.stringify(anonymized, snapshotReplacer)}\n`;
hash.update(line);
rowCount += 1;
if (!writeStream.write(line)) {
await new Promise<void>((resolve) => writeStream.once("drain", () => resolve()));
}
}
await new Promise<void>((resolve, reject) => {
writeStream.end((err: Error | null | undefined) => (err ? reject(err) : resolve()));
});
const missing = attemptedByModel.get(global.model)!.size - fetched.size;
if (missing > 0) {
logger?.warn(
`Globals: ${global.model} had ${missing} referenced id(s) with no source row (dangling FK). Continuing.`,
@@ -11,6 +11,10 @@ import {
isTenantScopedModel,
tenantScopedModelNames,
} from "./models.js";
import {
TENANT_DERIVED_MODELS,
TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS,
} from "./derived-models.js";
const here = dirname(fileURLToPath(import.meta.url));
const repoRoot = join(here, "..", "..", "..", "..", "..");
@@ -72,6 +76,13 @@ describe("TENANT_SCOPED_MODELS", () => {
it("tenantScopedModelNames returns the list in declared order", () => {
expect(tenantScopedModelNames()).toEqual(TENANT_SCOPED_MODELS.map((m) => m.model));
});
it("restores projects before project-linked team chats", () => {
const names = tenantScopedModelNames();
expect(names.indexOf("Projekt")).toBeLessThan(names.indexOf("TeamChat"));
expect(names.indexOf("TeamChat")).toBeLessThan(names.indexOf("TeamChatGroupSource"));
expect(names.indexOf("TeamChat")).toBeLessThan(names.indexOf("TeamChatEvent"));
});
});
interface RelationRef {
@@ -122,14 +133,17 @@ function collectTenantScopedFkRelations(): RelationRef[] {
describe("GLOBAL_REFERENCED_MODELS + PLATFORM_CATALOG_GLOBALS coverage", () => {
const schemaModels = listSchemaModels();
const tenantScopedNames = new Set(TENANT_SCOPED_MODELS.map((m) => m.model));
const globalNames = new Set(GLOBAL_REFERENCED_MODELS.map((m) => m.model));
const derivedNames = new Set(TENANT_DERIVED_MODELS.map((m) => m.model));
const directGlobalNames = new Set(GLOBAL_REFERENCED_MODELS.map((m) => m.model));
const globalNames = new Set(TENANT_LIFECYCLE_GLOBAL_REFERENCED_MODELS.map((m) => m.model));
const platformNames = new Set(PLATFORM_CATALOG_GLOBALS);
it("every tenant-scoped FK relation targets a tenant-scoped model, a snapshot-global, or a platform-catalog global", () => {
it("every tenant-scoped FK relation targets a lifecycle model, a snapshot-global, or a platform-catalog global", () => {
const relations = collectTenantScopedFkRelations();
const uncategorized: RelationRef[] = [];
for (const rel of relations) {
if (tenantScopedNames.has(rel.targetModel)) continue;
if (derivedNames.has(rel.targetModel)) continue;
if (globalNames.has(rel.targetModel)) continue;
if (platformNames.has(rel.targetModel)) continue;
// `Tenant` itself is the snapshot root — restore creates the target
@@ -175,6 +189,26 @@ describe("GLOBAL_REFERENCED_MODELS + PLATFORM_CATALOG_GLOBALS coverage", () => {
expect(violations).toEqual([]);
});
it("collects every direct tenant FK that targets a snapshot-global model", () => {
const declared = new Set(
GLOBAL_REFERENCED_MODELS.flatMap((global) =>
global.referencedBy.map((ref) => `${ref.model}.${ref.fkColumn}->${global.model}`),
),
);
const missing = collectTenantScopedFkRelations()
.filter((relation) => directGlobalNames.has(relation.targetModel))
.filter(
(relation) =>
!declared.has(`${relation.sourceModel}.${relation.fkColumn}->${relation.targetModel}`),
);
expect(
missing,
`snapshot-global FKs missing from referencedBy: ${missing
.map((relation) => `${relation.sourceModel}.${relation.fkColumn}->${relation.targetModel}`)
.join(", ")}`,
).toEqual([]);
});
it("isGlobalSnapshotModel + globalSnapshotModelNames agree with GLOBAL_REFERENCED_MODELS", () => {
for (const g of GLOBAL_REFERENCED_MODELS) {
expect(isGlobalSnapshotModel(g.model)).toBe(true);
@@ -25,7 +25,6 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
// accounts.prisma
{ model: "TenantUser", tenantField: "tenantId", schema: "accounts.prisma" },
{ model: "TenantUserInvitation", tenantField: "tenantId", schema: "accounts.prisma" },
{ model: "TenantIpAddress", tenantField: "tenantId", schema: "accounts.prisma" },
{ model: "WorkspaceAuthProvider", tenantField: "tenantId", schema: "accounts.prisma" },
{ model: "ImpersonationAudit", tenantField: "tenantId", schema: "accounts.prisma" },
@@ -35,7 +34,10 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "UserRole", tenantField: "tenantId", schema: "permissions.prisma" },
// core.prisma
{ model: "IdempotencyKey", tenantField: "tenantId", schema: "core.prisma" },
{ model: "ApiKey", tenantField: "tenantId", schema: "core.prisma" },
// TenantIpAddress optionally references ApiKey across schema files.
{ model: "TenantIpAddress", tenantField: "tenantId", schema: "accounts.prisma" },
{ model: "ApiKeyLog", tenantField: "tenantId", schema: "core.prisma" },
{ model: "AuditEvent", tenantField: "tenantId", schema: "core.prisma" },
{ model: "Event", tenantField: "tenantId", schema: "core.prisma" },
@@ -43,6 +45,13 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "MetricLog", tenantField: "tenantId", schema: "core.prisma" },
{ model: "Widget", tenantField: "tenantId", schema: "core.prisma" },
// auditRetention.prisma — append-only retention anchors and O(1) heads.
// No database relations; checkpoint rows precede their lookup head in
// snapshots so future FK hardening remains restore-safe.
{ model: "AuditChainCheckpoint", tenantField: "tenantId", schema: "auditRetention.prisma" },
{ model: "AuditChainHead", tenantField: "tenantId", schema: "auditRetention.prisma" },
{ model: "AuditChainCheckpointHead", tenantField: "tenantId", schema: "auditRetention.prisma" },
// publicApi.prisma (VR-P22b) — incoming endpoint before ingestion logs,
// outgoing subscription before delivery logs (FK subscriptionId, Cascade).
{ model: "PublicIncomingWebhookEndpoint", tenantField: "tenantId", schema: "publicApi.prisma" },
@@ -51,8 +60,10 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "PublicWebhookDeliveryLog", tenantField: "tenantId", schema: "publicApi.prisma" },
// subscriptions.prisma
{ model: "CheckoutSessionStatus", tenantField: "tenantId", schema: "subscriptions.prisma" },
{ model: "TenantSubscription", tenantField: "tenantId", schema: "subscriptions.prisma" },
{ model: "TenantSubscriptionUsageRecord", tenantField: "tenantId", schema: "subscriptions.prisma" },
{ model: "TenantProductAcquisition", tenantField: "tenantId", schema: "subscriptions.prisma" },
{ model: "TenantFeatureOverride", tenantField: "tenantId", schema: "subscriptions.prisma" },
{ model: "TenantProductConfiguration", tenantField: "tenantId", schema: "subscriptions.prisma" },
{ model: "Credit", tenantField: "tenantId", schema: "subscriptions.prisma" },
@@ -60,6 +71,9 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
// email.prisma
{ model: "EmailSender", tenantField: "tenantId", schema: "email.prisma" },
{ model: "TenantInboundAddress", tenantField: "tenantId", schema: "email.prisma" },
// Campaign optionally references RecipientSegment, so the segment must be
// restored first even though the remaining marketing models follow later.
{ model: "RecipientSegment", tenantField: "tenantId", schema: "email.prisma" },
{ model: "Campaign", tenantField: "tenantId", schema: "email.prisma" },
{ model: "OutboundEmail", tenantField: "tenantId", schema: "email.prisma" },
// AK-P14a — email foundation (sending domain, suppression, templates).
@@ -71,7 +85,6 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
// Cascade); CampaignVariant references Campaign (listed above). kontaktId /
// campaignId on Consent/Unsubscribe are BARE scalars (no @relation), so they
// are NOT collected as globals.
{ model: "RecipientSegment", tenantField: "tenantId", schema: "email.prisma" },
{ model: "SegmentSnapshotMember", tenantField: "tenantId", schema: "email.prisma" },
{ model: "CampaignVariant", tenantField: "tenantId", schema: "email.prisma" },
{ model: "KontaktMarketingConsent", tenantField: "tenantId", schema: "email.prisma" },
@@ -97,12 +110,26 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "AppSyncRun", tenantField: "tenantId", schema: "appsEngine.prisma" },
{ model: "AppSyncRunLog", tenantField: "tenantId", schema: "appsEngine.prisma" },
{ model: "AppSyncItem", tenantField: "tenantId", schema: "appsEngine.prisma" },
{ model: "AppEntityBinding", tenantField: "tenantId", schema: "appsEngine.prisma" },
// kwp.prisma (VR-P32b/VR-P32d) — durable contract/capability state and
// stable status routing. Cross-module references are bare tenant-safe scalars.
{ model: "KwpApiContractSnapshot", tenantField: "tenantId", schema: "kwp.prisma" },
{ model: "KwpCapabilityState", tenantField: "tenantId", schema: "kwp.prisma" },
{ model: "KwpErrorReport", tenantField: "tenantId", schema: "kwp.prisma" },
{ model: "KwpProjectRouting", tenantField: "tenantId", schema: "kwp.prisma" },
{ model: "KwpProjectCatalogState", tenantField: "tenantId", schema: "kwp.prisma" },
{ model: "KwpProjectCatalogItem", tenantField: "tenantId", schema: "kwp.prisma" },
{ model: "KwpMaterialPosition", tenantField: "tenantId", schema: "kwp.prisma" },
// crypto.prisma (R-P5 Phase 1)
{ model: "TenantEncryptionKey", tenantField: "tenantId", schema: "crypto.prisma" },
// featureFlags.prisma
{ model: "FeatureFlag", tenantField: "tenantId", schema: "featureFlags.prisma" },
// Cross-tenant operator record at runtime, but tenant lifecycle export must
// retain the override whose target is identified by this tenantId.
{ model: "AdminFeatureFlagOverride", tenantField: "tenantId", schema: "featureFlags.prisma" },
// helpDesk.prisma
{ model: "Feedback", tenantField: "tenantId", schema: "helpDesk.prisma" },
@@ -134,6 +161,8 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
// portals.prisma
{ model: "Portal", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalUser", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalSession", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalToken", tenantField: "tenantId", schema: "portals.prisma" },
// sites.prisma
{ model: "Site", tenantField: "tenantId", schema: "sites.prisma" },
@@ -261,6 +290,13 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "EmailIntegrationSyncCursor", tenantField: "tenantId", schema: "email-inbox.prisma" },
{ model: "EmailIntegrationWebhookEvent", tenantField: "tenantId", schema: "email-inbox.prisma" },
// telephony.prisma (AK-P15a) — Connection before its Cascade children;
// CallSession precedes WebhookEvent because the event can link to a call.
{ model: "TelephonyConnection", tenantField: "tenantId", schema: "telephony.prisma" },
{ model: "TelephonyUserBinding", tenantField: "tenantId", schema: "telephony.prisma" },
{ model: "TelephonyCallSession", tenantField: "tenantId", schema: "telephony.prisma" },
{ model: "TelephonyWebhookEvent", tenantField: "tenantId", schema: "telephony.prisma" },
// booking.prisma (AK-P16b) — BookingPage before its Cascade children
// (BookingPageProvider/Appointment via FK bookingPageId). AvailabilityRule/
// Exception are standalone (provider linked by bare scalar, no FK).
@@ -294,6 +330,9 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "Pipeline", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "PipelineStage", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "PipelineAccess", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "PipelineAccessRequest", tenantField: "tenantId", schema: "pipelineAccessRequest.prisma" },
// PipelineFieldGroup before PipelineFieldConfig: the config's groupId points here.
{ model: "PipelineFieldGroup", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "PipelineFieldConfig", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "PipelineFieldVisibility", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "LostReason", tenantField: "tenantId", schema: "projekt.prisma" },
@@ -301,6 +340,46 @@ export const TENANT_SCOPED_MODELS: readonly TenantScopedModel[] = [
{ model: "ProjektStageChange", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "PipelineAggregateSnapshot", tenantField: "tenantId", schema: "projekt.prisma" },
{ model: "ProjektKontakt", tenantField: "tenantId", schema: "projekt.prisma" },
// WF-P8 S02 address extras. Cascades from Projekt, which precedes it here.
{ model: "ProjektAdressDetail", tenantField: "tenantId", schema: "projekt.prisma" },
// WF-P8 baseline. projektId/sourceId are BARE scalars, so only the
// Handover -> HandoverItem cascade constrains the order here.
{ model: "ProjektNotiz", tenantField: "tenantId", schema: "projektNotiz.prisma" },
{ model: "PipelineHandover", tenantField: "tenantId", schema: "pipelineHandover.prisma" },
{ model: "PipelineHandoverItem", tenantField: "tenantId", schema: "pipelineHandover.prisma" },
// portals.prisma customer-project children. Their required Project, Stage,
// File, Portal and PortalUser parents all precede them in restore order.
{ model: "PortalDomainHostnameClaim", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalCustomDomain", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalConfiguration", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalDocumentAutoReleaseRule", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalProjectAccess", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalSubcontractorAccess", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalStageVisibility", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalProjectDocument", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalEmailTemplate", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalNotificationPreference", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalUpload", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalComplaint", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalActivityRoutingRule", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalServiceInboxItem", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalDeletionRequest", tenantField: "tenantId", schema: "portals.prisma" },
{ model: "PortalGdprExportJob", tenantField: "tenantId", schema: "portals.prisma" },
// chat.prisma (AK-P15b) — Projekt must be restored before project-linked
// channels because the RLS integrity contract verifies the bare projektId.
// Within the module, channels precede messages and messages precede members
// because lastReadMessageId is optional. Remaining aggregates follow.
{ model: "TeamChat", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatGroupSource", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatMessage", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatMember", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatThread", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatPinnedMessage", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatReaction", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatRead", tenantField: "tenantId", schema: "chat.prisma" },
{ model: "TeamChatEvent", tenantField: "tenantId", schema: "chat.prisma" },
// auftrag.prisma (P9 — R-P9a/R-P9b). Order-specific sub-areas on the same
// Projekt core. Projekt/User/Group/File/Form/Calendar references are BARE
@@ -369,7 +448,7 @@ export function tenantScopedModelNames(): readonly string[] {
* staging verification flagged as broken (`TenantUser`, `TenantIpAddress`,
* `UserRole`, `Event`, `Log`, `SupportTicket`). All other globals reached
* from tenant-scoped models in the current schema are platform-level
* catalogs (`Onboarding`, `WorkflowBlock`) — these are expected to
* catalogs (`Onboarding`) — these are expected to
* already exist on the target deployment because they are seeded by
* migrations/setup scripts, NOT by tenant onboarding. Their absence on
* an "empty" target is therefore an operator-environment issue, not a
@@ -399,7 +478,6 @@ export const GLOBAL_REFERENCED_MODELS: readonly GlobalReferencedModel[] = [
schema: "accounts.prisma",
referencedBy: [
// (kept in alphabetical order by source model for review-friendliness)
{ model: "AdminTenantNote", fkColumn: "authorUserId" },
{ model: "ApiKey", fkColumn: "createdByUserId" },
{ model: "AppSyncRun", fkColumn: "createdByUserId" },
{ model: "DataConnection", fkColumn: "createdByUserId" },
@@ -418,6 +496,7 @@ export const GLOBAL_REFERENCED_MODELS: readonly GlobalReferencedModel[] = [
{ model: "OnboardingSession", fkColumn: "userId" },
{ model: "Portal", fkColumn: "createdByUserId" },
{ model: "Site", fkColumn: "createdByUserId" },
{ model: "SupportTicket", fkColumn: "assignedToUserId" },
{ model: "SupportTicket", fkColumn: "userId" },
{ model: "TenantIpAddress", fkColumn: "userId" },
{ model: "TenantUser", fkColumn: "userId" },
@@ -451,9 +530,13 @@ export const GLOBAL_REFERENCED_MODELS: readonly GlobalReferencedModel[] = [
* test can prove every global reference is consciously categorized.
*/
export const PLATFORM_CATALOG_GLOBALS: readonly string[] = [
"AdminUser", // operator identity is deployment-owned and never part of a tenant snapshot
"App", // R-P5: global integrations catalog (seeded at deployment), referenced by DataConnection.appId
"Onboarding",
"WorkflowBlock",
// Billing products and prices are deployment-seeded catalog rows. Tenant
// acquisition ledgers preserve their FKs but never export catalog copies.
"SubscriptionProduct",
"SubscriptionPrice",
];
/** Constant-time check that a model is on the snapshot-globals list. */
@@ -6,7 +6,7 @@ import {
prismaModelAccessor,
type PrismaLikeClient,
} from "./prisma-runner.js";
import { TENANT_SCOPED_MODELS } from "./models.js";
import { TENANT_LIFECYCLE_MODELS } from "./derived-models.js";
import type { ModelScalarTypeMap } from "./json-codec.js";
describe("prismaModelAccessor", () => {
@@ -79,6 +79,46 @@ describe("createPrismaSnapshotRunner", () => {
}
})()).rejects.toThrow(/no delegate for model "TenantUser"/u);
});
it("passes relation filters through and paginates compound-key derived children", async () => {
const rows = [
{ knowledgeBaseArticleId: "a1", userAnalyticsId: "u1" },
{ knowledgeBaseArticleId: "a1", userAnalyticsId: "u2" },
{ knowledgeBaseArticleId: "a2", userAnalyticsId: "u1" },
];
const calls: Array<Record<string, unknown>> = [];
const client: PrismaLikeClient = {
knowledgeBaseArticleViews: {
findMany: async (args: Record<string, unknown>) => {
calls.push(args);
const cursor = args.cursor as
| { knowledgeBaseArticleId_userAnalyticsId?: { knowledgeBaseArticleId: string; userAnalyticsId: string } }
| undefined;
if (!cursor) return rows.slice(0, 2);
return rows.slice(2);
},
},
};
const runner = createPrismaSnapshotRunner(client);
const where = { knowledgeBaseArticle: { knowledgeBase: { tenantId: "tenant_1" } } };
const out: Array<Record<string, unknown>> = [];
for await (const row of runner.findManyByWhere("KnowledgeBaseArticleViews", where, 2)) {
out.push(row);
}
expect(out).toEqual(rows);
expect(calls[0]?.where).toEqual(where);
expect(calls[0]?.orderBy).toEqual([
{ knowledgeBaseArticleId: "asc" },
{ userAnalyticsId: "asc" },
]);
expect(calls[1]?.cursor).toEqual({
knowledgeBaseArticleId_userAnalyticsId: {
knowledgeBaseArticleId: "a1",
userAnalyticsId: "u2",
},
});
});
});
describe("createPrismaRestoreRunner", () => {
@@ -136,6 +176,92 @@ describe("createPrismaRestoreRunner", () => {
expect((row.ydocState as Buffer).toString()).toBe("hi");
});
it("restores TeamChatEvent rows in cursor order with target-allocated sequences", async () => {
let received: Array<Record<string, unknown>> | undefined;
const client: PrismaLikeClient = {
teamChatEvent: {
createMany: async (args: { data: Array<Record<string, unknown>> }) => {
received = args.data;
return { count: args.data.length };
},
},
};
const types = new Map<string, ModelScalarTypeMap>([
[
"TeamChatEvent",
{
modelName: "TeamChatEvent",
fields: new Map([["sequence", "BigInt"]]),
},
],
]);
const runner = createPrismaRestoreRunner(client, types);
const result = await runner.createMany("TeamChatEvent", [
{
id: "event_1",
tenantId: "tenant_1",
chatId: "chat_1",
sequence: "9007199254740993",
},
]);
expect(result).toEqual({ written: 1 });
expect(received?.[0]).not.toHaveProperty("sequence");
});
it("starts a fresh TeamChat event-stream generation on restore", async () => {
let received: Array<Record<string, unknown>> | undefined;
const client: PrismaLikeClient = {
teamChat: {
createMany: async (args: { data: Array<Record<string, unknown>> }) => {
received = args.data;
return { count: args.data.length };
},
},
};
const runner = createPrismaRestoreRunner(client, new Map());
const result = await runner.createMany("TeamChat", [
{
id: "chat_1",
tenantId: "tenant_1",
eventStreamId: "source_stream",
},
]);
expect(result).toEqual({ written: 1 });
expect(received?.[0]?.eventStreamId).not.toBe("source_stream");
expect(received?.[0]?.eventStreamId).toMatch(
/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u,
);
});
it("snapshots TeamChatEvent rows by their durable sequence cursor", async () => {
const calls: Array<Record<string, unknown>> = [];
const client: PrismaLikeClient = {
teamChatEvent: {
findMany: async (args: Record<string, unknown>) => {
calls.push(args);
return [];
},
},
};
const runner = createPrismaSnapshotRunner(client);
const rows: Record<string, unknown>[] = [];
for await (const row of runner.findManyByTenant(
"TeamChatEvent",
"tenantId",
"tenant_1",
100,
)) {
rows.push(row);
}
expect(rows).toEqual([]);
expect(calls[0]?.orderBy).toEqual({ sequence: "asc" });
});
it("findManyByIds delegates to findMany with where.id.in", async () => {
let received: Record<string, unknown> | undefined;
const client: PrismaLikeClient = {
@@ -168,6 +294,53 @@ describe("createPrismaRestoreRunner", () => {
expect(invoked).toBe(false);
});
it("combines id lookup with a hybrid-global predicate", async () => {
let received: Record<string, unknown> | undefined;
const client: PrismaLikeClient = {
workflow: {
findMany: async (args: Record<string, unknown>) => {
received = args;
return [{ id: "wf_global", tenantId: null }];
},
},
};
const runner = createPrismaSnapshotRunner(client);
await runner.findManyByIds!("Workflow", ["wf_global"], { tenantId: null });
expect(received).toEqual({
where: {
AND: [{ id: { in: ["wf_global"] } }, { tenantId: null }],
},
});
});
it("loads functional global children by foreign key", async () => {
let received: Record<string, unknown> | undefined;
const client: PrismaLikeClient = {
workflowBlock: {
findMany: async (args: Record<string, unknown>) => {
received = args;
return [{ id: "block_1", workflowId: "workflow_1" }];
},
},
};
const runner = createPrismaSnapshotRunner(client);
const rows = await runner.findManyByForeignKeys!(
"WorkflowBlock",
"workflowId",
["workflow_1"],
{ workflow: { tenantId: null } },
);
expect(rows).toHaveLength(1);
expect(received).toEqual({
where: {
AND: [
{ workflowId: { in: ["workflow_1"] } },
{ workflow: { tenantId: null } },
],
},
});
});
it("upsertManyById creates fresh rows and reports updated=N for pre-existing ids", async () => {
const existing = new Set(["u_exists"]);
const createdRows: Array<Record<string, unknown>> = [];
@@ -220,12 +393,13 @@ describe("createPrismaRestoreRunner", () => {
expect(result.written).toBe(0);
expect(invoked).toBe(false);
});
});
describe("assertClientCoversTenantScopedModels", () => {
it("passes for a client exposing every accessor", () => {
const client: PrismaLikeClient = {};
for (const { model } of TENANT_SCOPED_MODELS) {
for (const { model } of TENANT_LIFECYCLE_MODELS) {
client[prismaModelAccessor(model)] = { findMany: () => Promise.resolve([]) };
}
expect(() => assertClientCoversTenantScopedModels(client)).not.toThrow();
@@ -7,9 +7,14 @@
* wiring imports from here lazily inside the citty `run()` body so the
* command tree loads without pulling Prisma into memory.
*/
import { randomUUID } from "node:crypto";
import type { PrismaRunner } from "./snapshot.js";
import type { PrismaRestoreRunner } from "./restore.js";
import { TENANT_SCOPED_MODELS } from "./models.js";
import {
TENANT_DERIVED_MODELS,
TENANT_LIFECYCLE_MODELS,
} from "./derived-models.js";
import { decodeRowForPrisma, type ModelScalarTypeMap } from "./json-codec.js";
/** Minimal shape of `PrismaClient` we lean on — anything `[modelAccessor]` shaped. */
@@ -34,12 +39,29 @@ export function prismaModelAccessor(modelName: string): string {
*/
const CURSOR_FIELD_OVERRIDES: Record<string, string> = {
TenantSettingsRow: "tenantId",
// Event ids are opaque CUIDs. Snapshot by the durable cursor so restore can
// allocate new target-wide sequence values in the original event order.
TeamChatEvent: "sequence",
};
const TEAM_CHAT_MODEL = "TeamChat";
const TEAM_CHAT_EVENT_MODEL = "TeamChatEvent";
function cursorFieldFor(modelName: string): string {
return CURSOR_FIELD_OVERRIDES[modelName] ?? "id";
}
interface CursorSpec {
readonly fields: readonly string[];
readonly compoundField?: string;
}
function cursorSpecFor(modelName: string): CursorSpec {
const derived = TENANT_DERIVED_MODELS.find((entry) => entry.model === modelName);
if (derived?.cursor) return derived.cursor;
return { fields: [cursorFieldFor(modelName)] };
}
/**
* Build a snapshot-side `PrismaRunner` that streams rows out of the
* supplied client using cursor pagination keyed by primary key.
@@ -48,8 +70,61 @@ function cursorFieldFor(modelName: string): string {
* code path because their PK column is included in the rows themselves.
*/
export function createPrismaSnapshotRunner(prisma: PrismaLikeClient): PrismaRunner {
const findManyByWhere = async function* (
modelName: string,
where: Readonly<Record<string, unknown>>,
pageSize: number,
): AsyncIterable<Record<string, unknown>> {
const accessor = prismaModelAccessor(modelName);
const delegate = prisma[accessor] as
| undefined
| {
findMany: (args: Record<string, unknown>) => Promise<Array<Record<string, unknown>>>;
};
if (!delegate || typeof delegate.findMany !== "function") {
throw new Error(
`PrismaRunner: client has no delegate for model "${modelName}" (accessor "${accessor}").`,
);
}
const cursorSpec = cursorSpecFor(modelName);
let cursor: Record<string, unknown> | undefined;
// Belt-and-suspenders: cap the outer loop so a misbehaving page
// cannot wedge the snapshot. 10 M rows / pageSize is a sane ceiling.
const maxIterations = Math.max(1, Math.ceil(10_000_000 / pageSize));
let iterations = 0;
while (iterations++ < maxIterations) {
const orderBy =
cursorSpec.fields.length === 1
? { [cursorSpec.fields[0]!]: "asc" }
: cursorSpec.fields.map((field) => ({ [field]: "asc" }));
const args: Record<string, unknown> = { where, take: pageSize, orderBy };
if (cursor !== undefined) {
args.cursor = cursor;
args.skip = 1;
}
const page = await delegate.findMany(args);
if (page.length === 0) break;
for (const row of page) yield row;
if (page.length < pageSize) break;
const last = page[page.length - 1]!;
const cursorValues: Record<string, unknown> = {};
for (const field of cursorSpec.fields) {
const value = last[field];
if (value === undefined || value === null) {
throw new Error(
`PrismaRunner: cursor field "${field}" missing on a row of ${modelName}; cannot paginate.`,
);
}
cursorValues[field] = value;
}
cursor = cursorSpec.compoundField
? { [cursorSpec.compoundField]: cursorValues }
: { [cursorSpec.fields[0]!]: cursorValues[cursorSpec.fields[0]!] };
}
};
return {
async findManyByIds(modelName, ids) {
async findManyByIds(modelName, ids, extraWhere) {
if (ids.length === 0) return [];
const accessor = prismaModelAccessor(modelName);
const delegate = prisma[accessor] as
@@ -62,9 +137,13 @@ export function createPrismaSnapshotRunner(prisma: PrismaLikeClient): PrismaRunn
`PrismaRunner.findManyByIds: client has no delegate for model "${modelName}" (accessor "${accessor}").`,
);
}
return delegate.findMany({ where: { id: { in: Array.from(ids) } } });
const idWhere = { id: { in: Array.from(ids) } };
return delegate.findMany({
where: extraWhere ? { AND: [idWhere, extraWhere] } : idWhere,
});
},
async *findManyByTenant(modelName, tenantField, tenantId, pageSize) {
async findManyByForeignKeys(modelName, foreignKey, ids, extraWhere) {
if (ids.length === 0) return [];
const accessor = prismaModelAccessor(modelName);
const delegate = prisma[accessor] as
| undefined
@@ -73,40 +152,18 @@ export function createPrismaSnapshotRunner(prisma: PrismaLikeClient): PrismaRunn
};
if (!delegate || typeof delegate.findMany !== "function") {
throw new Error(
`PrismaRunner: client has no delegate for model "${modelName}" (accessor "${accessor}").`,
`PrismaRunner.findManyByForeignKeys: client has no delegate for model "${modelName}" (accessor "${accessor}").`,
);
}
const cursorField = cursorFieldFor(modelName);
let cursor: Record<string, unknown> | undefined;
// Belt-and-suspenders: cap the outer loop so a misbehaving page
// (always returning the same `pageSize` rows with the same last id)
// cannot wedge the snapshot. 10 M rows / pageSize is a sane ceiling.
const maxIterations = Math.max(1, Math.ceil(10_000_000 / pageSize));
let iterations = 0;
while (iterations++ < maxIterations) {
const args: Record<string, unknown> = {
where: { [tenantField]: tenantId },
take: pageSize,
orderBy: { [cursorField]: "asc" },
};
if (cursor !== undefined) {
args.cursor = cursor;
args.skip = 1;
}
const page = await delegate.findMany(args);
if (page.length === 0) break;
for (const row of page) yield row;
if (page.length < pageSize) break;
const last = page[page.length - 1] as Record<string, unknown>;
const lastCursor = last[cursorField];
if (lastCursor === undefined || lastCursor === null) {
throw new Error(
`PrismaRunner: cursor field "${cursorField}" missing on a row of ${modelName}; cannot paginate.`,
);
}
cursor = { [cursorField]: lastCursor };
}
const fkWhere = { [foreignKey]: { in: Array.from(ids) } };
return delegate.findMany({
where: extraWhere ? { AND: [fkWhere, extraWhere] } : fkWhere,
});
},
async *findManyByTenant(modelName, tenantField, tenantId, pageSize) {
yield* findManyByWhere(modelName, { [tenantField]: tenantId }, pageSize);
},
findManyByWhere,
};
}
@@ -137,8 +194,26 @@ export function createPrismaRestoreRunner(
);
}
const fieldTypes = schemaScalarTypes.get(modelName)?.fields;
const decoded = rows.map((row) => decodeRowForPrisma(row, fieldTypes));
const result = await delegate.createMany({ data: decoded, skipDuplicates: true });
const decodedRows = rows.map((row) => decodeRowForPrisma(row, fieldTypes));
const decoded = decodedRows.map((decodedRow) => {
if (modelName === TEAM_CHAT_MODEL) {
// A restored channel starts a fresh event-stream generation. Clients
// holding a pre-restore cursor must resync instead of skipping rows.
return { ...decodedRow, eventStreamId: randomUUID() };
}
if (modelName !== TEAM_CHAT_EVENT_MODEL) return decodedRow;
// The cursor sequence is database-global and can collide with events
// from other tenants in the restore target. Omit it so PostgreSQL
// allocates fresh values while preserving snapshot cursor order.
const { sequence: _sourceSequence, ...restoredEvent } = decodedRow;
return restoredEvent;
});
const result = await delegate.createMany({
data: decoded,
skipDuplicates: true,
});
return { written: result?.count ?? decoded.length };
},
async upsertManyById(modelName, rows) {
@@ -190,21 +265,22 @@ export function createPrismaRestoreRunner(
}
/**
* Defensive cross-check: every tenant-scoped model declared in `models.ts`
* Defensive cross-check: every direct and FK-derived tenant lifecycle model
* must resolve to an accessor on the supplied client. Surfaces a clear
* error before a snapshot or restore tries to stream from a missing
* delegate. Pure helper — not invoked by the runners themselves.
*/
export function assertClientCoversTenantScopedModels(prisma: PrismaLikeClient): void {
const missing: string[] = [];
for (const { model } of TENANT_SCOPED_MODELS) {
for (const entry of TENANT_LIFECYCLE_MODELS) {
const { model } = entry;
if (prisma[prismaModelAccessor(model)] === undefined) {
missing.push(model);
}
}
if (missing.length > 0) {
throw new Error(
`PrismaClient is missing accessors for tenant-scoped models: ${missing.join(", ")}.`,
`PrismaClient is missing accessors for tenant lifecycle models: ${missing.join(", ")}.`,
);
}
}
@@ -31,17 +31,39 @@ class FakeSourcePrisma implements PrismaRunner {
const list = this.rows[modelName] ?? [];
for (const r of list) yield r;
}
async *findManyByWhere(
modelName: string,
where: Readonly<Record<string, unknown>>,
pageSize: number,
): AsyncIterable<Record<string, unknown>> {
void where;
void pageSize;
const list = this.rows[modelName] ?? [];
for (const r of list) yield r;
}
async findManyByIds(modelName: string, ids: readonly string[]): Promise<Record<string, unknown>[]> {
const list = this.globals[modelName] ?? [];
return list.filter((r) => typeof r.id === "string" && ids.includes(r.id as string));
}
async findManyByForeignKeys(
modelName: string,
foreignKey: string,
ids: readonly string[],
): Promise<Record<string, unknown>[]> {
const list = this.globals[modelName] ?? [];
return list.filter(
(row) => typeof row[foreignKey] === "string" && ids.includes(row[foreignKey] as string),
);
}
}
class FakeTargetPrisma implements PrismaRestoreRunner {
readonly writes: Record<string, Record<string, unknown>[]> = {};
readonly writeOrder: string[] = [];
/** Rows that already exist on the target — used by upsertManyById to simulate prior state. */
readonly preExisting: Record<string, Set<string>> = {};
async createMany(modelName: string, rows: Record<string, unknown>[]): Promise<{ written: number }> {
if (rows.length > 0) this.writeOrder.push(modelName);
this.writes[modelName] = (this.writes[modelName] ?? []).concat(rows);
return { written: rows.length };
}
@@ -144,6 +166,50 @@ describe("runTenantRestore", () => {
}
// Anonymization preserved on the way in.
expect(target.writes.TenantUserInvitation?.[0]?.email).toMatch(/@anonymized\.test$/u);
}, 15_000);
it("restores FK-derived children without adding tenantId and in parent-first order", async () => {
const sourcePrisma = new FakeSourcePrisma({
TenantInboundAddress: [{ id: "inbound_1", tenantId: "tenant_a", address: "in@local.test" }],
Email: [{ id: "email_1", tenantInboundAddressId: "inbound_1", messageId: "message_1" }],
KnowledgeBase: [{ id: "kb_1", tenantId: "tenant_a" }],
KnowledgeBaseCategory: [{ id: "category_1", knowledgeBaseId: "kb_1" }],
Workflow: [{ id: "workflow_1", tenantId: "tenant_a" }],
WorkflowBlock: [{ id: "block_1", workflowId: "workflow_1" }],
WorkflowExecution: [
{ id: "execution_1", tenantId: "tenant_a", workflowId: "workflow_1", waitingBlockId: "block_1" },
],
Portal: [{ id: "portal_1", tenantId: "tenant_a" }],
PortalPage: [{ id: "page_1", portalId: "portal_1" }],
});
const snapshotPath = join(workdir, "derived.tar.gz");
await runTenantSnapshot({
tenantId: "tenant_a",
profile: "none",
superAdminConfirmed: true,
prisma: sourcePrisma,
output: { kind: "local", path: snapshotPath },
includeGlobals: false,
logger: { info: vi.fn(), warn: vi.fn() },
});
const target = new FakeTargetPrisma();
await runTenantRestore({
tenantId: "tenant_clone",
source: snapshotPath,
prisma: target,
yes: true,
logger: { info: vi.fn(), warn: vi.fn() },
});
for (const model of ["Email", "KnowledgeBaseCategory", "WorkflowBlock", "PortalPage"]) {
expect(target.writes[model]?.[0]).not.toHaveProperty("tenantId");
}
expect(target.writes.TenantInboundAddress?.[0]?.tenantId).toBe("tenant_clone");
expect(target.writeOrder.indexOf("TenantInboundAddress")).toBeLessThan(target.writeOrder.indexOf("Email"));
expect(target.writeOrder.indexOf("KnowledgeBase")).toBeLessThan(target.writeOrder.indexOf("KnowledgeBaseCategory"));
expect(target.writeOrder.indexOf("WorkflowBlock")).toBeLessThan(target.writeOrder.indexOf("WorkflowExecution"));
expect(target.writeOrder.indexOf("Portal")).toBeLessThan(target.writeOrder.indexOf("PortalPage"));
});
it("aborts when the operator answers 'no' to the confirmation prompt", async () => {
@@ -443,6 +509,9 @@ describe("runTenantRestore", () => {
async *findManyByTenant() {
// empty
},
async *findManyByWhere() {
// empty
},
};
const snapshotPath = join(workdir, "legacy.tar.gz");
await runTenantSnapshot({
@@ -8,14 +8,11 @@
* interface so the CLI package stays free of `@prisma/client`. Production
* callers wire up a real client in `bin/hivegrid-cli.mjs`; tests pass a fake.
*
* Foreign-key remapping: only the `tenantId` column is rewritten. Row primary
* keys are preserved (the snapshot is intended to land in a separate
* Foreign-key remapping: direct tenant rows receive the target `tenantId`;
* FK-derived children keep their original foreign keys because parent primary
* keys are preserved. The snapshot is intended to land in a separate
* environment, so id collisions with other tenants in that target are not
* the concern this commit addresses; the schema's tenant-scoped uniqueness
* indexes do the rest). The roadmap notes (`tenant-snapshot.md` step 6) call
* out a deeper FK-aware remapper as a follow-up if cross-tenant FK chains
* ever appear (today none of the tenant-scoped models cross-reference each
* other in a way that survives a snapshot — they all root at `tenantId`).
* handled here.
*/
import { defineCommand } from "citty";
import consola from "consola";
@@ -37,6 +34,7 @@ import {
deserializeTenantManifest,
type TenantSnapshotManifest,
} from "./manifest.js";
import { isTenantDerivedModel } from "./derived-models.js";
import { decryptFile, type EncryptionConfig } from "../backup/encryption.js";
export interface PrismaRestoreRunner {
@@ -206,7 +204,9 @@ export async function runTenantRestore(opts: RunRestoreOptions): Promise<RunRest
for (const entry of manifest.models) {
const filePath = join(stageDir, entry.path);
const rows = await readJsonl(filePath);
const remapped = rows.map((row) => ({ ...row, tenantId: opts.tenantId }));
const remapped = isTenantDerivedModel(entry.model)
? rows
: rows.map((row) => ({ ...row, tenantId: opts.tenantId }));
const result = await opts.prisma.createMany(entry.model, remapped);
perModel.push({ model: entry.model, written: result.written, expected: entry.rowCount });
if (result.written !== entry.rowCount) {
@@ -11,7 +11,10 @@ import {
runTenantSnapshot,
type PrismaRunner,
} from "./snapshot.js";
import { TENANT_SCOPED_MODELS } from "./models.js";
import {
TENANT_DERIVED_MODELS,
TENANT_LIFECYCLE_MODELS,
} from "./derived-models.js";
class FakePrisma implements PrismaRunner {
constructor(
@@ -33,10 +36,30 @@ class FakePrisma implements PrismaRunner {
yield r;
}
}
async *findManyByWhere(
modelName: string,
where: Readonly<Record<string, unknown>>,
pageSize: number,
): AsyncIterable<Record<string, unknown>> {
void where;
void pageSize;
const list = this.rows[modelName] ?? [];
for (const r of list) yield r;
}
async findManyByIds(modelName: string, ids: readonly string[]): Promise<Record<string, unknown>[]> {
const list = this.globals[modelName] ?? [];
return list.filter((r) => typeof r.id === "string" && ids.includes(r.id as string));
}
async findManyByForeignKeys(
modelName: string,
foreignKey: string,
ids: readonly string[],
): Promise<Record<string, unknown>[]> {
const list = this.globals[modelName] ?? [];
return list.filter(
(row) => typeof row[foreignKey] === "string" && ids.includes(row[foreignKey] as string),
);
}
}
class RecordingPrisma extends FakePrisma {
@@ -51,6 +74,15 @@ class RecordingPrisma extends FakePrisma {
this.pageSizes.push(pageSize);
yield* super.findManyByTenant(modelName, tenantField, tenantId, pageSize);
}
override async *findManyByWhere(
modelName: string,
where: Readonly<Record<string, unknown>>,
pageSize: number,
): AsyncIterable<Record<string, unknown>> {
this.pageSizes.push(pageSize);
yield* super.findManyByWhere(modelName, where, pageSize);
}
}
describe("parseOutputTarget", () => {
@@ -122,7 +154,7 @@ describe("runTenantSnapshot", () => {
const invEntry = result.manifest.models.find((m) => m.model === "TenantUserInvitation");
expect(invEntry?.rowCount).toBe(1);
// every other model should be present with rowCount=0.
expect(result.manifest.models).toHaveLength(TENANT_SCOPED_MODELS.length);
expect(result.manifest.models).toHaveLength(TENANT_LIFECYCLE_MODELS.length);
for (const m of result.manifest.models) {
if (m.model !== "TenantUser" && m.model !== "TenantUserInvitation") {
expect(m.rowCount).toBe(0);
@@ -130,6 +162,47 @@ describe("runTenantSnapshot", () => {
}
});
it("extracts Email, KnowledgeBase, Workflow, and Portal children through FK scope", async () => {
const queries = new Map<string, Readonly<Record<string, unknown>>>();
class DerivedProbe extends FakePrisma {
override async *findManyByWhere(
modelName: string,
where: Readonly<Record<string, unknown>>,
pageSize: number,
): AsyncIterable<Record<string, unknown>> {
queries.set(modelName, where);
yield* super.findManyByWhere(modelName, where, pageSize);
}
}
const prisma = new DerivedProbe({
Email: [{ id: "email_1", tenantInboundAddressId: "inbound_1" }],
KnowledgeBaseCategory: [{ id: "category_1", knowledgeBaseId: "kb_1" }],
WorkflowBlock: [{ id: "block_1", workflowId: "workflow_1" }],
PortalPage: [{ id: "page_1", portalId: "portal_1" }],
});
const result = await runTenantSnapshot({
tenantId: "ten_a",
profile: "none",
superAdminConfirmed: true,
prisma,
output: { kind: "local", path: join(workdir, "derived.tar.gz") },
includeGlobals: false,
logger: { info: vi.fn(), warn: vi.fn() },
});
for (const entry of TENANT_DERIVED_MODELS) {
expect(result.manifest.models.some((model) => model.model === entry.model)).toBe(true);
}
expect(result.manifest.models.find((entry) => entry.model === "Email")?.rowCount).toBe(1);
expect(result.manifest.models.find((entry) => entry.model === "KnowledgeBaseCategory")?.rowCount).toBe(1);
expect(result.manifest.models.find((entry) => entry.model === "WorkflowBlock")?.rowCount).toBe(1);
expect(result.manifest.models.find((entry) => entry.model === "PortalPage")?.rowCount).toBe(1);
expect(queries.get("Email")).toEqual({ tenantInboundAddress: { tenantId: "ten_a" } });
expect(queries.get("KnowledgeBaseCategory")).toEqual({ knowledgeBase: { tenantId: "ten_a" } });
expect(queries.get("WorkflowBlock")).toEqual({ workflow: { tenantId: "ten_a" } });
expect(queries.get("PortalPage")).toEqual({ portal: { tenantId: "ten_a" } });
});
it("requires explicit super-admin confirmation for the none anonymization profile", async () => {
await expect(
runTenantSnapshot({
@@ -189,7 +262,7 @@ describe("runTenantSnapshot", () => {
logger: { info: vi.fn(), warn: vi.fn() },
});
expect(prisma.pageSizes).toHaveLength(TENANT_SCOPED_MODELS.length);
expect(prisma.pageSizes).toHaveLength(TENANT_LIFECYCLE_MODELS.length);
expect(new Set(prisma.pageSizes)).toEqual(new Set([17]));
});
@@ -421,6 +494,9 @@ describe("runTenantSnapshot", () => {
void pageSize;
yield* [];
}
async *findManyByWhere(): AsyncIterable<Record<string, unknown>> {
yield* [];
}
}
const warn = vi.fn();
const outPath = join(workdir, "snap.tar.gz");
@@ -432,7 +508,7 @@ describe("runTenantSnapshot", () => {
logger: { info: vi.fn(), warn },
});
expect(result.manifest.globals).toBeUndefined();
expect(warn).toHaveBeenCalledWith(expect.stringContaining("findManyByIds"));
expect(warn).toHaveBeenCalledWith(expect.stringContaining("globals lookup methods"));
});
it("preserves anonymization-FK consistency across calls (same salt seed inside one run)", async () => {
@@ -36,7 +36,11 @@ import {
type TenantManifestModelEntry,
type TenantSnapshotManifest,
} from "./manifest.js";
import { TENANT_SCOPED_MODELS } from "./models.js";
import {
TENANT_LIFECYCLE_MODELS,
tenantWhereForLifecycleModel,
type TenantLifecycleModel,
} from "./derived-models.js";
import { assertSuperAdminForNoneProfile, writeSnapshotAudit } from "./audit.js";
import { snapshotReplacer } from "./json-codec.js";
import { collectAndWriteGlobals, type GlobalsPrismaRunner } from "./globals-runner.js";
@@ -65,6 +69,16 @@ export interface PrismaRunner extends Partial<GlobalsPrismaRunner> {
tenantId: string,
pageSize: number,
): AsyncIterable<Record<string, unknown>>;
/**
* Stream FK-derived tenant rows using a relation-filter where clause.
* This is separate from findManyByTenant because these models deliberately
* have no tenantId scalar of their own.
*/
findManyByWhere(
modelName: string,
where: Readonly<Record<string, unknown>>,
pageSize: number,
): AsyncIterable<Record<string, unknown>>;
}
export interface SnapshotS3Output {
@@ -160,13 +174,12 @@ export async function runTenantSnapshot(opts: RunSnapshotOptions): Promise<RunSn
const pageSize = opts.pageSize ?? 1000;
const modelEntries: TenantManifestModelEntry[] = [];
for (const { model, tenantField } of TENANT_SCOPED_MODELS) {
const filePath = join(postgresDir, `${model}.jsonl`);
logger.info(`Extracting model ${model}`);
for (const entry of TENANT_LIFECYCLE_MODELS) {
const filePath = join(postgresDir, `${entry.model}.jsonl`);
logger.info(`Extracting model ${entry.model}`);
const { rowCount, sizeBytes, sha256 } = await writeModelJsonl({
prisma: opts.prisma,
modelName: model,
tenantField,
entry,
tenantId: opts.tenantId,
pageSize,
profile,
@@ -174,8 +187,8 @@ export async function runTenantSnapshot(opts: RunSnapshotOptions): Promise<RunSn
outPath: filePath,
});
modelEntries.push({
model,
path: `postgres/${model}.jsonl`,
model: entry.model,
path: `postgres/${entry.model}.jsonl`,
rowCount,
sizeBytes,
checksum: { algorithm: "sha256", value: sha256 },
@@ -192,7 +205,10 @@ export async function runTenantSnapshot(opts: RunSnapshotOptions): Promise<RunSn
const wantGlobals = opts.includeGlobals !== false;
if (wantGlobals) {
const globalsRunner = opts.prisma as Partial<GlobalsPrismaRunner>;
if (typeof globalsRunner.findManyByIds === "function") {
if (
typeof globalsRunner.findManyByIds === "function" &&
typeof globalsRunner.findManyByForeignKeys === "function"
) {
const globalsDir = join(stageDir, "globals");
await mkdir(globalsDir, { recursive: true });
const collected = await collectAndWriteGlobals({
@@ -208,7 +224,7 @@ export async function runTenantSnapshot(opts: RunSnapshotOptions): Promise<RunSn
}
} else {
logger.warn(
"Snapshot runner does not implement findManyByIds — skipping globals extraction. Restore into an empty DB will fail on FKs to global rows.",
"Snapshot runner does not implement the globals lookup methods — skipping globals extraction. Restore into an empty DB will fail on FKs to global rows.",
);
}
}
@@ -314,8 +330,7 @@ export async function runTenantSnapshot(opts: RunSnapshotOptions): Promise<RunSn
interface WriteModelJsonlOptions {
prisma: PrismaRunner;
modelName: string;
tenantField: string;
entry: TenantLifecycleModel;
tenantId: string;
pageSize: number;
profile: (typeof PROFILES)[ProfileName];
@@ -330,13 +345,21 @@ async function writeModelJsonl(
const hash = createHash("sha256");
let rowCount = 0;
for await (const row of opts.prisma.findManyByTenant(
opts.modelName,
opts.tenantField,
opts.tenantId,
opts.pageSize,
)) {
const anonymized = anonymizeRow(opts.profile, opts.modelName, row, opts.ctx);
const rows =
opts.entry.scope === "direct"
? opts.prisma.findManyByTenant(
opts.entry.model,
opts.entry.tenantField,
opts.tenantId,
opts.pageSize,
)
: opts.prisma.findManyByWhere(
opts.entry.model,
tenantWhereForLifecycleModel(opts.entry, opts.tenantId),
opts.pageSize,
);
for await (const row of rows) {
const anonymized = anonymizeRow(opts.profile, opts.entry.model, row, opts.ctx);
const line = `${JSON.stringify(anonymized, snapshotReplacer)}\n`;
hash.update(line);
rowCount += 1;
@@ -33,12 +33,17 @@ describe("cli main command", () => {
expect(Object.keys(addSubs ?? {}).sort()).toEqual(["event-type", "hook", "permission"]);
});
it("registers the ops command group with doctor / migrate-tenant / impersonate", async () => {
it("registers the operator command group", async () => {
const subs = await resolveValue(mainCommand.subCommands);
expect(Object.keys(subs ?? {})).toContain("ops");
const opsSubs = await resolveValue(opsCommand.subCommands);
expect(Object.keys(opsSubs ?? {}).sort()).toEqual(["doctor", "impersonate", "migrate-tenant"]);
expect(Object.keys(opsSubs ?? {}).sort()).toEqual([
"doctor",
"impersonate",
"migrate-tenant",
"product-acquisition-recovery",
]);
});
it("registers the audit command group with verify-chain / export-pdf", async () => {
@@ -14,6 +14,7 @@ import { pluginsCommand } from "./commands/plugins/index.js";
import { searchCommand } from "./commands/search/index.js";
import { sequencesCommand } from "./commands/sequences/index.js";
import { tenantCommand } from "./commands/tenant/index.js";
import { runCliWithRls } from "./rls-context.js";
export const mainCommand = defineCommand({
meta: {
@@ -40,8 +41,11 @@ export const mainCommand = defineCommand({
},
});
export async function runMain(): Promise<void> {
await cittyRunMain(mainCommand);
export async function runMain(rawArgs: readonly string[] = process.argv.slice(2)): Promise<void> {
await runCliWithRls({
rawArgs,
execute: () => cittyRunMain(mainCommand, { rawArgs: [...rawArgs] }),
});
}
export {
@@ -0,0 +1,90 @@
import { describe, expect, it, vi } from "vitest";
import { getRlsExecutionContext } from "@hivegrid/db/rls-context.server";
import { readTenantArgument, requiresOperatorIdentity, runCliWithRls } from "./rls-context.js";
describe("operator CLI RLS context", () => {
it("requires an operator identity only for database-backed commands", () => {
expect(requiresOperatorIdentity(["leads", "list"])).toBe(true);
expect(requiresOperatorIdentity(["plugins", "enable", "--tenantId", "tenant-a"])).toBe(true);
expect(requiresOperatorIdentity(["tenant", "snapshot", "--tenant-id", "tenant-a"])).toBe(true);
expect(requiresOperatorIdentity(["tenant", "restore", "--tenant-id=tenant-b"])).toBe(true);
expect(requiresOperatorIdentity(["tenant", "list-snapshots"])).toBe(false);
expect(requiresOperatorIdentity(["plugins", "build"])).toBe(false);
expect(requiresOperatorIdentity(["create", "module", "inventory"])).toBe(false);
expect(requiresOperatorIdentity(["ops", "product-acquisition-recovery", "--tenant", "tenant-a"])).toBe(true);
expect(requiresOperatorIdentity(["leads", "--help"])).toBe(false);
});
it("reads one concrete tenant from either supported flag shape", () => {
expect(readTenantArgument(["forms", "list", "--tenant", "tenant-a"])).toBe("tenant-a");
expect(readTenantArgument(["plugins", "list", "--tenantId=tenant-b"])).toBe("tenant-b");
expect(readTenantArgument(["tenant", "snapshot", "--tenant-id", "tenant-c"])).toBe("tenant-c");
expect(readTenantArgument(["tenant", "restore", "--tenant-id=tenant-d"])).toBe("tenant-d");
expect(readTenantArgument(["search", "reindex", "--tenant=all"])).toBeUndefined();
expect(readTenantArgument(["audit", "verify-chain", "--tenant=__platform__"])).toBeUndefined();
expect(readTenantArgument(["ops", "impersonate", "tenant-c", "user-a", "--env", "staging"])).toBe("tenant-c");
expect(readTenantArgument(["ops", "product-acquisition-recovery", "--tenant", "tenant-e"])).toBe("tenant-e");
});
it("binds and validates the operator plus tenant before command execution", async () => {
const findUnique = vi.fn(async () => ({
id: "operator-a",
status: "active",
}));
const execute = vi.fn(async () => {
expect(getRlsExecutionContext()).toMatchObject({ userId: "operator-a", tenantId: "tenant-a" });
});
await runCliWithRls({
rawArgs: ["forms", "list", "--tenant", "tenant-a"],
env: { HIVEGRID_CLI_OPERATOR_USER_ID: "operator-a" },
client: { adminUser: { findUnique } } as never,
execute,
});
expect(findUnique).toHaveBeenCalledWith({
where: { id: "operator-a" },
select: {
id: true,
status: true,
},
});
expect(execute).toHaveBeenCalledOnce();
expect(getRlsExecutionContext()).toBeNull();
});
it("fails closed for a missing or non-operator identity", async () => {
const execute = vi.fn(async () => undefined);
await expect(
runCliWithRls({ rawArgs: ["leads", "list"], env: {}, client: {} as never, execute }),
).rejects.toThrow("HIVEGRID_CLI_OPERATOR_USER_ID");
await expect(
runCliWithRls({
rawArgs: ["leads", "list"],
env: { HIVEGRID_CLI_OPERATOR_USER_ID: "ordinary-user" },
client: { adminUser: { findUnique: vi.fn(async () => null) } } as never,
execute,
}),
).rejects.toThrow("AdminUser");
expect(execute).not.toHaveBeenCalled();
});
it.each(["disabled", "locked"])("rejects an ineligible operator account state: %s", async (status) => {
const execute = vi.fn(async () => undefined);
await expect(
runCliWithRls({
rawArgs: ["leads", "list"],
env: { HIVEGRID_CLI_OPERATOR_USER_ID: "operator-a" },
client: {
adminUser: { findUnique: vi.fn(async () => ({ id: "operator-a", status })) },
} as never,
execute,
}),
).rejects.toThrow("active HiveGrid AdminUser");
expect(execute).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,104 @@
import { getDbClient, type DbClient } from "@hivegrid/db/client.server";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
const DATABASE_COMMANDS = new Set([
"audit",
"dsgvo",
"feature-flags",
"forms",
"leads",
"marketing",
"outbox",
"search",
"sequences",
]);
const OPERATOR_PLUGIN_COMMANDS = new Set(["list", "enable", "disable", "uninstall", "verify-audit-chain"]);
const OPERATOR_TENANT_COMMANDS = new Set(["snapshot", "restore"]);
type OperatorDbClient = Pick<DbClient, "adminUser">;
export type RunCliWithRlsOptions = {
rawArgs: readonly string[];
env?: NodeJS.ProcessEnv;
execute: () => Promise<void>;
client?: OperatorDbClient;
};
/**
* Runs database-backed operator commands with the same authenticated identity
* contract as the admin application. Authoring, scaffolding and backup tools
* stay usable without opening a database connection.
*/
export async function runCliWithRls(options: RunCliWithRlsOptions): Promise<void> {
if (!requiresOperatorIdentity(options.rawArgs)) {
await options.execute();
return;
}
const env = options.env ?? process.env;
const userId = requireIdentifier(env.HIVEGRID_CLI_OPERATOR_USER_ID, "HIVEGRID_CLI_OPERATOR_USER_ID");
const tenantId = readTenantArgument(options.rawArgs);
await runWithRlsContext({ userId, ...(tenantId ? { tenantId } : {}) }, async () => {
const client = options.client ?? getDbClient();
const operator = await client.adminUser.findUnique({
where: { id: userId },
select: {
id: true,
status: true,
},
});
if (operator?.status !== "active") {
throw new Error("HIVEGRID_CLI_OPERATOR_USER_ID must reference an active HiveGrid AdminUser");
}
await options.execute();
});
}
export function requiresOperatorIdentity(rawArgs: readonly string[]): boolean {
if (rawArgs.some((argument) => argument === "--help" || argument === "-h" || argument === "--version" || argument === "-v")) {
return false;
}
const [command, subcommand] = readCommandPath(rawArgs);
if (!command) return false;
if (DATABASE_COMMANDS.has(command)) return true;
if (command === "plugins") return subcommand ? OPERATOR_PLUGIN_COMMANDS.has(subcommand) : false;
if (command === "tenant") return subcommand ? OPERATOR_TENANT_COMMANDS.has(subcommand) : false;
return command === "ops" && (subcommand === "impersonate" || subcommand === "product-acquisition-recovery");
}
export function readTenantArgument(rawArgs: readonly string[]): string | undefined {
for (let index = 0; index < rawArgs.length; index += 1) {
const argument = rawArgs[index];
const inline = argument.match(/^--(?:tenant|tenantId|tenant-id)=(.+)$/u)?.[1];
const candidate =
inline
?? (argument === "--tenant" || argument === "--tenantId" || argument === "--tenant-id"
? rawArgs[index + 1]
: undefined);
if (!candidate || candidate === "all" || candidate === "__platform__" || candidate.startsWith("-")) continue;
return requireIdentifier(candidate, "tenant argument");
}
const positional = rawArgs.filter((argument) => !argument.startsWith("-"));
if (positional[0] === "ops" && positional[1] === "impersonate" && positional[2]) {
return requireIdentifier(positional[2], "tenant argument");
}
return undefined;
}
function readCommandPath(rawArgs: readonly string[]): [string | undefined, string | undefined] {
const commandIndex = rawArgs.findIndex((argument) => !argument.startsWith("-"));
if (commandIndex < 0) return [undefined, undefined];
const command = rawArgs[commandIndex];
const subcommand = rawArgs.slice(commandIndex + 1).find((argument) => !argument.startsWith("-"));
return [command, subcommand];
}
function requireIdentifier(value: string | undefined, name: string): string {
const normalized = value?.trim() ?? "";
if (normalized.length === 0 || normalized.length > 191 || normalized.includes("\u0000")) {
throw new Error(`${name} must be a non-empty database identifier`);
}
return normalized;
}