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

@@ -0,0 +1,510 @@
#!/usr/bin/env node
import { spawnSync } from "node:child_process";
import { createHash } from "node:crypto";
import { mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { pathToFileURL } from "node:url";
import pg from "pg";
export const REPOSITORY_ROOT = path.resolve(import.meta.dirname, "..");
export const BASELINE_MANIFEST_PATH = path.join(REPOSITORY_ROOT, "prisma/baseline-legacy-manifest.json");
export const LEGACY_MIGRATION_ARCHIVE_PATH = path.join(REPOSITORY_ROOT, "prisma/baseline-legacy-migrations.tar.gz");
export const PRISMA_CLI_PATH = path.join(REPOSITORY_ROOT, "node_modules/prisma/build/index.js");
const IMPERSONATION_AUDIT_MIGRATION = "20260508140000_impersonation_audit";
const BOOKING_OVERLAP_MIGRATION = "20260717090000_ak_p16b_booking_overlap_constraint";
const TENANT_DELETION_MIGRATION = "20260721090000_ak_p21_tenant_deletion_capabilities";
const SUPPORT_RETENTION_MIGRATION = "20260721093000_ak_p21_support_retention_purge";
export const MIGRATION_TABLE_EXISTS_QUERY = `
SELECT to_regclass('public._prisma_migrations') IS NOT NULL AS "tableExists";
`;
export const MIGRATION_HISTORY_QUERY = `
SELECT
migration_name AS "name",
checksum,
finished_at AS "finishedAt",
rolled_back_at AS "rolledBackAt"
FROM public._prisma_migrations
ORDER BY started_at, id;
`;
export const LEGACY_VARIANT_CATALOG_CHECKS = [
{
id: "impersonation audit delete semantics",
migrations: [IMPERSONATION_AUDIT_MIGRATION],
query: `
SELECT
(SELECT is_nullable = 'YES'
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'ImpersonationAudit' AND column_name = 'actorUserId')
AND
(SELECT is_nullable = 'YES'
FROM information_schema.columns
WHERE table_schema = 'public' AND table_name = 'ImpersonationAudit' AND column_name = 'targetUserId')
AND
(SELECT confdeltype = 'n'
FROM pg_constraint
WHERE conrelid = 'public."ImpersonationAudit"'::regclass AND conname = 'ImpersonationAudit_actorUserId_fkey')
AND
(SELECT confdeltype = 'n'
FROM pg_constraint
WHERE conrelid = 'public."ImpersonationAudit"'::regclass AND conname = 'ImpersonationAudit_targetUserId_fkey')
AS "matches";
`,
},
{
id: "tenant-scoped booking overlap constraint",
migrations: [BOOKING_OVERLAP_MIGRATION],
query: `
SELECT COALESCE(
(SELECT pg_get_constraintdef(oid, false) LIKE '%"tenantId" WITH =%'
FROM pg_constraint
WHERE conrelid = 'public."Appointment"'::regclass AND conname = 'appointment_no_overlap'),
false
) AS "matches";
`,
},
{
id: "tenant deletion function ownership and ACLs",
migrations: [TENANT_DELETION_MIGRATION],
query: `
WITH expected(function_oid) AS (
VALUES
('public.hivegrid_purge_tenant_guarded_rows(text)'::regprocedure::oid),
('public.hivegrid_minimize_tenant_support_pii(text)'::regprocedure::oid)
)
SELECT COUNT(*) = 2
AND BOOL_AND(pg_get_userbyid(proc.proowner) = 'hivegrid_rls_definer')
AND BOOL_AND(has_function_privilege('hivegrid_worker', proc.oid, 'EXECUTE'))
AND BOOL_AND(NOT has_function_privilege('hivegrid_app', proc.oid, 'EXECUTE'))
AND BOOL_AND(NOT has_function_privilege('hivegrid_authentik_jit', proc.oid, 'EXECUTE'))
AND BOOL_AND(NOT EXISTS (
SELECT 1
FROM aclexplode(COALESCE(proc.proacl, acldefault('f', proc.proowner))) AS acl
WHERE acl.grantee = 0 AND acl.privilege_type = 'EXECUTE'
)) AS "matches"
FROM expected
JOIN pg_proc AS proc ON proc.oid = expected.function_oid;
`,
},
{
id: "support retention function ownership and ACLs",
migrations: [SUPPORT_RETENTION_MIGRATION],
query: `
SELECT pg_get_userbyid(proc.proowner) = 'hivegrid_rls_definer'
AND has_function_privilege('hivegrid_worker', proc.oid, 'EXECUTE')
AND NOT has_function_privilege('hivegrid_app', proc.oid, 'EXECUTE')
AND NOT has_function_privilege('hivegrid_authentik_jit', proc.oid, 'EXECUTE')
AND NOT EXISTS (
SELECT 1
FROM aclexplode(COALESCE(proc.proacl, acldefault('f', proc.proowner))) AS acl
WHERE acl.grantee = 0 AND acl.privilege_type = 'EXECUTE'
) AS "matches"
FROM pg_proc AS proc
WHERE proc.oid = 'public.hivegrid_purge_tenant_retained_support(text)'::regprocedure;
`,
},
];
export class BaselineAdoptionError extends Error {
constructor(message, options) {
super(message, options);
this.name = "BaselineAdoptionError";
}
}
export function readBaselineManifest(manifestPath = BASELINE_MANIFEST_PATH) {
return JSON.parse(readFileSync(manifestPath, "utf8"));
}
function assertManifest(manifest) {
if (
manifest?.version !== 1 ||
typeof manifest.baselineMigration !== "string" ||
!/^[a-f0-9]{64}$/.test(manifest.baselineChecksum ?? "") ||
!Array.isArray(manifest.migrations) ||
manifest.legacyMigrationCount !== manifest.migrations.length
) {
throw new BaselineAdoptionError("The Prisma baseline legacy manifest is malformed");
}
const names = new Set();
for (const migration of manifest.migrations) {
if (typeof migration?.name !== "string" || !/^[a-f0-9]{64}$/.test(migration.checksum ?? "") || names.has(migration.name)) {
throw new BaselineAdoptionError("The Prisma baseline legacy manifest contains an invalid or duplicate migration");
}
names.add(migration.name);
}
if (!Array.isArray(manifest.legacyChecksumVariants)) {
throw new BaselineAdoptionError("The Prisma baseline legacy manifest is missing its reviewed checksum variants");
}
const currentChecksums = new Map(manifest.migrations.map((migration) => [migration.name, migration.checksum]));
const variantKeys = new Set();
for (const variant of manifest.legacyChecksumVariants) {
const key = `${variant?.name}:${variant?.checksum}`;
if (
!names.has(variant?.name) ||
!/^[a-f0-9]{64}$/.test(variant?.checksum ?? "") ||
!/^[a-f0-9]{40}$/.test(variant?.sourceCommit ?? "") ||
currentChecksums.get(variant.name) === variant.checksum ||
variantKeys.has(key)
) {
throw new BaselineAdoptionError("The Prisma baseline legacy manifest contains an invalid checksum variant");
}
variantKeys.add(key);
}
}
function isSuccessful(row) {
return row.finishedAt != null && row.rolledBackAt == null;
}
function isUnresolvedFailure(row) {
return row.finishedAt == null && row.rolledBackAt == null;
}
function matchesReviewedChecksum(name, checksum, expectedChecksum, reviewedVariants) {
return checksum === expectedChecksum || reviewedVariants.get(name)?.has(checksum);
}
export function classifyMigrationHistory({ tableExists, rows }, manifest) {
assertManifest(manifest);
if (!tableExists) return { mode: "fresh", detail: "migration table absent" };
if (!Array.isArray(rows)) throw new BaselineAdoptionError("Prisma migration history rows are unavailable");
if (rows.some(isUnresolvedFailure)) {
throw new BaselineAdoptionError("Prisma migration history contains an unresolved failed migration");
}
const successful = rows.filter(isSuccessful);
const baselineRows = successful.filter((row) => row.name === manifest.baselineMigration);
if (baselineRows.length > 0) {
if (baselineRows.length !== 1 || baselineRows[0].checksum !== manifest.baselineChecksum) {
throw new BaselineAdoptionError("The applied Prisma baseline does not match the committed baseline checksum");
}
return { mode: "baseline", detail: "baseline already applied" };
}
if (rows.length === 0) return { mode: "fresh", detail: "migration history empty" };
const expected = new Map(manifest.migrations.map((migration) => [migration.name, migration.checksum]));
const reviewedVariants = new Map();
for (const variant of manifest.legacyChecksumVariants) {
const checksums = reviewedVariants.get(variant.name) ?? new Set();
checksums.add(variant.checksum);
reviewedVariants.set(variant.name, checksums);
}
const rowNames = new Set(rows.map((row) => row.name));
const unexpectedNames = [...rowNames].filter((name) => !expected.has(name));
if (unexpectedNames.length > 0) {
throw new BaselineAdoptionError("Prisma migration history contains entries outside the reviewed legacy chain");
}
const successfulByName = new Map();
for (const row of successful) {
const entries = successfulByName.get(row.name) ?? [];
entries.push(row);
successfulByName.set(row.name, entries);
}
const variantNames = [];
let successfulPrefixLength = 0;
let gapFound = false;
for (const [name, checksum] of expected) {
const entries = successfulByName.get(name) ?? [];
if (entries.length === 0) {
gapFound = true;
continue;
}
if (entries.length !== 1 || gapFound) {
throw new BaselineAdoptionError("Prisma migration history is not an exact legacy prefix");
}
if (!matchesReviewedChecksum(name, entries[0].checksum, checksum, reviewedVariants)) {
throw new BaselineAdoptionError(`Prisma migration history checksum differs from the reviewed legacy chain (${name})`);
}
if (entries[0].checksum !== checksum) {
variantNames.push(name);
}
successfulPrefixLength += 1;
}
if (successful.length !== successfulPrefixLength) {
throw new BaselineAdoptionError("Prisma migration history contains duplicate successful legacy entries");
}
if (successfulPrefixLength < manifest.migrations.length) {
return {
mode: "legacy-prefix",
detail: "checksum-verified legacy prefix",
variantNames,
appliedMigrationCount: successfulPrefixLength,
missingMigrations: manifest.migrations.slice(successfulPrefixLength).map((migration) => migration.name),
};
}
if (successful.length !== manifest.migrations.length) {
throw new BaselineAdoptionError("Prisma migration history has an unexpected successful legacy migration count");
}
return {
mode: "legacy",
detail: variantNames.length === 0 ? "complete reviewed legacy chain" : "complete reviewed legacy chain with historical checksums",
variantNames,
};
}
function sha256(value) {
return createHash("sha256").update(value).digest("hex");
}
export function prepareLegacyMigrationArchive({ manifest, archivePath = LEGACY_MIGRATION_ARCHIVE_PATH, spawnImpl = spawnSync, tempRoot = os.tmpdir() } = {}) {
assertManifest(manifest);
if (!/^[a-f0-9]{64}$/.test(manifest.legacyArchiveChecksum ?? "") || sha256(readFileSync(archivePath)) !== manifest.legacyArchiveChecksum) {
throw new BaselineAdoptionError("The Prisma legacy migration archive does not match the reviewed manifest");
}
const temporaryDirectory = mkdtempSync(path.join(tempRoot, "hivegrid-legacy-catch-up-"));
const cleanup = () => rmSync(temporaryDirectory, { recursive: true, force: true });
try {
const extraction = spawnImpl("tar", ["-xzf", archivePath, "-C", temporaryDirectory], {
cwd: REPOSITORY_ROOT,
stdio: "inherit",
});
if (extraction.error || extraction.status !== 0) {
throw new BaselineAdoptionError("Could not extract the reviewed Prisma legacy migration archive", {
cause: extraction.error,
});
}
const migrationsPath = path.join(temporaryDirectory, "prisma/migrations");
const migrationNames = readdirSync(migrationsPath, { withFileTypes: true })
.filter((entry) => entry.isDirectory())
.map((entry) => entry.name)
.sort();
const expectedNames = manifest.migrations.map((migration) => migration.name);
if (JSON.stringify(migrationNames) !== JSON.stringify(expectedNames)) {
throw new BaselineAdoptionError("The Prisma legacy migration archive contains an unexpected migration set");
}
for (const migration of manifest.migrations) {
const sqlPath = path.join(migrationsPath, migration.name, "migration.sql");
if (sha256(readFileSync(sqlPath)) !== migration.checksum) {
throw new BaselineAdoptionError(`The Prisma legacy migration archive checksum differs (${migration.name})`);
}
}
return { migrationsPath, cleanup };
} catch (error) {
cleanup();
throw error;
}
}
export function deployMissingLegacyMigrations({
manifest,
missingMigrations,
env = process.env,
prepareArchive = prepareLegacyMigrationArchive,
spawnImpl = spawnSync,
tempRoot = os.tmpdir(),
} = {}) {
const connectionString = env.DIRECT_URL?.trim();
if (!connectionString) throw new BaselineAdoptionError("DIRECT_URL is required for Prisma legacy catch-up");
const expectedMissing = manifest.migrations.slice(manifest.migrations.length - missingMigrations.length).map((migration) => migration.name);
if (missingMigrations.length === 0 || JSON.stringify(missingMigrations) !== JSON.stringify(expectedMissing)) {
throw new BaselineAdoptionError("Prisma legacy catch-up requires the exact missing manifest suffix");
}
const prepared = prepareArchive({ manifest });
let configDirectory;
try {
configDirectory = mkdtempSync(path.join(tempRoot, "hivegrid-prisma-config-"));
const configPath = path.join(configDirectory, "prisma.config.ts");
const prismaConfigUrl = pathToFileURL(path.join(REPOSITORY_ROOT, "node_modules/prisma/config.js")).href;
writeFileSync(
configPath,
[
`import { defineConfig, env } from ${JSON.stringify(prismaConfigUrl)};`,
"",
"export default defineConfig({",
` schema: ${JSON.stringify(path.join(REPOSITORY_ROOT, "prisma/schema"))},`,
` migrations: { path: ${JSON.stringify(prepared.migrationsPath)} },`,
' datasource: { url: env("DIRECT_URL") },',
"});",
"",
].join("\n"),
{ encoding: "utf8", mode: 0o600 }
);
const result = spawnImpl(process.execPath, [PRISMA_CLI_PATH, "migrate", "deploy", "--config", configPath], {
cwd: REPOSITORY_ROOT,
env,
stdio: "inherit",
});
if (result.error || result.status !== 0) {
throw new BaselineAdoptionError("Prisma could not apply the missing reviewed legacy migration suffix", {
cause: result.error,
});
}
} finally {
if (configDirectory) rmSync(configDirectory, { recursive: true, force: true });
prepared.cleanup();
}
}
export function verifyPrismaSchemaParity({ env = process.env, spawnImpl = spawnSync } = {}) {
const result = spawnImpl(
process.execPath,
[PRISMA_CLI_PATH, "migrate", "diff", "--from-config-datasource", "--to-schema", "prisma/schema", "--exit-code", "--config", "prisma.config.ts"],
{
cwd: REPOSITORY_ROOT,
env,
stdio: "inherit",
}
);
if (result.error || result.status === 1 || result.status == null) {
throw new BaselineAdoptionError("Could not verify the live database schema after applying migrations", {
cause: result.error,
});
}
if (result.status === 2) {
throw new BaselineAdoptionError("Live database schema differs from the reviewed current Prisma schema after applying migrations");
}
if (result.status !== 0) {
throw new BaselineAdoptionError(`Live database schema verification returned unsupported exit status ${result.status}`);
}
}
export async function verifyLegacyVariantCatalog({
variantNames,
env = process.env,
clientFactory = (connectionString) => new pg.Client({ connectionString, application_name: "hivegrid-prisma-baseline-variant-verification" }),
} = {}) {
const requiredChecks = LEGACY_VARIANT_CATALOG_CHECKS.filter((check) => check.migrations.some((migration) => variantNames.includes(migration)));
if (requiredChecks.length === 0) return;
const connectionString = env.DIRECT_URL?.trim();
if (!connectionString) throw new BaselineAdoptionError("DIRECT_URL is required for Prisma baseline variant verification");
const client = clientFactory(connectionString);
try {
await client.connect();
for (const check of requiredChecks) {
const result = await client.query(check.query);
if (result.rows[0]?.matches !== true) {
throw new BaselineAdoptionError(`Live database does not satisfy the reviewed ${check.id} contract`);
}
}
} catch (error) {
if (error instanceof BaselineAdoptionError) throw error;
throw new BaselineAdoptionError("Could not verify the live database catalog before adopting historical checksums", {
cause: error,
});
} finally {
await client.end().catch(() => undefined);
}
}
export async function inspectMigrationHistory({
env = process.env,
clientFactory = (connectionString) => new pg.Client({ connectionString, application_name: "hivegrid-prisma-baseline-adoption" }),
} = {}) {
const connectionString = env.DIRECT_URL?.trim();
if (!connectionString) throw new BaselineAdoptionError("DIRECT_URL is required for Prisma baseline adoption");
const client = clientFactory(connectionString);
try {
await client.connect();
const tableState = await client.query(MIGRATION_TABLE_EXISTS_QUERY);
const tableExists = tableState.rows[0]?.tableExists === true;
if (!tableExists) return { tableExists: false, rows: [] };
const history = await client.query(MIGRATION_HISTORY_QUERY);
return { tableExists: true, rows: history.rows };
} catch (error) {
if (error instanceof BaselineAdoptionError) throw error;
throw new BaselineAdoptionError("Could not inspect Prisma migration history; inspect restricted database logs", { cause: error });
} finally {
await client.end().catch(() => undefined);
}
}
export function resolveBaselineMigration({ manifest, env = process.env, spawnImpl = spawnSync } = {}) {
const result = spawnImpl(process.execPath, [PRISMA_CLI_PATH, "migrate", "resolve", "--applied", manifest.baselineMigration, "--config", "prisma.config.ts"], {
cwd: REPOSITORY_ROOT,
env,
stdio: "inherit",
});
if (result.error || result.status !== 0) {
throw new BaselineAdoptionError("Prisma could not record the reviewed baseline migration", { cause: result.error });
}
}
export async function adoptPrismaBaseline({
manifest = readBaselineManifest(),
inspect = inspectMigrationHistory,
deployMissing = deployMissingLegacyMigrations,
verifyCatalog = verifyLegacyVariantCatalog,
resolve = resolveBaselineMigration,
stdout = process.stdout,
} = {}) {
let before = classifyMigrationHistory(await inspect(), manifest);
if (before.mode === "fresh") {
stdout.write("[baseline] fresh database; migrate deploy will apply the baseline\n");
return before;
}
if (before.mode === "baseline") {
stdout.write("[baseline] committed baseline already recorded\n");
return before;
}
if (before.mode === "legacy-prefix") {
stdout.write(
`[baseline] applying ${before.missingMigrations.length} checksum-verified legacy migration(s) after ${before.appliedMigrationCount} applied entries\n`
);
await deployMissing({ manifest, missingMigrations: before.missingMigrations });
before = classifyMigrationHistory(await inspect(), manifest);
if (before.mode !== "legacy") {
throw new BaselineAdoptionError("Prisma legacy catch-up did not produce the complete reviewed legacy chain");
}
stdout.write("[baseline] legacy migration suffix applied and verified\n");
}
if (before.variantNames.length > 0) {
stdout.write(`[baseline] verifying ${before.variantNames.length} reviewed historical checksum variant catalog contract(s)\n`);
await verifyCatalog({ variantNames: before.variantNames });
stdout.write("[baseline] security-sensitive historical catalog contracts verified\n");
}
stdout.write(`[baseline] adopting ${manifest.baselineMigration} over the checksum-verified legacy chain\n`);
await resolve({ manifest });
const after = classifyMigrationHistory(await inspect(), manifest);
if (after.mode !== "baseline") {
throw new BaselineAdoptionError("Prisma baseline adoption did not produce a verified baseline history entry");
}
stdout.write("[baseline] adoption verified\n");
return { mode: "adopted", detail: before.detail };
}
const isCli = process.argv[1] && path.join(import.meta.dirname, "adopt-prisma-baseline.mjs") === path.resolve(process.argv[1]);
if (isCli) {
try {
const args = process.argv.slice(2);
if (args.length === 0 || (args.length === 1 && args[0] === "--adopt")) {
await adoptPrismaBaseline();
} else if (args.length === 1 && args[0] === "--verify-current-schema") {
verifyPrismaSchemaParity();
process.stdout.write("[baseline] current live schema verified after migrations\n");
} else {
throw new BaselineAdoptionError("Unsupported Prisma baseline adoption argument");
}
} catch (error) {
const message = error instanceof BaselineAdoptionError ? error.message : "Prisma baseline adoption failed without a safe diagnostic";
process.stderr.write(`FAIL ${message}\n`);
process.exitCode = 1;
}
}
@@ -0,0 +1,333 @@
import { createHash } from "node:crypto";
import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { describe, expect, it, vi } from "vitest";
import {
BaselineAdoptionError,
REPOSITORY_ROOT,
adoptPrismaBaseline,
classifyMigrationHistory,
deployMissingLegacyMigrations,
resolveBaselineMigration,
verifyLegacyVariantCatalog,
verifyPrismaSchemaParity,
} from "./adopt-prisma-baseline.mjs";
const checksum = (value) => createHash("sha256").update(value).digest("hex");
const manifest = {
version: 1,
baselineMigration: "00000000000000_hivegrid_baseline",
baselineChecksum: checksum("baseline"),
legacyMigrationCount: 2,
migrations: [
{ name: "20260101000000_first", checksum: checksum("first") },
{ name: "20260102000000_second", checksum: checksum("second") },
],
legacyChecksumVariants: [
{
name: "20260101000000_first",
checksum: checksum("first-historical"),
sourceCommit: "a".repeat(40),
},
],
};
const success = (name, rowChecksum) => ({ name, checksum: rowChecksum, finishedAt: new Date(), rolledBackAt: null });
const completeLegacyHistory = {
tableExists: true,
rows: manifest.migrations.map((migration) => success(migration.name, migration.checksum)),
};
const baselineHistory = {
tableExists: true,
rows: [success(manifest.baselineMigration, manifest.baselineChecksum)],
};
describe("classifyMigrationHistory", () => {
it("keeps a database without migration history on the fresh baseline path", () => {
expect(classifyMigrationHistory({ tableExists: false, rows: [] }, manifest).mode).toBe("fresh");
expect(classifyMigrationHistory({ tableExists: true, rows: [] }, manifest).mode).toBe("fresh");
});
it("recognizes the committed baseline and permits later migration rows", () => {
const history = {
tableExists: true,
rows: [...baselineHistory.rows, success("20270101000000_later", checksum("later"))],
};
expect(classifyMigrationHistory(history, manifest).mode).toBe("baseline");
});
it("accepts exactly one successful checksum-identical copy of every legacy migration", () => {
expect(classifyMigrationHistory(completeLegacyHistory, manifest)).toEqual({
mode: "legacy",
detail: "complete reviewed legacy chain",
variantNames: [],
});
});
it("accepts only an explicitly reviewed historical checksum and reports its migration", () => {
const history = {
tableExists: true,
rows: [success(manifest.migrations[0].name, manifest.legacyChecksumVariants[0].checksum), completeLegacyHistory.rows[1]],
};
expect(classifyMigrationHistory(history, manifest)).toEqual({
mode: "legacy",
detail: "complete reviewed legacy chain with historical checksums",
variantNames: [manifest.migrations[0].name],
});
});
it("accepts a checksum-verified exact legacy prefix for catch-up", () => {
expect(classifyMigrationHistory({ tableExists: true, rows: completeLegacyHistory.rows.slice(0, 1) }, manifest)).toEqual({
mode: "legacy-prefix",
detail: "checksum-verified legacy prefix",
variantNames: [],
appliedMigrationCount: 1,
missingMigrations: ["20260102000000_second"],
});
});
it.each([
{
label: "gapped history",
history: { tableExists: true, rows: completeLegacyHistory.rows.slice(1) },
message: /not an exact legacy prefix/,
},
{
label: "duplicate successful history",
history: { tableExists: true, rows: [completeLegacyHistory.rows[0], completeLegacyHistory.rows[0]] },
message: /not an exact legacy prefix/,
},
{
label: "changed checksum",
history: { tableExists: true, rows: [success(manifest.migrations[0].name, checksum("changed")), completeLegacyHistory.rows[1]] },
message: /checksum differs/,
},
{
label: "foreign migration",
history: { tableExists: true, rows: [...completeLegacyHistory.rows, success("foreign", checksum("foreign"))] },
message: /outside the reviewed legacy chain/,
},
{
label: "unresolved failure",
history: {
tableExists: true,
rows: [...completeLegacyHistory.rows, { name: "failed", checksum: checksum("failed"), finishedAt: null, rolledBackAt: null }],
},
message: /unresolved failed migration/,
},
{
label: "changed baseline",
history: { tableExists: true, rows: [success(manifest.baselineMigration, checksum("changed"))] },
message: /baseline checksum/,
},
])("fails closed for $label", ({ history, message }) => {
expect(() => classifyMigrationHistory(history, manifest)).toThrow(message);
});
});
describe("adoptPrismaBaseline", () => {
it("does not resolve the baseline on a fresh database", async () => {
const resolve = vi.fn();
const stdout = { write: vi.fn() };
await expect(adoptPrismaBaseline({ manifest, inspect: async () => ({ tableExists: false, rows: [] }), resolve, stdout })).resolves.toMatchObject({
mode: "fresh",
});
expect(resolve).not.toHaveBeenCalled();
});
it("resolves a complete legacy chain once and verifies the resulting baseline row", async () => {
const inspect = vi.fn().mockResolvedValueOnce(completeLegacyHistory).mockResolvedValueOnce(baselineHistory);
const resolve = vi.fn();
const stdout = { write: vi.fn() };
await expect(adoptPrismaBaseline({ manifest, inspect, resolve, stdout })).resolves.toEqual({
mode: "adopted",
detail: "complete reviewed legacy chain",
});
expect(resolve).toHaveBeenCalledOnce();
expect(resolve).toHaveBeenCalledWith({ manifest });
expect(inspect).toHaveBeenCalledTimes(2);
});
it("catches up an exact legacy prefix before resolving the baseline", async () => {
const partialLegacyHistory = { tableExists: true, rows: completeLegacyHistory.rows.slice(0, 1) };
const inspect = vi.fn().mockResolvedValueOnce(partialLegacyHistory).mockResolvedValueOnce(completeLegacyHistory).mockResolvedValueOnce(baselineHistory);
const deployMissing = vi.fn();
const resolve = vi.fn();
const stdout = { write: vi.fn() };
await expect(adoptPrismaBaseline({ manifest, inspect, deployMissing, resolve, stdout })).resolves.toEqual({
mode: "adopted",
detail: "complete reviewed legacy chain",
});
expect(deployMissing).toHaveBeenCalledOnce();
expect(deployMissing).toHaveBeenCalledWith({
manifest,
missingMigrations: ["20260102000000_second"],
});
expect(deployMissing.mock.invocationCallOrder[0]).toBeLessThan(resolve.mock.invocationCallOrder[0]);
expect(inspect).toHaveBeenCalledTimes(3);
});
it("verifies security-sensitive catalog contracts before resolving a reviewed historical checksum", async () => {
const variantHistory = {
tableExists: true,
rows: [success(manifest.migrations[0].name, manifest.legacyChecksumVariants[0].checksum), completeLegacyHistory.rows[1]],
};
const inspect = vi.fn().mockResolvedValueOnce(variantHistory).mockResolvedValueOnce(baselineHistory);
const verifyCatalog = vi.fn();
const resolve = vi.fn();
await expect(adoptPrismaBaseline({ manifest, inspect, verifyCatalog, resolve, stdout: { write: vi.fn() } })).resolves.toMatchObject({
mode: "adopted",
});
expect(verifyCatalog).toHaveBeenCalledWith({ variantNames: [manifest.migrations[0].name] });
expect(verifyCatalog.mock.invocationCallOrder[0]).toBeLessThan(resolve.mock.invocationCallOrder[0]);
});
it("is a no-op after the baseline has already been recorded", async () => {
const resolve = vi.fn();
await expect(adoptPrismaBaseline({ manifest, inspect: async () => baselineHistory, resolve, stdout: { write: vi.fn() } })).resolves.toMatchObject({
mode: "baseline",
});
expect(resolve).not.toHaveBeenCalled();
});
});
describe("deployMissingLegacyMigrations", () => {
it("runs Prisma migrate deploy with a writable temporary config and an absolute Prisma config import", () => {
const cleanup = vi.fn();
const prepareArchive = vi.fn(() => ({
migrationsPath: "/tmp/reviewed-legacy/prisma/migrations",
cleanup,
}));
const tempRoot = mkdtempSync(path.join(os.tmpdir(), "hivegrid-baseline-test-"));
let configPath;
let configSource;
const spawnImpl = vi.fn((_command, args) => {
configPath = args[args.indexOf("--config") + 1];
configSource = readFileSync(configPath, "utf8");
return { status: 0 };
});
try {
expect(() =>
deployMissingLegacyMigrations({
manifest,
missingMigrations: ["20260102000000_second"],
env: { DIRECT_URL: "postgresql://redacted" },
prepareArchive,
spawnImpl,
tempRoot,
})
).not.toThrow();
expect(prepareArchive).toHaveBeenCalledWith({ manifest });
expect(spawnImpl).toHaveBeenCalledWith(
process.execPath,
expect.arrayContaining(["migrate", "deploy", "--config"]),
expect.objectContaining({
env: { DIRECT_URL: "postgresql://redacted" },
stdio: "inherit",
})
);
expect(configPath).toMatch(new RegExp(`^${tempRoot.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}/hivegrid-prisma-config-`));
expect(configPath).not.toContain(REPOSITORY_ROOT);
expect(configSource).toContain(`file://${path.join(REPOSITORY_ROOT, "node_modules/prisma/config.js")}`);
expect(existsSync(configPath)).toBe(false);
expect(cleanup).toHaveBeenCalledOnce();
} finally {
rmSync(tempRoot, { recursive: true, force: true });
}
});
it("rejects anything other than the exact missing manifest suffix", () => {
expect(() =>
deployMissingLegacyMigrations({
manifest,
missingMigrations: ["20260101000000_first"],
env: { DIRECT_URL: "postgresql://redacted" },
prepareArchive: vi.fn(),
})
).toThrow(/exact missing manifest suffix/);
});
});
describe("resolveBaselineMigration", () => {
it("runs the installed Prisma CLI without a package manager", () => {
const spawnImpl = vi.fn(() => ({ status: 0 }));
resolveBaselineMigration({ manifest, env: { DIRECT_URL: "postgresql://redacted" }, spawnImpl });
expect(spawnImpl).toHaveBeenCalledWith(
process.execPath,
expect.arrayContaining(["migrate", "resolve", "--applied", manifest.baselineMigration, "--config", "prisma.config.ts"]),
expect.objectContaining({ stdio: "inherit" })
);
});
it("fails closed when Prisma resolve fails", () => {
expect(() => resolveBaselineMigration({ manifest, spawnImpl: () => ({ status: 1 }) })).toThrow(BaselineAdoptionError);
});
});
describe("verifyPrismaSchemaParity", () => {
it("compares the configured live datasource with the committed Prisma schema", () => {
const spawnImpl = vi.fn(() => ({ status: 0 }));
verifyPrismaSchemaParity({ env: { DIRECT_URL: "postgresql://redacted" }, spawnImpl });
expect(spawnImpl).toHaveBeenCalledWith(
process.execPath,
expect.arrayContaining(["migrate", "diff", "--from-config-datasource", "--to-schema", "prisma/schema", "--exit-code"]),
expect.objectContaining({ stdio: "inherit" })
);
});
it.each([
{ status: 1, message: /Could not verify/ },
{ status: 2, message: /differs from the reviewed current Prisma schema/ },
{ status: 3, message: /unsupported exit status 3/ },
])("fails closed for Prisma diff exit $status", ({ status, message }) => {
expect(() => verifyPrismaSchemaParity({ spawnImpl: () => ({ status }) })).toThrow(message);
});
});
describe("verifyLegacyVariantCatalog", () => {
it("does not open a database connection for variants without an extra raw-SQL contract", async () => {
const clientFactory = vi.fn();
await expect(verifyLegacyVariantCatalog({ variantNames: ["20260517200000_08_capacitor_device_tokens"], clientFactory })).resolves.toBeUndefined();
expect(clientFactory).not.toHaveBeenCalled();
});
it("fails closed when a security-sensitive historical variant does not match the live catalog", async () => {
const client = {
connect: vi.fn(),
query: vi.fn().mockResolvedValue({ rows: [{ matches: false }] }),
end: vi.fn().mockResolvedValue(undefined),
};
await expect(
verifyLegacyVariantCatalog({
variantNames: ["20260717090000_ak_p16b_booking_overlap_constraint"],
env: { DIRECT_URL: "postgresql://redacted" },
clientFactory: () => client,
})
).rejects.toThrow(/tenant-scoped booking overlap constraint/);
expect(client.end).toHaveBeenCalledOnce();
});
it("accepts a security-sensitive historical variant only after the catalog contract passes", async () => {
const client = {
connect: vi.fn(),
query: vi.fn().mockResolvedValue({ rows: [{ matches: true }] }),
end: vi.fn().mockResolvedValue(undefined),
};
await expect(
verifyLegacyVariantCatalog({
variantNames: ["20260721093000_ak_p21_support_retention_purge"],
env: { DIRECT_URL: "postgresql://redacted" },
clientFactory: () => client,
})
).resolves.toBeUndefined();
expect(client.query).toHaveBeenCalledOnce();
});
});
@@ -0,0 +1,60 @@
import "dotenv/config";
import { pathToFileURL } from "node:url";
const LOCAL_DATABASE_HOSTS = new Set(["127.0.0.1", "::1", "localhost"]);
const POSTGRES_PROTOCOLS = new Set(["postgres:", "postgresql:"]);
const PROTECTED_ENVIRONMENTS = new Set(["production", "staging"]);
export function assertPortalLegacyCommerceRecutEnvironment(env = process.env) {
if (env.HIVEGRID_ALLOW_PORTAL_LEGACY_RECUT_DB_PUSH !== "1") {
throw new Error(
"Set HIVEGRID_ALLOW_PORTAL_LEGACY_RECUT_DB_PUSH=1 for the explicit local/CI feature-branch recut",
);
}
const nodeEnvironment = env.NODE_ENV?.trim().toLowerCase();
const sentryEnvironment = env.SENTRY_ENVIRONMENT?.trim().toLowerCase();
if (
(nodeEnvironment && PROTECTED_ENVIRONMENTS.has(nodeEnvironment)) ||
(sentryEnvironment && PROTECTED_ENVIRONMENTS.has(sentryEnvironment))
) {
throw new Error("The VA-P26a feature-branch recut is forbidden in staging and production");
}
const databaseUrl = env.DIRECT_URL || env.DATABASE_URL;
if (!databaseUrl) {
throw new Error("DIRECT_URL or DATABASE_URL is required for the VA-P26a recut");
}
let parsedUrl;
try {
parsedUrl = new URL(databaseUrl);
} catch {
throw new Error("The VA-P26a recut database URL is invalid");
}
if (!POSTGRES_PROTOCOLS.has(parsedUrl.protocol)) {
throw new Error("The VA-P26a recut requires a PostgreSQL database URL");
}
if (!LOCAL_DATABASE_HOSTS.has(parsedUrl.hostname)) {
throw new Error("The VA-P26a recut is restricted to a loopback local/CI database");
}
return Object.freeze({ hostname: parsedUrl.hostname });
}
function isDirectExecution() {
return Boolean(process.argv[1]) && import.meta.url === pathToFileURL(process.argv[1]).href;
}
if (isDirectExecution()) {
try {
assertPortalLegacyCommerceRecutEnvironment();
process.stdout.write("OK VA-P26a local/CI legacy-commerce recut guard\n");
} catch (error) {
const message = error instanceof Error ? error.message : "unknown recut guard failure";
process.stderr.write(`FAIL ${message}\n`);
process.exitCode = 1;
}
}
@@ -0,0 +1,124 @@
import { describe, expect, it } from "vitest";
import { assessLagoCatalog, buildDesiredLagoCatalog, toLagoPlanPayload, toLagoTaxPayload, type LagoCatalogSnapshot } from "./catalog";
const desired = buildDesiredLagoCatalog();
function matchingSnapshot(): LagoCatalogSnapshot {
return {
organization: { name: "HiveGrid Test", idSha256: "a".repeat(64) },
tax: {
code: desired.tax.code,
name: desired.tax.name,
description: desired.tax.description,
rate: desired.tax.rate,
applied_to_organization: desired.tax.appliedToOrganization,
},
plans: desired.plans.map((plan) => ({
code: plan.code,
name: plan.name,
invoice_display_name: plan.invoiceDisplayName,
description: plan.description,
interval: plan.interval,
amount_cents: plan.amountCents,
amount_currency: plan.amountCurrency,
pay_in_advance: plan.payInAdvance,
taxes: plan.taxCodes.map((code) => ({ code })),
metadata: { ...plan.metadata },
})),
};
}
describe("HiveGrid Lago billing catalog", () => {
it("builds base plans, recurring storage products, and five email-marketing tiers", () => {
expect(desired.plans.map((plan) => plan.code)).toEqual([
"business",
"business_annual_sepa",
"email_marketing_l",
"email_marketing_m",
"email_marketing_s",
"email_marketing_xl",
"email_marketing_xxl",
"pro",
"pro_annual_sepa",
"starter",
"starter_annual_sepa",
"storage_100gb",
"storage_1tb",
"storage_500gb",
"storage_5tb",
]);
expect(desired.plans.every((plan) => plan.interval === "monthly")).toBe(true);
expect(desired.plans.every((plan) => plan.taxCodes.includes("de-vat-19"))).toBe(true);
expect(desired.plans.find((plan) => plan.code === "email_marketing_m")).toMatchObject({
amountCents: 14_900,
metadata: {
hivegrid_resource_kind: "email_marketing_add_on",
hivegrid_monthly_email_limit: "50000",
},
});
expect(desired.plans.find((plan) => plan.code === "pro")).toMatchObject({
metadata: {
hivegrid_included_storage_gb: "500",
hivegrid_storage_per_additional_seat_gb: "20",
},
});
expect(desired.plans.find((plan) => plan.code === "storage_1tb")).toMatchObject({
amountCents: 1_299,
metadata: {
hivegrid_resource_kind: "storage_add_on",
hivegrid_included_storage_gb: "1000",
hivegrid_purchasable: "true",
},
});
expect(desired.plans.find((plan) => plan.code === "storage_100gb")).toMatchObject({
amountCents: 125,
metadata: {
hivegrid_resource_kind: "storage_add_on",
hivegrid_included_storage_gb: "100",
hivegrid_purchasable: "false",
},
});
});
it("produces a deterministic machine-readable contract digest", () => {
expect(buildDesiredLagoCatalog()).toEqual(desired);
expect(desired.digestSha256).toMatch(/^[a-f0-9]{64}$/u);
});
it("reports a complete idempotent catalog as noops", () => {
const assessment = assessLagoCatalog(matchingSnapshot());
expect(assessment.complete).toBe(true);
expect(assessment.actions.every((action) => action.action === "noop")).toBe(true);
});
it("detects price, tax, and catalog-version drift", () => {
const snapshot = matchingSnapshot();
snapshot.tax!.rate = 7;
snapshot.plans[0]!.amount_cents += 1;
snapshot.plans[1]!.metadata = {
...snapshot.plans[1]!.metadata,
hivegrid_catalog_version: "old",
};
const assessment = assessLagoCatalog(snapshot);
expect(assessment.complete).toBe(false);
expect(assessment.actions.find((action) => action.resource === "tax")?.driftFields).toContain("rate");
expect(assessment.actions.find((action) => action.code === snapshot.plans[0]!.code)?.driftFields).toContain("amountCents");
expect(assessment.actions.find((action) => action.code === snapshot.plans[1]!.code)?.driftFields).toContain("metadata");
});
it("creates explicit Lago tax and non-cascading plan update payloads", () => {
expect(toLagoTaxPayload(desired.tax)).toMatchObject({
tax: { code: "de-vat-19", rate: 19, applied_to_organization: false },
});
expect(toLagoPlanPayload(desired.plans[0]!, true)).toMatchObject({
plan: {
interval: "monthly",
amount_currency: "EUR",
tax_codes: ["de-vat-19"],
cascade_updates: false,
},
});
});
});
@@ -0,0 +1,318 @@
import { createHash } from "node:crypto";
import { emailMarketingCommercialProducts, hiveGridBasePlans, hiveGridBillingCatalogVersion, hiveGridStorageAddOns, hiveGridVat } from "@hivegrid/entitlements";
import { z } from "zod";
const CURRENCY = "EUR";
export const billingCatalogResourceKinds = Object.freeze({
basePlan: "base_plan",
emailMarketingAddOn: "email_marketing_add_on",
storageAddOn: "storage_add_on",
} as const);
export type BillingCatalogResourceKind = (typeof billingCatalogResourceKinds)[keyof typeof billingCatalogResourceKinds];
export type DesiredLagoTax = {
readonly code: string;
readonly name: string;
readonly description: string;
readonly rate: number;
readonly appliedToOrganization: boolean;
};
export type DesiredLagoPlan = {
readonly code: string;
readonly name: string;
readonly invoiceDisplayName: string;
readonly description: string;
readonly interval: "monthly";
readonly amountCents: number;
readonly amountCurrency: typeof CURRENCY;
readonly payInAdvance: true;
readonly taxCodes: readonly string[];
readonly metadata: Readonly<Record<string, string>>;
};
export type DesiredLagoCatalog = {
readonly version: string;
readonly digestSha256: string;
readonly tax: DesiredLagoTax;
readonly plans: readonly DesiredLagoPlan[];
};
function desiredPlan(input: {
code: string;
name: string;
description: string;
amountCents: number;
kind: BillingCatalogResourceKind;
metadata?: Readonly<Record<string, string>>;
}): DesiredLagoPlan {
return Object.freeze({
code: input.code,
name: input.name,
invoiceDisplayName: input.name,
description: `${input.description} · HiveGrid Katalog ${hiveGridBillingCatalogVersion}`,
interval: "monthly",
amountCents: input.amountCents,
amountCurrency: CURRENCY,
payInAdvance: true,
taxCodes: Object.freeze([hiveGridVat.code]),
metadata: Object.freeze({
hivegrid_catalog_version: hiveGridBillingCatalogVersion,
hivegrid_resource_kind: input.kind,
...input.metadata,
}),
});
}
function buildDesiredPlans(): readonly DesiredLagoPlan[] {
const basePlans = hiveGridBasePlans.flatMap((plan) =>
plan.variants.map((variant) =>
desiredPlan({
code: variant.code,
name: variant.contractMonths === 12 ? `${plan.publicName} · 12 Monate` : `${plan.publicName} · monatlich`,
description:
variant.contractMonths === 12 ? `${plan.publicName}, monatliche SEPA-Rate bei 12 Monaten Mindestlaufzeit` : `${plan.publicName}, monatlich kuendbar`,
amountCents: variant.baseAmountCents,
kind: billingCatalogResourceKinds.basePlan,
metadata: {
hivegrid_technical_plan_code: plan.technicalCode,
hivegrid_billing_cadence: variant.cadence,
hivegrid_contract_months: String(variant.contractMonths),
hivegrid_included_office_seats: String(plan.includedSeats.office),
hivegrid_included_field_seats: String(plan.includedSeats.field),
hivegrid_included_storage_gb: String(plan.includedStorageGb),
hivegrid_storage_per_additional_seat_gb: String(plan.storagePerAdditionalSeatGb),
hivegrid_extra_office_seat_cents: String(variant.extraSeatAmountCents.office),
hivegrid_extra_field_seat_cents: String(variant.extraSeatAmountCents.field),
},
})
)
);
const storagePlans = hiveGridStorageAddOns.map((addOn) =>
desiredPlan({
code: addOn.code,
name: addOn.publicName,
description: `${addOn.publicName}, festes wiederkehrendes Speicherpaket`,
amountCents: addOn.amountCents,
kind: billingCatalogResourceKinds.storageAddOn,
metadata: {
hivegrid_included_storage_gb: String(addOn.includedStorageGb),
hivegrid_billing_cadence: "monthly",
hivegrid_purchasable: String(addOn.purchasable),
},
})
);
const emailMarketingPlans = emailMarketingCommercialProducts.map((addOn) =>
desiredPlan({
code: addOn.code,
name: addOn.title,
description: `${addOn.title}, festes wiederkehrendes Monatskontingent`,
amountCents: addOn.amountCents!,
kind: billingCatalogResourceKinds.emailMarketingAddOn,
metadata: {
hivegrid_monthly_email_limit: String(addOn.monthlyEmailLimit),
hivegrid_billing_cadence: "monthly",
},
})
);
return Object.freeze([...basePlans, ...storagePlans, ...emailMarketingPlans].sort((left, right) => left.code.localeCompare(right.code)));
}
function stableJson(value: unknown): string {
if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
if (value !== null && typeof value === "object") {
return `{${Object.entries(value as Record<string, unknown>)
.sort(([left], [right]) => left.localeCompare(right))
.map(([key, nested]) => `${JSON.stringify(key)}:${stableJson(nested)}`)
.join(",")}}`;
}
return JSON.stringify(value);
}
export function buildDesiredLagoCatalog(): DesiredLagoCatalog {
const tax = Object.freeze({
code: hiveGridVat.code,
name: hiveGridVat.name,
description: `HiveGrid Deutschland · Katalog ${hiveGridBillingCatalogVersion}`,
rate: hiveGridVat.rateBasisPoints / 100,
appliedToOrganization: false,
});
const plans = buildDesiredPlans();
const digestInput = {
version: hiveGridBillingCatalogVersion,
tax,
plans,
};
return Object.freeze({
...digestInput,
digestSha256: createHash("sha256").update(stableJson(digestInput)).digest("hex"),
});
}
const lagoTaxSchema = z.object({
code: z.string(),
name: z.string(),
description: z.string().nullable().optional(),
rate: z.coerce.number(),
applied_to_organization: z.boolean(),
});
const lagoPlanSchema = z.object({
code: z.string(),
name: z.string(),
invoice_display_name: z.string().nullable().optional(),
description: z.string().nullable().optional(),
interval: z.string(),
amount_cents: z.number().int(),
amount_currency: z.string(),
pay_in_advance: z.boolean(),
taxes: z
.array(
z.object({
code: z.string(),
})
)
.default([]),
metadata: z.record(z.string(), z.unknown()).nullable().optional(),
});
export const lagoTaxResponseSchema = z.object({ tax: lagoTaxSchema });
export const lagoPlanResponseSchema = z.object({ plan: lagoPlanSchema });
export const lagoOrganizationResponseSchema = z.object({
organization: z.object({ lago_id: z.string().min(1), name: z.string().min(1) }),
});
export type LagoTaxSnapshot = z.infer<typeof lagoTaxSchema>;
export type LagoPlanSnapshot = z.infer<typeof lagoPlanSchema>;
export type LagoCatalogSnapshot = {
readonly organization: {
readonly name: string;
readonly idSha256: string;
};
readonly tax: LagoTaxSnapshot | null;
readonly plans: readonly LagoPlanSnapshot[];
};
export type LagoCatalogAction = {
readonly resource: "tax" | "plan";
readonly code: string;
readonly action: "create" | "update" | "noop";
readonly driftFields: readonly string[];
};
export type LagoCatalogAssessment = {
readonly catalogVersion: string;
readonly catalogDigestSha256: string;
readonly complete: boolean;
readonly actions: readonly LagoCatalogAction[];
};
function normalizedMetadata(metadata: Record<string, unknown> | null | undefined): Record<string, string> {
return Object.fromEntries(
Object.entries(metadata ?? {})
.filter(([, value]) => typeof value === "string")
.map(([key, value]) => [key, value as string])
.sort(([left], [right]) => left.localeCompare(right))
);
}
function differentFields(actual: Readonly<Record<string, unknown>>, desired: Readonly<Record<string, unknown>>): string[] {
return Object.keys(desired)
.filter((field) => stableJson(actual[field]) !== stableJson(desired[field]))
.sort();
}
export function assessLagoCatalog(snapshot: LagoCatalogSnapshot, desired = buildDesiredLagoCatalog()): LagoCatalogAssessment {
const taxDrift = snapshot.tax
? differentFields(
{
code: snapshot.tax.code,
name: snapshot.tax.name,
description: snapshot.tax.description ?? "",
rate: snapshot.tax.rate,
appliedToOrganization: snapshot.tax.applied_to_organization,
},
desired.tax
)
: [];
const actions: LagoCatalogAction[] = [
{
resource: "tax",
code: desired.tax.code,
action: snapshot.tax ? (taxDrift.length > 0 ? "update" : "noop") : "create",
driftFields: taxDrift,
},
];
for (const plan of desired.plans) {
const matches = snapshot.plans.filter((candidate) => candidate.code === plan.code);
if (matches.length > 1) {
throw new Error(`billing catalog: Lago returned duplicate plan code ${plan.code}`);
}
const actual = matches[0];
const driftFields = actual
? differentFields(
{
code: actual.code,
name: actual.name,
invoiceDisplayName: actual.invoice_display_name ?? "",
description: actual.description ?? "",
interval: actual.interval,
amountCents: actual.amount_cents,
amountCurrency: actual.amount_currency.toUpperCase(),
payInAdvance: actual.pay_in_advance,
taxCodes: actual.taxes.map((tax) => tax.code).sort(),
metadata: normalizedMetadata(actual.metadata),
},
plan
)
: [];
actions.push({
resource: "plan",
code: plan.code,
action: actual ? (driftFields.length > 0 ? "update" : "noop") : "create",
driftFields,
});
}
return Object.freeze({
catalogVersion: desired.version,
catalogDigestSha256: desired.digestSha256,
complete: actions.every((action) => action.action === "noop"),
actions: Object.freeze(actions),
});
}
export function toLagoTaxPayload(tax: DesiredLagoTax): Record<string, unknown> {
return {
tax: {
name: tax.name,
code: tax.code,
rate: tax.rate,
description: tax.description,
applied_to_organization: tax.appliedToOrganization,
},
};
}
export function toLagoPlanPayload(plan: DesiredLagoPlan, update: boolean): Record<string, unknown> {
return {
plan: {
name: plan.name,
code: plan.code,
invoice_display_name: plan.invoiceDisplayName,
description: plan.description,
interval: plan.interval,
amount_cents: plan.amountCents,
amount_currency: plan.amountCurrency,
pay_in_advance: plan.payInAdvance,
tax_codes: plan.taxCodes,
metadata: plan.metadata,
...(update ? { cascade_updates: false } : {}),
},
};
}
@@ -0,0 +1,44 @@
import { describe, expect, it } from "vitest";
import { hiveGridBillingCatalogVersion } from "@hivegrid/entitlements";
import { parseBillingCatalogCommand } from "./contracts";
const baseEnv = {
NODE_ENV: "production",
LAGO_API_URL: "http://127.0.0.1:3108",
LAGO_API_KEY: "lago_secret",
};
describe("billing catalog operator contracts", () => {
it("parses read-only staging plan mode with the canonical identity", () => {
expect(parseBillingCatalogCommand(["--target=staging", "--plan"], baseEnv)).toMatchObject({
target: "staging",
mode: "plan",
expectedOrganizationName: "HiveGrid Staging",
});
});
it("requires exact versioned confirmation for apply", () => {
expect(() => parseBillingCatalogCommand(["--target=staging", "--apply"], baseEnv)).toThrow(`--confirm=staging:${hiveGridBillingCatalogVersion}`);
expect(parseBillingCatalogCommand(["--target=staging", "--apply", `--confirm=staging:${hiveGridBillingCatalogVersion}`], baseEnv).mode).toBe("apply");
});
it("uses the pinned production organization identity", () => {
expect(parseBillingCatalogCommand(["--target=production", "--verify"], baseEnv)).toMatchObject({
target: "production",
expectedOrganizationName: "HiveGrid",
expectedOrganizationIdSha256: "c54f682e7528f2f1d556a5f539d6d200aa7d9163c9aec31f8fb5b21be632505e",
});
});
it("rejects unsafe runtime mode and credential-bearing URLs", () => {
expect(() => parseBillingCatalogCommand(["--target=staging"], { ...baseEnv, NODE_ENV: "development" })).toThrow("NODE_ENV must be production");
expect(() =>
parseBillingCatalogCommand(["--target=staging"], {
...baseEnv,
LAGO_API_URL: "https://user:password@lago.example.test/api/v1",
})
).toThrow("HTTP(S) origin");
});
});
@@ -0,0 +1,133 @@
import { hiveGridBillingCatalogVersion } from "@hivegrid/entitlements";
export type BillingCatalogTarget = "staging" | "production";
export type BillingCatalogMode = "plan" | "apply" | "verify";
export type BillingCatalogEnvironment = Readonly<Record<string, string | undefined>>;
export type BillingCatalogCommand = {
readonly target: BillingCatalogTarget;
readonly mode: BillingCatalogMode;
readonly lagoApiUrl: string;
readonly lagoApiKey: string;
readonly expectedOrganizationName: string;
readonly expectedOrganizationIdSha256: string;
readonly snapshotDirectory: string;
};
const STAGING_ORGANIZATION_NAME = "HiveGrid Staging";
const STAGING_ORGANIZATION_ID_SHA256 = "3b1134a731c67b704bb0b3298ce031213079966b348aa762800f9c92556085a8";
const PRODUCTION_ORGANIZATION_NAME = "HiveGrid";
const PRODUCTION_ORGANIZATION_ID_SHA256 = "c54f682e7528f2f1d556a5f539d6d200aa7d9163c9aec31f8fb5b21be632505e";
const MODE_ARGUMENTS = new Map<string, BillingCatalogMode>([
["--plan", "plan"],
["--apply", "apply"],
["--verify", "verify"],
]);
export class BillingCatalogOperatorError extends Error {
constructor(message: string) {
super(message);
this.name = "BillingCatalogOperatorError";
}
}
function required(env: BillingCatalogEnvironment, name: string): string {
const value = env[name]?.trim();
if (!value) throw new BillingCatalogOperatorError(`billing catalog: ${name} is required`);
return value;
}
function valueArgument(argv: readonly string[], name: string): string | undefined {
const prefix = `${name}=`;
const values = argv.filter((argument) => argument.startsWith(prefix)).map((argument) => argument.slice(prefix.length));
if (values.length > 1) throw new BillingCatalogOperatorError(`billing catalog: ${name} may only be provided once`);
return values[0];
}
function parseTarget(argv: readonly string[]): BillingCatalogTarget {
const target = valueArgument(argv, "--target");
if (target !== "staging" && target !== "production") {
throw new BillingCatalogOperatorError("billing catalog: --target=staging|production is required");
}
return target;
}
function parseMode(argv: readonly string[]): BillingCatalogMode {
const modes = argv.flatMap((argument) => {
const mode = MODE_ARGUMENTS.get(argument);
return mode ? [mode] : [];
});
if (modes.length > 1) throw new BillingCatalogOperatorError("billing catalog: provide exactly one mode");
return modes[0] ?? "plan";
}
function assertKnownArguments(argv: readonly string[]): void {
for (const argument of argv) {
if (MODE_ARGUMENTS.has(argument) || argument.startsWith("--target=") || argument.startsWith("--confirm=")) {
continue;
}
throw new BillingCatalogOperatorError("billing catalog: unknown argument");
}
}
function normalizeApiUrl(value: string): string {
let parsed: URL;
try {
parsed = new URL(value);
} catch {
throw new BillingCatalogOperatorError("billing catalog: LAGO_API_URL must be an absolute URL");
}
if (
!new Set(["http:", "https:"]).has(parsed.protocol) ||
parsed.username ||
parsed.password ||
parsed.search ||
parsed.hash ||
(parsed.pathname !== "" && parsed.pathname !== "/")
) {
throw new BillingCatalogOperatorError("billing catalog: LAGO_API_URL must be an HTTP(S) origin");
}
return parsed.origin;
}
function requireOrganizationContract(target: BillingCatalogTarget): { name: string; idSha256: string } {
if (target === "staging") {
return { name: STAGING_ORGANIZATION_NAME, idSha256: STAGING_ORGANIZATION_ID_SHA256 };
}
return {
name: PRODUCTION_ORGANIZATION_NAME,
idSha256: PRODUCTION_ORGANIZATION_ID_SHA256,
};
}
export function parseBillingCatalogCommand(argv: readonly string[], env: BillingCatalogEnvironment): BillingCatalogCommand {
assertKnownArguments(argv);
const target = parseTarget(argv);
const mode = parseMode(argv);
const confirmation = valueArgument(argv, "--confirm");
const expectedConfirmation = `${target}:${hiveGridBillingCatalogVersion}`;
if (mode === "apply" && confirmation !== expectedConfirmation) {
throw new BillingCatalogOperatorError(`billing catalog: apply requires --confirm=${expectedConfirmation}`);
}
if (mode !== "apply" && confirmation !== undefined) {
throw new BillingCatalogOperatorError("billing catalog: --confirm is valid only with --apply");
}
if (env.NODE_ENV?.trim() !== "production") {
throw new BillingCatalogOperatorError("billing catalog: NODE_ENV must be production so the operator path fails closed");
}
const organization = requireOrganizationContract(target);
return {
target,
mode,
lagoApiUrl: normalizeApiUrl(required(env, "LAGO_API_URL")),
lagoApiKey: required(env, "LAGO_API_KEY"),
expectedOrganizationName: organization.name,
expectedOrganizationIdSha256: organization.idSha256,
snapshotDirectory: env.HIVEGRID_BILLING_CATALOG_SNAPSHOT_DIR?.trim() || "tmp/billing-catalog-snapshots",
};
}
export function safeBillingCatalogError(error: unknown): string {
if (error instanceof BillingCatalogOperatorError) return error.message;
return "billing catalog: operator command failed; inspect redacted service logs";
}
@@ -0,0 +1,67 @@
import { createHash } from "node:crypto";
import { describe, expect, it, vi } from "vitest";
import { buildDesiredLagoCatalog } from "./catalog";
import { LagoCatalogClient } from "./lago-client";
const organizationId = "organization_test";
const organizationDigest = createHash("sha256").update(organizationId).digest("hex");
function response(status: number, body: unknown): Response {
return new Response(JSON.stringify(body), {
status,
headers: { "content-type": "application/json" },
});
}
describe("LagoCatalogClient", () => {
it("pins organization identity before every provider mutation", async () => {
const fetchImpl = vi
.fn<typeof fetch>()
.mockResolvedValueOnce(response(200, { organization: { lago_id: organizationId, name: "HiveGrid Test" } }))
.mockResolvedValueOnce(response(200, { tax: { ...buildDesiredLagoCatalog().tax } }));
const client = new LagoCatalogClient({
apiUrl: "https://lago.example.test",
apiKey: "secret",
expectedOrganizationName: "Other",
expectedOrganizationIdSha256: organizationDigest,
fetchImpl,
});
await expect(client.applyTax(buildDesiredLagoCatalog(), false)).rejects.toThrow("pinned target identity");
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
it("creates and updates plans using only redacted-safe endpoints", async () => {
const desired = buildDesiredLagoCatalog();
const fetchImpl = vi.fn<typeof fetch>().mockImplementation(async (url, init) => {
if (String(url).endsWith("/organizations")) {
return response(200, {
organization: { lago_id: organizationId, name: "HiveGrid Test" },
});
}
const requestBody = JSON.parse(String(init?.body)) as { plan: Record<string, unknown> };
return response(200, {
plan: {
...requestBody.plan,
taxes: [{ code: "de-vat-19" }],
},
});
});
const client = new LagoCatalogClient({
apiUrl: "https://lago.example.test",
apiKey: "secret",
expectedOrganizationName: "HiveGrid Test",
expectedOrganizationIdSha256: organizationDigest,
fetchImpl,
});
await client.applyPlan(desired.plans[0]!, false);
await client.applyPlan(desired.plans[1]!, true);
expect(fetchImpl.mock.calls[1]?.[0]).toBe("https://lago.example.test/api/v1/plans");
expect(fetchImpl.mock.calls[3]?.[0]).toBe(`https://lago.example.test/api/v1/plans/${desired.plans[1]!.code}`);
expect(fetchImpl.mock.calls[3]?.[1]?.method).toBe("PUT");
});
});
@@ -0,0 +1,118 @@
import { createHash } from "node:crypto";
import { z } from "zod";
import {
buildDesiredLagoCatalog,
lagoOrganizationResponseSchema,
lagoPlanResponseSchema,
lagoTaxResponseSchema,
toLagoPlanPayload,
toLagoTaxPayload,
type DesiredLagoCatalog,
type DesiredLagoPlan,
type LagoCatalogSnapshot,
} from "./catalog";
import { BillingCatalogOperatorError } from "./contracts";
const DEFAULT_TIMEOUT_MS = 10_000;
export class LagoCatalogClient {
private readonly apiUrl: string;
private readonly apiKey: string;
private readonly expectedOrganizationName: string;
private readonly expectedOrganizationIdSha256: string;
private readonly fetchImpl: typeof fetch;
private readonly timeoutMs: number;
constructor(input: {
apiUrl: string;
apiKey: string;
expectedOrganizationName: string;
expectedOrganizationIdSha256: string;
fetchImpl?: typeof fetch;
timeoutMs?: number;
}) {
this.apiUrl = input.apiUrl.replace(/\/+$/u, "");
this.apiKey = input.apiKey;
this.expectedOrganizationName = input.expectedOrganizationName;
this.expectedOrganizationIdSha256 = input.expectedOrganizationIdSha256;
this.fetchImpl = input.fetchImpl ?? fetch;
this.timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
}
async readCatalog(desired = buildDesiredLagoCatalog()): Promise<LagoCatalogSnapshot> {
const organization = await this.assertOrganization();
const [tax, ...plans] = await Promise.all([
this.request(`/taxes/${encodeURIComponent(desired.tax.code)}`, "GET", undefined, lagoTaxResponseSchema, true),
...desired.plans.map((plan) => this.request(`/plans/${encodeURIComponent(plan.code)}`, "GET", undefined, lagoPlanResponseSchema, true)),
]);
return {
organization,
tax: tax?.tax ?? null,
plans: plans.flatMap((response) => (response ? [{ ...response.plan, taxes: response.plan.taxes ?? [] }] : [])),
};
}
async applyTax(catalog: DesiredLagoCatalog, update: boolean): Promise<void> {
await this.assertOrganization();
await this.request(
update ? `/taxes/${encodeURIComponent(catalog.tax.code)}` : "/taxes",
update ? "PUT" : "POST",
toLagoTaxPayload(catalog.tax),
lagoTaxResponseSchema
);
}
async applyPlan(plan: DesiredLagoPlan, update: boolean): Promise<void> {
await this.assertOrganization();
await this.request(
update ? `/plans/${encodeURIComponent(plan.code)}` : "/plans",
update ? "PUT" : "POST",
toLagoPlanPayload(plan, update),
lagoPlanResponseSchema
);
}
private async assertOrganization(): Promise<LagoCatalogSnapshot["organization"]> {
const response = await this.request("/organizations", "GET", undefined, lagoOrganizationResponseSchema);
if (!response) throw new BillingCatalogOperatorError("billing catalog: Lago organization is unavailable");
const idSha256 = createHash("sha256").update(response.organization.lago_id).digest("hex");
if (response.organization.name !== this.expectedOrganizationName || idSha256 !== this.expectedOrganizationIdSha256) {
throw new BillingCatalogOperatorError("billing catalog: Lago organization does not match the pinned target identity");
}
return { name: response.organization.name, idSha256 };
}
private async request<T>(path: string, method: "GET" | "POST" | "PUT", body: unknown, schema: z.ZodType<T>, allowNotFound = false): Promise<T | null> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
try {
const response = await this.fetchImpl(`${this.apiUrl}/api/v1${path}`, {
method,
headers: {
authorization: `Bearer ${this.apiKey}`,
accept: "application/json",
...(body === undefined ? {} : { "content-type": "application/json" }),
},
body: body === undefined ? undefined : JSON.stringify(body),
redirect: "error",
signal: controller.signal,
});
if (allowNotFound && response.status === 404) return null;
if (!response.ok) {
throw new BillingCatalogOperatorError(`billing catalog: Lago request failed with status ${response.status}`);
}
const parsed = schema.safeParse(await response.json());
if (!parsed.success) {
throw new BillingCatalogOperatorError("billing catalog: Lago response shape is invalid");
}
return parsed.data;
} catch (error) {
if (error instanceof BillingCatalogOperatorError) throw error;
throw new BillingCatalogOperatorError("billing catalog: Lago request failed");
} finally {
clearTimeout(timeout);
}
}
}
@@ -0,0 +1,101 @@
import { chmod, mkdtemp, readFile, stat } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { describe, expect, it, vi } from "vitest";
import { buildDesiredLagoCatalog, type LagoCatalogSnapshot } from "./catalog";
import type { BillingCatalogCommand } from "./contracts";
import type { LagoCatalogClient } from "./lago-client";
import { executeBillingCatalogCommand, writeRedactedCatalogSnapshot } from "./sync";
const desired = buildDesiredLagoCatalog();
const emptySnapshot: LagoCatalogSnapshot = {
organization: { name: "HiveGrid Staging", idSha256: "a".repeat(64) },
tax: null,
plans: [],
};
function command(mode: BillingCatalogCommand["mode"], snapshotDirectory = "tmp/test"): BillingCatalogCommand {
return {
target: "staging",
mode,
lagoApiUrl: "https://lago.example.test",
lagoApiKey: "secret",
expectedOrganizationName: "HiveGrid Staging",
expectedOrganizationIdSha256: "a".repeat(64),
snapshotDirectory,
};
}
describe("billing catalog sync", () => {
it("plans without mutating and fails verify on drift", async () => {
const client = {
readCatalog: vi.fn().mockResolvedValue(emptySnapshot),
applyTax: vi.fn(),
applyPlan: vi.fn(),
} as unknown as LagoCatalogClient;
const result = await executeBillingCatalogCommand(command("plan"), client);
expect(result.complete).toBe(false);
expect(client.applyTax).not.toHaveBeenCalled();
await expect(executeBillingCatalogCommand(command("verify"), client)).rejects.toThrow("verification found missing or drifted");
});
it("applies all missing resources and proves convergence", async () => {
const directory = await mkdtemp(join(tmpdir(), "hivegrid-billing-catalog-"));
const convergedSnapshot: LagoCatalogSnapshot = {
organization: emptySnapshot.organization,
tax: {
code: desired.tax.code,
name: desired.tax.name,
description: desired.tax.description,
rate: desired.tax.rate,
applied_to_organization: desired.tax.appliedToOrganization,
},
plans: desired.plans.map((plan) => ({
code: plan.code,
name: plan.name,
invoice_display_name: plan.invoiceDisplayName,
description: plan.description,
interval: plan.interval,
amount_cents: plan.amountCents,
amount_currency: plan.amountCurrency,
pay_in_advance: plan.payInAdvance,
taxes: plan.taxCodes.map((code) => ({ code })),
metadata: { ...plan.metadata },
})),
};
const client = {
readCatalog: vi.fn().mockResolvedValueOnce(emptySnapshot).mockResolvedValueOnce(convergedSnapshot),
applyTax: vi.fn(),
applyPlan: vi.fn(),
} as unknown as LagoCatalogClient;
const result = await executeBillingCatalogCommand(command("apply", directory), client);
expect(result.complete).toBe(true);
expect(client.applyTax).toHaveBeenCalledOnce();
expect(client.applyPlan).toHaveBeenCalledTimes(desired.plans.length);
expect(result.snapshotPath).toContain(directory);
});
it("writes only redacted catalog state with owner-only permissions", async () => {
const directory = await mkdtemp(join(tmpdir(), "hivegrid-billing-snapshot-"));
await chmod(directory, 0o700);
const path = await writeRedactedCatalogSnapshot({
directory,
target: "production",
snapshot: emptySnapshot,
assessment: {
catalogVersion: desired.version,
catalogDigestSha256: desired.digestSha256,
complete: false,
actions: [],
},
now: new Date("2026-07-29T08:00:00.000Z"),
});
const contents = await readFile(path, "utf8");
expect(contents).not.toContain("secret");
expect(contents).toContain(desired.digestSha256);
expect((await stat(path)).mode & 0o777).toBe(0o600);
});
});
@@ -0,0 +1,134 @@
import { mkdir, writeFile } from "node:fs/promises";
import { dirname, resolve } from "node:path";
import { pathToFileURL } from "node:url";
import { assessLagoCatalog, buildDesiredLagoCatalog, type LagoCatalogAssessment, type LagoCatalogSnapshot } from "./catalog";
import { BillingCatalogOperatorError, parseBillingCatalogCommand, safeBillingCatalogError, type BillingCatalogCommand } from "./contracts";
import { LagoCatalogClient } from "./lago-client";
type BillingCatalogExecutionResult = {
readonly target: BillingCatalogCommand["target"];
readonly mode: BillingCatalogCommand["mode"];
readonly complete: boolean;
readonly catalogVersion: string;
readonly catalogDigestSha256: string;
readonly snapshotPath: string | null;
readonly actions: LagoCatalogAssessment["actions"];
};
function safeTimestamp(now: Date): string {
return now.toISOString().replace(/[:.]/gu, "-");
}
export async function writeRedactedCatalogSnapshot(input: {
directory: string;
target: BillingCatalogCommand["target"];
snapshot: LagoCatalogSnapshot;
assessment: LagoCatalogAssessment;
now?: Date;
}): Promise<string> {
const path = resolve(input.directory, `${input.target}-${safeTimestamp(input.now ?? new Date())}.json`);
await mkdir(dirname(path), { recursive: true, mode: 0o700 });
await writeFile(
path,
`${JSON.stringify(
{
target: input.target,
capturedAt: (input.now ?? new Date()).toISOString(),
catalogVersion: input.assessment.catalogVersion,
catalogDigestSha256: input.assessment.catalogDigestSha256,
snapshot: input.snapshot,
},
null,
2
)}\n`,
{ encoding: "utf8", mode: 0o600 }
);
return path;
}
export async function executeBillingCatalogCommand(
command: BillingCatalogCommand,
client = new LagoCatalogClient({
apiUrl: command.lagoApiUrl,
apiKey: command.lagoApiKey,
expectedOrganizationName: command.expectedOrganizationName,
expectedOrganizationIdSha256: command.expectedOrganizationIdSha256,
})
): Promise<BillingCatalogExecutionResult> {
const desired = buildDesiredLagoCatalog();
const initialSnapshot = await client.readCatalog(desired);
const initialAssessment = assessLagoCatalog(initialSnapshot, desired);
if (command.mode === "plan") {
return {
target: command.target,
mode: command.mode,
complete: initialAssessment.complete,
catalogVersion: desired.version,
catalogDigestSha256: desired.digestSha256,
snapshotPath: null,
actions: initialAssessment.actions,
};
}
if (command.mode === "verify") {
if (!initialAssessment.complete) {
throw new BillingCatalogOperatorError("billing catalog: verification found missing or drifted Lago resources");
}
return {
target: command.target,
mode: command.mode,
complete: true,
catalogVersion: desired.version,
catalogDigestSha256: desired.digestSha256,
snapshotPath: null,
actions: initialAssessment.actions,
};
}
const snapshotPath = await writeRedactedCatalogSnapshot({
directory: command.snapshotDirectory,
target: command.target,
snapshot: initialSnapshot,
assessment: initialAssessment,
});
for (const action of initialAssessment.actions) {
if (action.action === "noop") continue;
if (action.resource === "tax") {
await client.applyTax(desired, action.action === "update");
continue;
}
const plan = desired.plans.find((candidate) => candidate.code === action.code);
if (!plan) throw new BillingCatalogOperatorError("billing catalog: desired Lago plan is unavailable");
await client.applyPlan(plan, action.action === "update");
}
const finalAssessment = assessLagoCatalog(await client.readCatalog(desired), desired);
if (!finalAssessment.complete) {
throw new BillingCatalogOperatorError("billing catalog: apply did not converge to the canonical contract");
}
return {
target: command.target,
mode: command.mode,
complete: true,
catalogVersion: desired.version,
catalogDigestSha256: desired.digestSha256,
snapshotPath,
actions: finalAssessment.actions,
};
}
async function main(): Promise<void> {
try {
const command = parseBillingCatalogCommand(process.argv.slice(2), process.env);
const result = await executeBillingCatalogCommand(command);
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
} catch (error) {
process.stderr.write(`${safeBillingCatalogError(error)}\n`);
process.exitCode = 1;
}
}
if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
void main();
}
@@ -3,15 +3,15 @@ import { builtinModules } from "node:module";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { build } from "esbuild";
import { precompressWebAssets, pruneUnreferencedDuplicateCss } from "./precompress-web-assets.mjs";
const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const entryPoint = path.join(rootDir, "server/server.ts");
const outputFile = path.join(rootDir, "build/server-runtime/server.js");
const nodeBuiltins = new Set([...builtinModules, ...builtinModules.map((moduleName) => `node:${moduleName}`)]);
const buildSourcemapsEnabled =
process.env.HIVEGRID_BUILD_SOURCEMAPS === "1" ||
process.env.SOURCEMAP === "true" ||
process.env.BUILD_SOURCEMAPS === "true";
const buildSourcemapsEnabled = process.env.HIVEGRID_BUILD_SOURCEMAPS === "1" || process.env.SOURCEMAP === "true" || process.env.BUILD_SOURCEMAPS === "true";
const browserCspBuildEnvKeys = ["VITE_SENTRY_DSN_WEB", "VITE_OTEL_EXPORTER_OTLP_ENDPOINT", "VITE_HOCUSPOCUS_URL"];
const browserCspBuildEnvDefines = Object.fromEntries(browserCspBuildEnvKeys.map((name) => [`process.env.${name}`, JSON.stringify(process.env[name] ?? "")]));
const externalizeRuntimeDependencies = {
name: "externalize-runtime-dependencies",
@@ -38,8 +38,9 @@ await build({
bundle: true,
platform: "node",
format: "esm",
target: "node20",
target: "node24",
sourcemap: buildSourcemapsEnabled,
define: browserCspBuildEnvDefines,
banner: {
js: 'import { createRequire as __hivegridCreateRequire } from "node:module"; const require = __hivegridCreateRequire(import.meta.url);',
},
@@ -47,6 +48,12 @@ await build({
logLevel: "warning",
});
for (const buildDirectory of ["build", "build-portal"]) {
const clientBuildDirectory = path.join(rootDir, "apps", "web", buildDirectory, "client");
await pruneUnreferencedDuplicateCss(path.join(clientBuildDirectory, "assets"));
await precompressWebAssets(clientBuildDirectory);
}
function isBarePackageSpecifier(specifier) {
return !specifier.startsWith(".") && !specifier.startsWith("/") && !specifier.startsWith("#");
}
@@ -65,6 +72,8 @@ function isExternalRuntimePackage(specifier) {
specifier.startsWith("@prisma/client/") ||
specifier === "@prisma/adapter-pg" ||
specifier.startsWith("@prisma/adapter-pg/") ||
specifier === "pg" ||
specifier.startsWith("pg/") ||
specifier === "jsonwebtoken" ||
specifier.startsWith("jsonwebtoken/") ||
specifier === "pino" ||
@@ -1,9 +1,10 @@
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import assert from "node:assert/strict";
import { describe, it } from "vitest";
const scriptSource = fs.readFileSync(path.join(path.dirname(new URL(import.meta.url).pathname), "build-web-server.mjs"), "utf8");
const scriptSource = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "build-web-server.mjs"), "utf8");
describe("build-web-server", () => {
it("bundles the server entrypoint into the production runtime artifact", () => {
@@ -11,10 +12,18 @@ describe("build-web-server", () => {
assert.match(scriptSource, /build\/server-runtime\/server\.js/);
});
it("precompresses emitted client assets at build time", () => {
assert.match(scriptSource, /precompressWebAssets/);
assert.match(scriptSource, /pruneUnreferencedDuplicateCss/);
assert.match(scriptSource, /clientBuildDirectory,\s*["']assets["']/);
assert.match(scriptSource, /\["build", "build-portal"\]/);
assert.match(scriptSource, /apps["'],\s*["']web["'],\s*buildDirectory,\s*["']client/);
});
it("pins a Node ESM esbuild output instead of a runtime tsx command", () => {
assert.match(scriptSource, /platform:\s*"node"/);
assert.match(scriptSource, /format:\s*"esm"/);
assert.match(scriptSource, /target:\s*"node20"/);
assert.match(scriptSource, /target:\s*"node24"/);
assert.match(scriptSource, /sourcemap:\s*buildSourcemapsEnabled/);
assert.match(scriptSource, /logLevel:\s*"warning"/);
assert.doesNotMatch(scriptSource, /tsx/);
@@ -28,11 +37,20 @@ describe("build-web-server", () => {
assert.doesNotMatch(scriptSource, /sourcemap:\s*true/);
});
it("embeds the public browser endpoints used by the authenticated CSP", () => {
assert.match(scriptSource, /VITE_SENTRY_DSN_WEB/);
assert.match(scriptSource, /VITE_OTEL_EXPORTER_OTLP_ENDPOINT/);
assert.match(scriptSource, /VITE_HOCUSPOCUS_URL/);
assert.match(scriptSource, /define:\s*browserCspBuildEnvDefines/);
});
it("keeps runtime packages external to avoid bundling browser or native assets", () => {
assert.match(scriptSource, /externalizeRuntimeDependencies/);
assert.match(scriptSource, /plugins:\s*\[externalizeRuntimeDependencies\]/);
assert.match(scriptSource, /function isExternalRuntimePackage/);
assert.match(scriptSource, /specifier === "react-router"/);
assert.match(scriptSource, /specifier === "@prisma\/adapter-pg"/);
assert.match(scriptSource, /specifier === "pg"/);
assert.doesNotMatch(scriptSource, /packages:\s*"external"/);
});
});
@@ -0,0 +1,47 @@
import { spawn } from "node:child_process";
import { createRequire } from "node:module";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { stageWebClientSourcemaps } from "./stage-web-sourcemaps.mjs";
import { stagePortalPublicAssets } from "./stage-portal-public-assets.mjs";
import { verifyWebBuildSurfaces } from "./verify-web-build-surfaces.mjs";
const rootDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const webDirectory = path.join(rootDirectory, "apps", "web");
const require = createRequire(import.meta.url);
const reactRouterPackageDirectory = path.dirname(require.resolve("@react-router/dev/package.json"));
const reactRouterCli = path.join(reactRouterPackageDirectory, "bin.js");
for (const surface of ["core", "portal"]) {
await runReactRouterBuild(surface);
if (surface === "portal") {
stagePortalPublicAssets(rootDirectory);
}
}
verifyWebBuildSurfaces(rootDirectory);
if (process.env.HIVEGRID_BUILD_SOURCEMAPS === "1") {
await stageWebClientSourcemaps(rootDirectory);
}
function runReactRouterBuild(surface) {
return new Promise((resolve, reject) => {
const child = spawn(process.execPath, [reactRouterCli, "build", "."], {
cwd: webDirectory,
env: {
...process.env,
HIVEGRID_RUNTIME_SURFACE: surface,
VITE_OTEL_SERVICE_NAME: surface === "portal" ? "hivegrid-portal" : process.env.VITE_OTEL_SERVICE_NAME || "hivegrid-web",
},
stdio: "inherit",
});
child.once("error", reject);
child.once("exit", (code, signal) => {
if (code === 0) {
resolve();
return;
}
reject(new Error(`React Router ${surface} build failed (${signal ?? `exit ${code}`})`));
});
});
}
@@ -0,0 +1,22 @@
import assert from "node:assert/strict";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { describe, it } from "vitest";
const scriptSource = fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), "build-web-surfaces.mjs"), "utf8");
describe("build-web-surfaces", () => {
it("builds Core and Customer Portal as separate React Router surfaces", () => {
assert.match(scriptSource, /\["core", "portal"\]/);
assert.match(scriptSource, /HIVEGRID_RUNTIME_SURFACE:\s*surface/);
assert.match(scriptSource, /surface === "portal"[\s\S]*?"hivegrid-portal"/);
assert.match(scriptSource, /process\.env\.VITE_OTEL_SERVICE_NAME \|\| "hivegrid-web"/);
assert.match(scriptSource, /reactRouterCli,\s*"build",\s*"\."/);
});
it("runs the builds sequentially and fails on either non-zero exit", () => {
assert.match(scriptSource, /for \(const surface[\s\S]+await runReactRouterBuild\(surface\)/);
assert.match(scriptSource, /React Router \$\{surface\} build failed/);
});
});
@@ -1,6 +1,6 @@
{
"$schema": "./bundle-budgets.schema.json",
"comment": "Per-route + vendor-chunk bundle size budgets in GZIP bytes. The hard raw-JS initial-payload budget lives in scripts/verify-bundle-size.mjs as BUDGETS.initial_payload_js. See docs/architecture/bundle-budgets.md.",
"comment": "Per-route, vendor and lazy-runtime bundle size budgets in GZIP bytes. Hard raw-JS group budgets live in scripts/verify-bundle-size.mjs. See docs/architecture/bundle-budgets.md.",
"default": { "limitKb": 200, "warningKb": 180 },
"routes": {
"app/$tenant/dashboard": { "limitKb": 250, "warningKb": 225 },
@@ -40,5 +40,19 @@
"vendor-workflow": { "limitKb": 200, "warningKb": 180 },
"vendor-aws-sdk": { "limitKb": 250, "warningKb": 230 },
"vendor-core-utils": { "limitKb": 60, "warningKb": 50 }
},
"lazyRuntimeChunks": {
"MonacoEditor": { "limitKb": 10, "warningKb": 8 },
"MonacoEditor.client": { "limitKb": 1000, "warningKb": 950 },
"editor.worker": { "limitKb": 90, "warningKb": 80 },
"json.worker": { "limitKb": 130, "warningKb": 120 },
"html.worker": { "limitKb": 200, "warningKb": 185 },
"css.worker": { "limitKb": 250, "warningKb": 235 },
"ts.worker": { "limitKb": 1550, "warningKb": 1520 },
"PdfJsLoader.client": { "limitKb": 20, "warningKb": 15 },
"pdf": { "limitKb": 170, "warningKb": 150 },
"pdf.min": { "limitKb": 170, "warningKb": 150 },
"pdf.worker": { "limitKb": 400, "warningKb": 380 },
"pdf.worker.min": { "limitKb": 400, "warningKb": 380 }
}
}
@@ -1,10 +1,10 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Bundle Budgets Config",
"description": "Per-route and per-vendor-chunk gzip-size budgets used by scripts/verify-bundle-size.mjs.",
"description": "Per-route, per-vendor and per-lazy-runtime gzip-size budgets used by scripts/verify-bundle-size.mjs.",
"type": "object",
"additionalProperties": false,
"required": ["default", "routes", "vendorChunks"],
"required": ["default", "routes", "vendorChunks", "lazyRuntimeChunks"],
"properties": {
"$schema": { "type": "string" },
"comment": { "type": "string" },
@@ -16,6 +16,10 @@
"vendorChunks": {
"type": "object",
"additionalProperties": { "$ref": "#/definitions/budget" }
},
"lazyRuntimeChunks": {
"type": "object",
"additionalProperties": { "$ref": "#/definitions/budget" }
}
},
"definitions": {
@@ -2,12 +2,14 @@ import { execFile } from "node:child_process";
import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { createRequire } from "node:module";
import { promisify } from "node:util";
import { describe, expect, test } from "vitest";
import { renderApiInventoryGuardResult, validateApiInventory } from "./check-api-inventory.js";
const execFileAsync = promisify(execFile);
const tsxCli = createRequire(import.meta.url).resolve("tsx/cli");
async function makeFixture() {
const root = await mkdtemp(path.join(os.tmpdir(), "api-inventory-"));
@@ -43,6 +45,25 @@ describe("api inventory guard", () => {
expect(output).not.toContain("SECRET_TOKEN_SHOULD_NOT_PRINT");
});
test("permanently blocks the removed AD-26 AI upload route", async () => {
const fixture = await makeFixture();
await writeFile(
fixture.appSourcePath,
'import { Hono } from "hono";\nconst app = new Hono();\napp.post("/v1/ai/upload", () => "must-stay-removed");\n',
"utf8",
);
const result = await validateApiInventory({ appSourcePath: fixture.appSourcePath, removedWebApiRoutesRoot: fixture.removedWebApiRoutesRoot });
expect(result.ok).toBe(false);
expect(result.violations).toContainEqual(
expect.objectContaining({
routeKey: "POST /v1/ai/upload",
surface: "hono",
}),
);
});
test("fails when removed React Router API route files are present", async () => {
const fixture = await makeFixture();
await mkdir(path.join(fixture.removedWebApiRoutesRoot, "auth"), { recursive: true });
@@ -84,7 +105,7 @@ describe("api inventory guard", () => {
});
test("CLI fails on unknown flags", async () => {
await expect(execFileAsync("pnpm", ["exec", "tsx", "scripts/check-api-inventory.ts", "--unknown"])).rejects.toMatchObject({
await expect(execFileAsync(process.execPath, [tsxCli, "scripts/check-api-inventory.ts", "--unknown"])).rejects.toMatchObject({
code: 1,
stderr: expect.stringContaining("FAIL api-inventory: unknown arguments"),
});
@@ -6,7 +6,7 @@ import { fileURLToPath } from "node:url";
import { scanApiRoutesFromFile, type ApiRouteKey } from "../tools/api-inventory/scan-api-routes.js";
export const DEPRECATED_API_ROUTE_KEYS = ["GET /v1/auth/verify-token", "GET /v1/auth/me"] as const satisfies readonly ApiRouteKey[];
export const DEPRECATED_API_ROUTE_KEYS = ["GET /v1/auth/verify-token", "GET /v1/auth/me", "POST /v1/ai/upload"] as const satisfies readonly ApiRouteKey[];
export type DeprecatedApiRouteKey = (typeof DEPRECATED_API_ROUTE_KEYS)[number];
@@ -1,6 +1,7 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { pathToFileURL } from "node:url";
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { afterEach, describe, it } from "vitest";
@@ -14,7 +15,9 @@ const ENV_FIXTURES = {
APP_NAME=HiveGrid
DATABASE_URL="postgres://{USER}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}"
SESSION_SECRET=
AUDIT_CHAIN_SECRET=
CRYPTO_SECRET=
ADMIN_CONNECTION_MASTER_KEY=
APP_BASE_DOMAIN=localhost
WEB_APP_HOST=app.localhost
ADMIN_APP_HOST=admin.localhost
@@ -35,7 +38,9 @@ SITE_KEY_EXAMPLE_SITE=
".env.local.example": `APP_NAME=HiveGrid Local
DATABASE_URL="file:./dev.db?connection_limit=1&connect_timeout=30"
SESSION_SECRET=replace-with-local-session-secret
AUDIT_CHAIN_SECRET=replace-with-local-audit-chain-secret
CRYPTO_SECRET=replace-with-local-crypto-secret
ADMIN_CONNECTION_MASTER_KEY=replace-with-local-admin-connection-key
APP_BASE_DOMAIN=localhost:3000
WEB_APP_HOST=app.localhost:3000
ADMIN_APP_HOST=admin.localhost:3000
@@ -48,7 +53,9 @@ SITE_KEY_LOCAL=replace-with-local-site-key
".env.production.example": `APP_NAME=HiveGrid
DATABASE_URL="postgres://{USER}:{PASSWORD}@{HOST}:{PORT}/{DATABASE}"
SESSION_SECRET=
AUDIT_CHAIN_SECRET=
CRYPTO_SECRET=
ADMIN_CONNECTION_MASTER_KEY=
APP_BASE_DOMAIN=your-domain.invalid
WEB_APP_HOST=app.your-domain.invalid
ADMIN_APP_HOST=admin.your-domain.invalid
@@ -68,7 +75,9 @@ BULLMQ_REDIS_URL=redis://localhost:6379/0
".env.test": `APP_NAME=HiveGrid Test
DATABASE_URL="file:./test.db?connection_limit=1&connect_timeout=30"
SESSION_SECRET=test-session-secret-placeholder
AUDIT_CHAIN_SECRET=test-audit-chain-secret-placeholder
CRYPTO_SECRET=test-crypto-secret-placeholder
ADMIN_CONNECTION_MASTER_KEY=test-admin-connection-key-placeholder
APP_BASE_DOMAIN=localhost.test
WEB_APP_HOST=app.localhost.test
ADMIN_APP_HOST=admin.localhost.test
@@ -189,7 +198,7 @@ describe("check-env-drift", () => {
const nodePath = path.resolve("node_modules");
assert.throws(
() => execFileSync(process.execPath, ["--import", path.join(nodePath, "tsx/dist/loader.mjs"), scriptPath], {
() => execFileSync(process.execPath, ["--import", pathToFileURL(path.join(nodePath, "tsx/dist/loader.mjs")).href, scriptPath], {
cwd: rootDir,
encoding: "utf8",
stdio: "pipe",
@@ -0,0 +1,10 @@
[history]
maxAge = 86400
maxEntries = 20
[worker.oci]
gc = true
reservedSpace = "2GB"
maxUsedSpace = "30GB"
minFreeSpace = "100GB"
max-parallelism = 12
@@ -0,0 +1,93 @@
#!/usr/bin/env bash
set -euo pipefail
deploy_web() {
pnpm --offline --config.inject-workspace-packages=true \
--filter @hivegrid/runtime-web deploy --prod /prod/web
}
deploy_api() {
pnpm --offline --config.inject-workspace-packages=true \
--filter @hivegrid/runtime-api deploy --prod --no-optional /prod/api
}
deploy_mcp() {
pnpm --offline --config.inject-workspace-packages=true \
--filter @hivegrid/runtime-mcp deploy --prod --no-optional /prod/mcp
}
deploy_portal_controller() {
pnpm --offline --config.inject-workspace-packages=true \
--filter @hivegrid/runtime-portal-domain-controller deploy --prod --no-optional /prod/portal-domain-controller
}
deploy_worker() {
pnpm --offline --config.inject-workspace-packages=true \
--filter @hivegrid/runtime-worker deploy --prod /prod/worker
}
tasks=(deploy_web deploy_api deploy_mcp deploy_portal_controller deploy_worker)
targets=(web api mcp portal-domain-controller worker)
mkdir -p /prod
run_wave() {
local phase="$1"
local status=0
local child_status
local index
local task
local -a pids=()
for task in "${tasks[@]}"; do
echo "[production-deps] START phase=${phase} task=${task}" >&2
"$task" &
pids+=("$!")
done
# Always reap every child. A quick failure must not leave another deploy
# writing into /prod while the fallback cleans or retries the closures.
for index in "${!pids[@]}"; do
if wait "${pids[$index]}"; then
echo "[production-deps] PASS phase=${phase} task=${tasks[$index]}" >&2
continue
else
child_status=$?
fi
echo "[production-deps] FAIL phase=${phase} task=${tasks[$index]} exit_code=${child_status}" >&2
if [[ "$status" -eq 0 ]]; then
status="$child_status"
fi
done
return "$status"
}
initial_status=0
run_wave offline-first || initial_status=$?
if [[ "$initial_status" -eq 0 ]]; then
echo "[production-deps] READY source=warm-store" >&2
exit 0
fi
echo "[production-deps] REFRESH initial_exit_code=${initial_status}" >&2
for target in "${targets[@]}"; do
rm -rf -- "/prod/${target}"
done
if pnpm fetch --frozen-lockfile; then
echo "[production-deps] FETCH PASS" >&2
else
fetch_status=$?
echo "[production-deps] FETCH FAIL exit_code=${fetch_status} initial_exit_code=${initial_status}" >&2
exit "$fetch_status"
fi
retry_status=0
run_wave after-fetch || retry_status=$?
if [[ "$retry_status" -ne 0 ]]; then
echo "[production-deps] RETRY FAIL exit_code=${retry_status} initial_exit_code=${initial_status}" >&2
exit "$retry_status"
fi
echo "[production-deps] READY source=refreshed-store initial_exit_code=${initial_status}" >&2
@@ -0,0 +1,266 @@
#!/usr/bin/env bash
set -euo pipefail
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" && pwd)/docker-runtime-smoke.sh"
TARGET="${1:-all}"
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-local-$$}"
DOCKER_SMOKE_REVISION="${DOCKER_SMOKE_REVISION:-}"
DOCKER_SMOKE_BUILD_TIMEOUT_SECONDS="${DOCKER_SMOKE_BUILD_TIMEOUT_SECONDS:-1200}"
DOCKER_SMOKE_WEB_RUNTIME_TIMEOUT_SECONDS="${DOCKER_SMOKE_WEB_RUNTIME_TIMEOUT_SECONDS:-720}"
DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS="${DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS:-420}"
DOCKER_SMOKE_ARTIFACT_TIMEOUT_SECONDS="${DOCKER_SMOKE_ARTIFACT_TIMEOUT_SECONDS:-60}"
DOCKER_SMOKE_COMPOSE_TIMEOUT_SECONDS="${DOCKER_SMOKE_COMPOSE_TIMEOUT_SECONDS:-60}"
DOCKER_SMOKE_RUNTIME_GRACE_SECONDS="${DOCKER_SMOKE_RUNTIME_GRACE_SECONDS:-30}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! "$DOCKER_SMOKE_RUN_ID" =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
if [[ ! "$DOCKER_SMOKE_REVISION" =~ ^[0-9a-fA-F]{40}$ ]]; then
echo "DOCKER_SMOKE_REVISION must be a concrete 40-character Git SHA" >&2
exit 2
fi
case "$TARGET" in
all | web | worker | api | mcp | hocuspocus | portal-domain-controller) ;;
*)
echo "Docker smoke target must be one of: all, web, worker, api, mcp, hocuspocus, portal-domain-controller" >&2
exit 2
;;
esac
WEB_IMAGE="hivegrid-web:smoke-${DOCKER_SMOKE_RUN_ID}"
WORKER_IMAGE="hivegrid-worker:smoke-${DOCKER_SMOKE_RUN_ID}"
API_IMAGE="hivegrid-api:smoke-${DOCKER_SMOKE_RUN_ID}"
MCP_IMAGE="hivegrid-mcp:smoke-${DOCKER_SMOKE_RUN_ID}"
HOCUSPOCUS_IMAGE="hivegrid-hocuspocus:smoke-${DOCKER_SMOKE_RUN_ID}"
PORTAL_CONTROLLER_IMAGE="hivegrid-portal-domain-controller:smoke-${DOCKER_SMOKE_RUN_ID}"
WEB_ARTIFACT_CONTAINER_NAME="hivegrid-web-artifact-smoke-${DOCKER_SMOKE_RUN_ID}"
export DOCKER_SMOKE_RUN_ID
export DOCKER_SMOKE_REVISION
export DOCKER_SMOKE_MIGRATOR_IMAGE="$WEB_IMAGE"
export DOCKER_WEB_SMOKE_TRANSPORT="${DOCKER_WEB_SMOKE_TRANSPORT:-exec}"
export DOCKER_API_SMOKE_TRANSPORT="${DOCKER_API_SMOKE_TRANSPORT:-exec}"
export DOCKER_MCP_SMOKE_TRANSPORT="${DOCKER_MCP_SMOKE_TRANSPORT:-exec}"
export DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_REVISION="$DOCKER_SMOKE_REVISION"
cleanup() {
docker_smoke_cleanup_container "suite:cleanup:web-artifact" "$WEB_ARTIFACT_CONTAINER_NAME"
}
docker_smoke_install_cleanup_traps cleanup
cleanup
run_parallel_wave() {
local wave="$1"
local task
local index
local child_status
local status=0
local -a tasks=()
local -a pids=()
shift
if [[ "$#" -eq 0 ]]; then
echo "[docker-smoke] FAIL stage=wave:${wave} reason=no_tasks exit_code=2" >&2
return 2
fi
echo "[docker-smoke] WAVE_START wave=${wave} tasks=$#" >&2
for task in "$@"; do
tasks+=("$task")
"$task" &
pids+=("$!")
done
for index in "${!pids[@]}"; do
if wait "${pids[$index]}"; then
echo "[docker-smoke] WAVE_PASS wave=${wave} task=${tasks[$index]}" >&2
continue
else
child_status=$?
fi
echo "[docker-smoke] WAVE_FAIL wave=${wave} task=${tasks[$index]} exit_code=${child_status}" >&2
if [[ "$status" -eq 0 ]]; then
status="$child_status"
fi
done
if [[ "$status" -ne 0 ]]; then
return "$status"
fi
echo "[docker-smoke] WAVE_PASS wave=${wave} tasks=${#tasks[@]}" >&2
}
build_root_target() {
local target="$1"
local image="$2"
local build_args
build_args=(
docker build
--target "$target"
--build-arg "APP_REVISION=${DOCKER_SMOKE_REVISION}"
)
if [[ "$target" == "web" ]]; then
build_args+=(--build-arg VITE_HOCUSPOCUS_URL=wss://collab.invalid)
fi
build_args+=(--tag "$image" .)
docker_smoke_run "build:${target}" "$DOCKER_SMOKE_BUILD_TIMEOUT_SECONDS" "${build_args[@]}"
}
build_hocuspocus() {
docker_smoke_run "build:hocuspocus" "$DOCKER_SMOKE_BUILD_TIMEOUT_SECONDS" \
docker build \
--file apps/hocuspocus/Dockerfile \
--target hocuspocus \
--build-arg "APP_REVISION=${DOCKER_SMOKE_REVISION}" \
--tag "$HOCUSPOCUS_IMAGE" \
.
}
image_matches_revision() {
local image="$1"
local actual_revision=""
if ! docker_smoke_capture actual_revision "image:inspect" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$image"; then
return 1
fi
[[ "$actual_revision" == "$DOCKER_SMOKE_REVISION" ]]
}
ensure_web_migrator_image() {
if image_matches_revision "$WEB_IMAGE"; then
echo "[docker-smoke] REUSE stage=image:web revision=${DOCKER_SMOKE_REVISION}" >&2
return
fi
build_root_target web "$WEB_IMAGE"
}
validate_web() {
docker_smoke_run "artifacts:web" "$DOCKER_SMOKE_ARTIFACT_TIMEOUT_SECONDS" \
docker run --rm --name "$WEB_ARTIFACT_CONTAINER_NAME" --entrypoint /bin/sh "$WEB_IMAGE" -lc \
'test -f /myapp/apps/web/build/server/index.js && test -d /myapp/apps/web/build/client && test -f /myapp/apps/web/build-portal/server/index.js && test -d /myapp/apps/web/build-portal/client && test -f /myapp/build/server-runtime/server.js'
docker_smoke_run_with_grace "runtime:web" "$DOCKER_SMOKE_WEB_RUNTIME_TIMEOUT_SECONDS" "$DOCKER_SMOKE_RUNTIME_GRACE_SECONDS" \
bash scripts/docker-web-runtime-smoke.sh "$WEB_IMAGE"
}
build_web() {
build_root_target web "$WEB_IMAGE"
}
build_worker() {
build_root_target worker "$WORKER_IMAGE"
}
validate_worker() {
docker_smoke_run_with_grace "runtime:worker" "$DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS" "$DOCKER_SMOKE_RUNTIME_GRACE_SECONDS" \
bash scripts/docker-worker-runtime-smoke.sh "$WORKER_IMAGE"
}
build_and_validate_worker() {
build_worker
validate_worker
}
build_api() {
build_root_target api "$API_IMAGE"
}
validate_api() {
docker_smoke_run_with_grace "runtime:api" "$DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS" "$DOCKER_SMOKE_RUNTIME_GRACE_SECONDS" \
bash scripts/docker-api-runtime-smoke.sh "$API_IMAGE"
}
build_and_validate_api() {
build_api
validate_api
}
build_mcp() {
build_root_target mcp "$MCP_IMAGE"
}
validate_mcp() {
docker_smoke_run_with_grace "runtime:mcp" "$DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS" "$DOCKER_SMOKE_RUNTIME_GRACE_SECONDS" \
bash scripts/docker-mcp-runtime-smoke.sh "$MCP_IMAGE"
}
build_and_validate_mcp() {
build_mcp
validate_mcp
}
validate_hocuspocus() {
docker_smoke_run_with_grace "runtime:hocuspocus" "$DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS" "$DOCKER_SMOKE_RUNTIME_GRACE_SECONDS" \
bash scripts/docker-hocuspocus-runtime-smoke.sh "$HOCUSPOCUS_IMAGE"
}
build_and_validate_hocuspocus() {
build_hocuspocus
validate_hocuspocus
}
build_portal_controller() {
build_root_target portal-domain-controller "$PORTAL_CONTROLLER_IMAGE"
}
validate_portal_controller() {
docker_smoke_run_with_grace "runtime:portal-domain-controller" "$DOCKER_SMOKE_SERVICE_RUNTIME_TIMEOUT_SECONDS" "$DOCKER_SMOKE_RUNTIME_GRACE_SECONDS" \
bash scripts/docker-portal-domain-controller-runtime-smoke.sh "$PORTAL_CONTROLLER_IMAGE"
}
build_and_validate_portal_controller() {
build_portal_controller
validate_portal_controller
}
# Validate interpolation against a committed non-secret fixture. `--quiet`
# prevents Compose from echoing resolved developer or CI credentials.
docker_smoke_run "compose:config" "$DOCKER_SMOKE_COMPOSE_TIMEOUT_SECONDS" \
docker compose --env-file .env.test config --quiet
case "$TARGET" in
all)
# All images are complete before any service consumes the web migrator image.
run_parallel_wave builds \
build_web build_worker build_api build_mcp build_hocuspocus build_portal_controller
# Runtime resources are service- and run-scoped; their databases and Redis instances
# intentionally remain isolated while the six unchanged validations run concurrently.
run_parallel_wave runtimes \
validate_web validate_worker validate_api validate_mcp validate_hocuspocus validate_portal_controller
;;
web)
build_web
validate_web
;;
worker)
ensure_web_migrator_image
build_and_validate_worker
;;
api)
ensure_web_migrator_image
build_and_validate_api
;;
mcp)
ensure_web_migrator_image
build_and_validate_mcp
;;
hocuspocus)
ensure_web_migrator_image
build_and_validate_hocuspocus
;;
portal-domain-controller)
build_and_validate_portal_controller
;;
esac
echo "Docker smoke suite passed for target=${TARGET} revision=${DOCKER_SMOKE_REVISION} run=${DOCKER_SMOKE_RUN_ID}"
@@ -0,0 +1,38 @@
#!/usr/bin/env bash
set -euo pipefail
# Gitea's act runner does not preserve setup-node's GITHUB_PATH update between
# steps. Link the downloaded, version-pinned runtime into a stable PATH entry so
# later Node.js, Corepack, and pnpm steps cannot fall back to the runner image.
node_version="$(tr -d '[:space:]' < .nvmrc)"
node_version="${node_version#v}"
tool_cache="${RUNNER_TOOL_CACHE:-/opt/hostedtoolcache}"
install_directory="${HIVEGRID_CI_TOOL_BIN:-/usr/local/bin}"
node_binary="$(find "$tool_cache/node/$node_version" -type f -path '*/bin/node' -perm -u+x -print -quit 2>/dev/null || true)"
if [[ -z "$node_binary" ]]; then
echo "setup-node runtime $node_version was not found below $tool_cache/node" >&2
exit 1
fi
node_bin_directory="$(dirname "$node_binary")"
corepack_binary="$node_bin_directory/corepack"
if [[ ! -x "$corepack_binary" ]]; then
echo "Corepack is missing beside setup-node runtime $node_binary" >&2
exit 1
fi
if [[ ! -d "$install_directory" || ! -w "$install_directory" ]]; then
echo "Persistent tool directory $install_directory is not writable" >&2
exit 1
fi
ln -sfn "$node_binary" "$install_directory/node"
ln -sfn "$corepack_binary" "$install_directory/corepack"
actual_version="$("$install_directory/node" --version)"
if [[ "$actual_version" != "v$node_version" ]]; then
echo "Persistent Node.js runtime mismatch: expected v$node_version, got $actual_version" >&2
exit 1
fi
echo "Persisted Node.js $actual_version and Corepack in $install_directory"
@@ -0,0 +1,66 @@
import assert from "node:assert/strict";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { execFileSync, spawnSync } from "node:child_process";
import { afterEach, describe, it } from "vitest";
const scriptPath = path.resolve("scripts/ci/persist-node-toolchain.sh");
const temporaryDirectories = [];
afterEach(() => {
for (const directory of temporaryDirectories.splice(0)) {
fs.rmSync(directory, { recursive: true, force: true });
}
});
function createFixture({ reportedVersion = "v24.18.0", includeCorepack = true } = {}) {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "hivegrid-node-toolchain-"));
temporaryDirectories.push(root);
const toolCache = path.join(root, "toolcache");
const toolBin = path.join(root, "persistent-bin");
const downloadedBin = path.join(toolCache, "node", "24.18.0", "x64", "bin");
fs.mkdirSync(downloadedBin, { recursive: true });
fs.mkdirSync(toolBin, { recursive: true });
fs.writeFileSync(path.join(root, ".nvmrc"), "v24.18.0\n");
fs.writeFileSync(path.join(downloadedBin, "node"), `#!/bin/sh\nprintf '%s\\n' '${reportedVersion}'\n`, { mode: 0o755 });
if (includeCorepack) {
fs.writeFileSync(path.join(downloadedBin, "corepack"), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
}
return { root, toolCache, toolBin, downloadedBin };
}
function environment(fixture) {
return {
...process.env,
RUNNER_TOOL_CACHE: fixture.toolCache,
HIVEGRID_CI_TOOL_BIN: fixture.toolBin,
};
}
describe("persist-node-toolchain", () => {
it("links setup-node's pinned runtime into a stable tool directory", () => {
const fixture = createFixture();
execFileSync("bash", [scriptPath], { cwd: fixture.root, env: environment(fixture) });
assert.equal(fs.realpathSync(path.join(fixture.toolBin, "node")), fs.realpathSync(path.join(fixture.downloadedBin, "node")));
assert.equal(fs.realpathSync(path.join(fixture.toolBin, "corepack")), fs.realpathSync(path.join(fixture.downloadedBin, "corepack")));
});
it("fails closed when Corepack is absent from the downloaded runtime", () => {
const fixture = createFixture({ includeCorepack: false });
const result = spawnSync("bash", [scriptPath], { cwd: fixture.root, env: environment(fixture), encoding: "utf8" });
assert.equal(result.status, 1);
assert.match(result.stderr, /Corepack is missing/);
});
it("fails closed when the persisted runtime does not match .nvmrc", () => {
const fixture = createFixture({ reportedVersion: "v24.17.0" });
const result = spawnSync("bash", [scriptPath], { cwd: fixture.root, env: environment(fixture), encoding: "utf8" });
assert.equal(result.status, 1);
assert.match(result.stderr, /runtime mismatch/);
});
});
@@ -0,0 +1,94 @@
#!/usr/bin/env bash
set -euo pipefail
SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
REPO_ROOT="$(cd -- "$SCRIPT_DIR/../.." && pwd)"
cd "$REPO_ROOT"
if [[ ! -f package.json || ! -d apps || ! -d packages || ! -d prisma ]]; then
echo "[quality-groups] repository workspace is incomplete" >&2
exit 1
fi
# Web typechecking normally generates the tracked Prisma client. Complete that
# single writer before any Vitest reader starts, then run the remaining
# typecheck commands explicitly inside the parallel group below.
echo "[quality-groups] PREPARE prisma-client"
pnpm run db:generate
echo "[quality-groups] READY prisma-client"
run_typecheck_lint() {
pnpm --filter @hivegrid/portal-domain-controller typecheck
pnpm --filter @hivegrid/web typegen
(
cd apps/web
node ../../scripts/typecheck-web.mjs
)
pnpm lint
}
run_foundation_packages() {
# The CI host also builds six Docker targets in parallel. Bound both the
# Vitest pool and pnpm's recursive package fan-out so this job cannot starve
# BuildKit (or push the shared runner back into swap) while retaining the
# three-way overlap with typecheck/lint and the core suite.
pnpm run test:foundation --maxWorkers=2
PNPM_CONFIG_WORKSPACE_CONCURRENCY=2 pnpm run test:packages --maxWorkers=1
}
run_core_tests() {
pnpm run test --maxWorkers=4
}
declare -a QUALITY_GROUP_NAMES=()
declare -a QUALITY_GROUP_PIDS=()
start_group() {
local name="$1"
local function_name="$2"
(
set -euo pipefail
echo "[quality-groups] START $name"
"$function_name"
) &
QUALITY_GROUP_NAMES+=("$name")
QUALITY_GROUP_PIDS+=("$!")
}
terminate_groups() {
trap - HUP INT TERM
for pid in "${QUALITY_GROUP_PIDS[@]:-}"; do
kill -TERM "$pid" 2>/dev/null || true
done
for pid in "${QUALITY_GROUP_PIDS[@]:-}"; do
wait "$pid" 2>/dev/null || true
done
echo "[quality-groups] interrupted; child groups terminated" >&2
exit 130
}
trap terminate_groups HUP INT TERM
start_group "typecheck-lint" run_typecheck_lint
start_group "foundation-packages" run_foundation_packages
start_group "core-tests" run_core_tests
QUALITY_FAILED=0
for index in "${!QUALITY_GROUP_PIDS[@]}"; do
name="${QUALITY_GROUP_NAMES[$index]}"
pid="${QUALITY_GROUP_PIDS[$index]}"
if wait "$pid"; then
echo "[quality-groups] PASS $name"
else
status=$?
echo "[quality-groups] FAIL $name (exit $status)" >&2
QUALITY_FAILED=1
fi
done
if [[ "$QUALITY_FAILED" -ne 0 ]]; then
echo "[quality-groups] one or more groups failed" >&2
exit "$QUALITY_FAILED"
fi
echo "[quality-groups] PASS all groups"
@@ -0,0 +1,103 @@
#!/usr/bin/env node
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
function stripComment(line) {
let quote = "";
let escaped = false;
for (let index = 0; index < line.length; index += 1) {
const character = line[index];
if (escaped) {
escaped = false;
continue;
}
if (quote === '"' && character === "\\") {
escaped = true;
continue;
}
if (quote) {
if (character === quote) quote = "";
continue;
}
if (character === '"' || character === "'") {
quote = character;
continue;
}
if (character === "#") return line.slice(0, index);
}
return line;
}
function normalizeValue(rawValue) {
const value = rawValue.trim();
if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
return value.slice(1, -1);
}
return value;
}
export function parseBuildkitToml(content) {
const sections = new Map();
let currentSection = "";
for (const rawLine of content.split(/\r?\n/)) {
const line = stripComment(rawLine).trim();
if (!line) continue;
const sectionMatch = line.match(/^\[([^\]]+)\]$/);
if (sectionMatch) {
currentSection = sectionMatch[1];
if (sections.has(currentSection)) throw new Error(`duplicate section ${currentSection}`);
sections.set(currentSection, new Map());
continue;
}
const assignment = line.match(/^([A-Za-z0-9_-]+)\s*=\s*(.+)$/);
if (!assignment || !currentSection) throw new Error("unsupported deploy BuildKit TOML syntax");
const values = sections.get(currentSection);
if (values.has(assignment[1])) throw new Error(`duplicate key ${currentSection}.${assignment[1]}`);
values.set(assignment[1], normalizeValue(assignment[2]));
}
return sections;
}
export function verifyLoadedBuildkitConfig(expectedContent, actualContent) {
try {
const expected = parseBuildkitToml(expectedContent);
const actual = parseBuildkitToml(actualContent);
for (const [section, expectedValues] of expected) {
const actualValues = actual.get(section);
if (!actualValues || actualValues.size !== expectedValues.size) return false;
for (const [key, expectedValue] of expectedValues) {
if (actualValues.get(key) !== expectedValue) return false;
}
}
for (const [section, actualValues] of actual) {
if (!expected.has(section) && !(section === "worker" && actualValues.size === 0)) return false;
}
return true;
} catch {
return false;
}
}
function main() {
const expectedPath = process.argv[2];
if (!expectedPath) {
console.error("Expected deploy BuildKit config path is required");
process.exit(2);
}
const expectedContent = fs.readFileSync(path.resolve(expectedPath), "utf8");
const actualContent = fs.readFileSync(0, "utf8");
if (!verifyLoadedBuildkitConfig(expectedContent, actualContent)) {
console.error("Running deploy BuildKit configuration does not match the reviewed repository config");
process.exit(1);
}
console.log("Running deploy BuildKit configuration matches the reviewed repository config");
}
if (path.resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) main();
@@ -0,0 +1,54 @@
import { describe, expect, it } from "vitest";
import { parseBuildkitToml, verifyLoadedBuildkitConfig } from "./verify-deploy-buildkit-config.mjs";
const expected = `[history]
maxAge = 86400
maxEntries = 20
[worker.oci]
gc = true
reservedSpace = "2GB"
maxUsedSpace = "30GB"
minFreeSpace = "100GB"
max-parallelism = 12
`;
describe("verify-deploy-buildkit-config", () => {
it("accepts Buildx-normalized ordering, quotes, and its empty parent section", () => {
const actual = `[history]
maxEntries = 20
maxAge = 86400
[worker]
[worker.oci]
minFreeSpace = '100GB'
gc = true
maxUsedSpace = '30GB'
reservedSpace = '2GB'
max-parallelism = 12
`;
expect(verifyLoadedBuildkitConfig(expected, actual)).toBe(true);
});
it("rejects a changed history bound", () => {
expect(verifyLoadedBuildkitConfig(expected, expected.replace("maxEntries = 20", "maxEntries = 2000"))).toBe(false);
});
it("rejects a missing OCI cache bound", () => {
expect(verifyLoadedBuildkitConfig(expected, expected.replace(' maxUsedSpace = "30GB"\n', ""))).toBe(false);
});
it("rejects an extra setting in a reviewed section", () => {
expect(verifyLoadedBuildkitConfig(expected, expected.replace(" gc = true", " gc = true\n debug = true"))).toBe(false);
});
it("rejects an unexpected non-empty section", () => {
expect(verifyLoadedBuildkitConfig(expected, `${expected}\n[registry.\"unsafe.example\"]\n insecure = true\n`)).toBe(false);
});
it("rejects duplicate keys instead of silently selecting one", () => {
expect(() => parseBuildkitToml(expected.replace(" maxEntries = 20", " maxEntries = 20\n maxEntries = 21"))).toThrow("duplicate key history.maxEntries");
});
});
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -16,16 +16,28 @@ const prefix = environment === "production" ? "COOLIFY" : "COOLIFY_STAGING";
const apiUrl = (process.env.SELECTED_COOLIFY_API_URL || process.env[`${prefix}_API_URL`] || "").replace(/\/+$/, "");
const token = process.env.SELECTED_COOLIFY_TOKEN || process.env[`${prefix}_TOKEN`] || "";
const apiTimeoutMs = Number(process.env.COOLIFY_API_TIMEOUT_MS || "20000");
const imageTag = process.env.IMAGE_TAG || (environment === "production" ? "main" : "staging");
const registry = process.env.REGISTRY || "";
const imageNamespace = process.env.IMAGE_NAMESPACE || "";
const imagePrefix = process.env.IMAGE_PREFIX || "";
const workerImage = process.env.WORKER_IMAGE || [registry, imageNamespace, imagePrefix, "worker"].filter(Boolean).join("/");
const existingResourceUuids = process.env[`${prefix}_RESOURCE_UUIDS`] || "";
const resolvedEnvName = process.env.COOLIFY_RESOLVED_RESOURCE_UUIDS_ENV_NAME || (environment === "production" ? "PRODUCTION_RESOLVED_RESOURCE_UUIDS" : "STAGING_RESOLVED_RESOURCE_UUIDS");
const resolvedEnvName =
process.env.COOLIFY_RESOLVED_RESOURCE_UUIDS_ENV_NAME ||
(environment === "production" ? "PRODUCTION_RESOLVED_RESOURCE_UUIDS" : "STAGING_RESOLVED_RESOURCE_UUIDS");
const provisionEnabled = process.env[`${prefix}_PROVISION_WORKER_GROUPS`] === "true";
const configuredWorkerEnvSourceUuid = process.env[`${prefix}_WORKER_ENV_SOURCE_UUID`] || process.env.WORKER_ENV_SOURCE_UUID || "";
const FULL_GIT_SHA_PATTERN = /^[0-9a-f]{40}$/;
const COOLIFY_CUID_PATTERN = /^[a-z][a-z0-9]{23}$/;
const WORKER_DATABASE_ROLE = "hivegrid_worker";
class CoolifyRuntimeEnvConflictError extends Error {}
export const WORKER_ENV_OVERRIDE_KEYS = new Set([
"APP_REVISION",
"DATABASE_RUNTIME_ROLE",
"RLS_RUNTIME_MODE",
"WORKER_ENABLED",
"WORKER_QUEUE_GROUP",
"WORKER_CONCURRENCY",
@@ -50,6 +62,32 @@ export const WORKER_ENV_OVERRIDE_KEYS = new Set([
"WORKFLOW_TRIGGER_OUTBOX_REQUIRED",
]);
export const WORKER_PRIVILEGED_ENV_KEYS = new Set(["DIRECT_URL", "MIGRATOR_DATABASE_URL", "MIGRATE_ON_BOOT", "SEED_ON_BOOT", "SEED_ONCE"]);
export const WORKER_GENERAL_PROVIDER_ENV_KEYS = new Set([
"PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED",
"LAGO_API_URL",
"LAGO_API_KEY",
"LAGO_TIMEOUT_MS",
"MOLLIE_API_KEY",
"MOLLIE_PROFILE_ID",
"MOLLIE_TIMEOUT_MS",
"BILLING_MOLLIE_WEBHOOK_URL",
]);
export const KWP_WORKER_ENV_KEY = "KWP_HIVEGRID_TENANT_ID";
const KWP_WORKER_GROUP_NAMES = new Set(["general", "import"]);
const WORKER_MAIL_ONLY_ENV_KEYS = new Set(["CRYPTO_SECRET"]);
function isWorkerPrivilegedEnvKey(key) {
return WORKER_PRIVILEGED_ENV_KEYS.has(key) || key.startsWith("MIGRATOR_") || key.startsWith("SEED_");
}
function canWorkerGroupReceiveProviderEnv(group, key) {
if (key === KWP_WORKER_ENV_KEY) return KWP_WORKER_GROUP_NAMES.has(group.name);
if (WORKER_MAIL_ONLY_ENV_KEYS.has(key)) return group.name === "mail";
return group.name === "general" || !WORKER_GENERAL_PROVIDER_ENV_KEYS.has(key);
}
function fail(message) {
process.stderr.write(`${message}\n`);
process.exit(1);
@@ -63,19 +101,34 @@ function requireEnv(name) {
return value;
}
function requireCoolifyCuid(value, label) {
if (!COOLIFY_CUID_PATTERN.test(value)) {
fail(`${label} must be a valid Coolify CUID`);
}
}
async function coolify(path, options = {}) {
if (!apiUrl || !token) {
fail("Coolify API URL and token are required");
}
const response = await fetch(`${apiUrl}${path}`, {
...options,
headers: {
Authorization: `Bearer ${token}`,
Accept: "application/json",
...(options.body ? { "Content-Type": "application/json" } : {}),
...options.headers,
},
});
if (!Number.isInteger(apiTimeoutMs) || apiTimeoutMs < 10 || apiTimeoutMs > 120_000) {
fail("COOLIFY_API_TIMEOUT_MS must be an integer between 10 and 120000");
}
let response;
try {
response = await fetch(`${apiUrl}${path}`, {
...options,
signal: options.signal ?? AbortSignal.timeout(apiTimeoutMs),
headers: {
Authorization: `Bearer ${token}`,
Accept: "application/json",
...(options.body ? { "Content-Type": "application/json" } : {}),
...options.headers,
},
});
} catch {
fail("Coolify API request failed or timed out");
}
const text = await response.text();
let payload = {};
@@ -97,7 +150,7 @@ async function coolify(path, options = {}) {
function asArray(payload) {
if (Array.isArray(payload)) return payload;
if (Array.isArray(payload?.data)) return payload.data;
return [];
fail("Coolify list response was malformed");
}
function appText(app) {
@@ -126,12 +179,86 @@ function isGroupWorker(app) {
return GROUPS.some((group) => matchesWorkerGroup(app, group.name));
}
function managedWorkerDescription(group) {
return `Managed by deploy workflow. WORKER_QUEUE_GROUP=${group.name}`;
}
function hasManagedWorkerMarker(app, group) {
return app?.name === `worker-${group.name}` && app?.description === managedWorkerDescription(group);
}
function hasManagedWorkerIdentity(app, group) {
return hasManagedWorkerMarker(app, group) && app?.docker_registry_image_name === workerImage;
}
function hasManagedWorkerRetryProvenance(app, group) {
const deployedImageTag = normalizeCoolifyConfigValue(app?.docker_registry_image_tag);
if (!hasManagedWorkerIdentity(app, group) || !FULL_GIT_SHA_PATTERN.test(deployedImageTag)) {
return false;
}
return normalizeCoolifyConfigValue(app?.health_check_command) === buildWorkerDeploymentHealthCommand(deployedImageTag, group.name);
}
function isInProvisioningScope(app, scope) {
if (!scope) return false;
return (
Number(app?.environment_id) === scope.environmentId &&
app?.destination?.uuid === scope.destinationUuid &&
app?.destination?.server?.uuid === scope.serverUuid
);
}
function isInProvisioningEnvironment(app, scope) {
return Boolean(scope) && Number(app?.environment_id) === scope.environmentId;
}
async function resolveProvisioningScope() {
const projectUuid = requireEnv(`${prefix}_PROJECT_UUID`);
const serverUuid = requireEnv(`${prefix}_SERVER_UUID`);
const destinationUuid = requireEnv(`${prefix}_DESTINATION_UUID`);
const environmentUuid = process.env[`${prefix}_ENVIRONMENT_UUID`] || "";
const environmentName = process.env[`${prefix}_ENVIRONMENT_NAME`] || environment;
requireCoolifyCuid(projectUuid, `${prefix}_PROJECT_UUID`);
requireCoolifyCuid(serverUuid, `${prefix}_SERVER_UUID`);
requireCoolifyCuid(destinationUuid, `${prefix}_DESTINATION_UUID`);
if (environmentUuid) requireCoolifyCuid(environmentUuid, `${prefix}_ENVIRONMENT_UUID`);
const projectPayload = await coolify(`/projects/${encodeURIComponent(projectUuid)}`);
const project = projectPayload?.data && !Array.isArray(projectPayload.data) ? projectPayload.data : projectPayload;
if (project?.uuid !== projectUuid || !Array.isArray(project?.environments)) {
fail(`${prefix}_PROJECT_UUID response did not expose a verifiable environment scope`);
}
const matchingEnvironments = project.environments.filter((candidate) =>
environmentUuid ? candidate?.uuid === environmentUuid : candidate?.name === environmentName
);
if (matchingEnvironments.length !== 1 || !Number.isInteger(Number(matchingEnvironments[0]?.id))) {
fail(`${prefix} worker provisioning environment scope could not be resolved uniquely`);
}
return {
projectUuid,
serverUuid,
destinationUuid,
environmentUuid,
environmentName,
environmentId: Number(matchingEnvironments[0].id),
};
}
function resolveWorkerEnvSourceUuid(apps, allowed) {
if (configuredWorkerEnvSourceUuid) {
const app = apps.find((candidate) => candidate.uuid === configuredWorkerEnvSourceUuid);
if (!app) {
fail(`${prefix}_WORKER_ENV_SOURCE_UUID does not match an existing Coolify application`);
}
if (allowed.size > 0 && !allowed.has(configuredWorkerEnvSourceUuid)) {
fail(`${prefix}_WORKER_ENV_SOURCE_UUID must be included in ${prefix}_RESOURCE_UUIDS`);
}
if (app.docker_registry_image_name !== workerImage) {
fail(`${prefix}_WORKER_ENV_SOURCE_UUID must reference the exact worker image`);
}
return configuredWorkerEnvSourceUuid;
}
@@ -158,15 +285,34 @@ function envKey(entry) {
}
function envValue(entry) {
let value = typeof entry?.value === "string" ? entry.value : "";
const rawValue = entry?.value ?? entry?.real_value;
let value = typeof rawValue === "string" ? rawValue : "";
while (value.length >= 2 && ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"')))) {
value = value.slice(1, -1);
}
return value;
}
export function canonicalRuntimeEnvEntries(entries) {
const canonical = [];
const runtimeKeys = new Set();
for (const entry of entries || []) {
if (normalizeCoolifyBoolean(entry?.is_preview) === "true") continue;
const key = envKey(entry);
if (!key) continue;
if (runtimeKeys.has(key)) {
throw new CoolifyRuntimeEnvConflictError("Coolify runtime environment response contained duplicate non-preview keys");
}
runtimeKeys.add(key);
canonical.push(entry);
}
return canonical;
}
export function desiredWorkerEnv(group) {
const env = {
DATABASE_RUNTIME_ROLE: WORKER_DATABASE_ROLE,
RLS_RUNTIME_MODE: "required",
WORKER_ENABLED: "true",
WORKER_QUEUE_GROUP: group.name,
WORKER_HEALTH_PORT: group.healthPort,
@@ -194,7 +340,7 @@ export function desiredWorkerEnv(group) {
export function envEntriesToRecord(entries) {
const record = {};
for (const entry of entries || []) {
for (const entry of canonicalRuntimeEnvEntries(entries)) {
const key = envKey(entry);
if (!key) continue;
record[key] = envValue(entry);
@@ -225,11 +371,75 @@ export function getWorkerEnvDrift(app, group, entries) {
group: group.name,
}));
const sharedRuntimeDrift = getSharedWorkerRuntimeDrift(app, group, actual);
const groupRuntimeDrift = group.name === "general" ? getGeneralWorkerRuntimeDrift(app, group, actual) : [];
return [...exactDrift, ...sharedRuntimeDrift, ...groupRuntimeDrift];
const groupRuntimeDrift =
group.name === "general" ? getGeneralWorkerRuntimeDrift(app, group, actual) : group.name === "mail" ? getMailWorkerRuntimeDrift(app, group, actual) : [];
const revisionOverrideDrift = Object.hasOwn(actual, "APP_REVISION")
? [
{
key: "APP_REVISION",
expected: "unset; image-baked revision is authoritative",
actual: "<configured>",
appUuid: app?.uuid ?? "",
appName: app?.name ?? `worker-${group.name}`,
group: group.name,
},
]
: [];
const privilegedEnvDrift = Object.keys(actual)
.filter(isWorkerPrivilegedEnvKey)
.map((key) => ({
key,
expected: "unset; migration and seed credentials are forbidden in worker runtimes",
actual: "<configured>",
appUuid: app?.uuid ?? "",
appName: app?.name ?? `worker-${group.name}`,
group: group.name,
}));
const providerBoundaryDrift = Object.keys(actual)
.filter(
(key) =>
(group.name !== "general" && WORKER_GENERAL_PROVIDER_ENV_KEYS.has(key)) ||
(key === KWP_WORKER_ENV_KEY && !KWP_WORKER_GROUP_NAMES.has(group.name))
)
.map((key) => ({
key,
expected:
key === KWP_WORKER_ENV_KEY
? "unset; the KWP pilot tenant belongs only to worker-general and worker-import"
: "unset; billing provider credentials belong only to worker-general",
actual: "<configured>",
appUuid: app?.uuid ?? "",
appName: app?.name ?? `worker-${group.name}`,
group: group.name,
}));
return [...exactDrift, ...revisionOverrideDrift, ...privilegedEnvDrift, ...providerBoundaryDrift, ...sharedRuntimeDrift, ...groupRuntimeDrift];
}
export function getWorkerAppConfigDrift(app, group) {
export function buildWorkerDeploymentHealthCommand(deployedImageTag, workerGroup) {
if (!FULL_GIT_SHA_PATTERN.test(deployedImageTag)) {
throw new Error("Worker deployment health requires a full lowercase Git SHA image tag.");
}
if (!GROUPS.some((group) => group.name === workerGroup)) {
throw new Error("Worker deployment health requires a valid worker group.");
}
return `node apps/worker/dist/deploy-health.js ${deployedImageTag} ${workerGroup}`;
}
function desiredWorkerAppConfig(group, deployedImageTag) {
return {
docker_registry_image_tag: deployedImageTag,
ports_exposes: group.healthPort,
health_check_enabled: true,
health_check_type: "cmd",
health_check_command: buildWorkerDeploymentHealthCommand(deployedImageTag, group.name),
health_check_interval: 30,
health_check_timeout: 10,
health_check_retries: 3,
health_check_start_period: 20,
};
}
export function getWorkerAppConfigDrift(app, group, deployedImageTag) {
const appName = app?.name ?? `worker-${group.name}`;
const appUuid = app?.uuid ?? "";
const item = (key, expected, actual) => ({
@@ -240,19 +450,19 @@ export function getWorkerAppConfigDrift(app, group) {
appName,
group: group.name,
});
const expected = {
ports_exposes: group.healthPort,
health_check_enabled: "true",
health_check_path: "/readyz",
health_check_port: group.healthPort,
health_check_host: "127.0.0.1",
};
const desired = desiredWorkerAppConfig(group, deployedImageTag);
const expected = { ...desired, health_check_enabled: "true", custom_healthcheck_found: "false" };
const actual = {
docker_registry_image_tag: normalizeCoolifyConfigValue(app?.docker_registry_image_tag),
ports_exposes: normalizeCoolifyConfigValue(app?.ports_exposes),
health_check_enabled: normalizeCoolifyBoolean(app?.health_check_enabled),
health_check_path: normalizeCoolifyConfigValue(app?.health_check_path),
health_check_port: normalizeCoolifyConfigValue(app?.health_check_port),
health_check_host: normalizeCoolifyConfigValue(app?.health_check_host),
health_check_type: normalizeCoolifyConfigValue(app?.health_check_type),
health_check_command: normalizeCoolifyConfigValue(app?.health_check_command),
health_check_interval: Number(app?.health_check_interval),
health_check_timeout: Number(app?.health_check_timeout),
health_check_retries: Number(app?.health_check_retries),
health_check_start_period: Number(app?.health_check_start_period),
custom_healthcheck_found: normalizeCoolifyBoolean(app?.custom_healthcheck_found),
};
return Object.entries(expected)
.filter(([key, expectedValue]) => actual[key] !== expectedValue)
@@ -260,7 +470,11 @@ export function getWorkerAppConfigDrift(app, group) {
}
function normalizeCoolifyBoolean(value) {
return value === true || value === "true" || value === 1 || value === "1" ? "true" : value === false || value === "false" || value === 0 || value === "0" ? "false" : "";
return value === true || value === "true" || value === 1 || value === "1"
? "true"
: value === false || value === "false" || value === 0 || value === "0"
? "false"
: "";
}
function normalizeCoolifyConfigValue(value) {
@@ -285,14 +499,49 @@ function getSharedWorkerRuntimeDrift(app, group, actual) {
if (!hasEnvValue(actual, "DATABASE_URL")) {
drift.push(item("DATABASE_URL", "configured DATABASE_URL", "<missing>"));
} else {
let databaseRole = "";
try {
const databaseUrl = new URL(actual.DATABASE_URL);
if (databaseUrl.protocol === "postgres:" || databaseUrl.protocol === "postgresql:") {
databaseRole = decodeURIComponent(databaseUrl.username);
}
} catch {
// Invalid URLs are reported below without echoing the credential.
}
if (databaseRole !== WORKER_DATABASE_ROLE) {
drift.push(
item(
"DATABASE_URL",
`PostgreSQL DSN authenticated as ${WORKER_DATABASE_ROLE}`,
databaseRole ? "<configured with non-worker role>" : "<invalid PostgreSQL DSN>"
)
);
}
}
if (!hasEnvValue(actual, "BULLMQ_REDIS_URL")) {
drift.push(item("BULLMQ_REDIS_URL", "configured BULLMQ_REDIS_URL", actual.REDIS_URL ? "<missing; REDIS_URL fallback not accepted for managed workers>" : "<missing>"));
drift.push(
item("BULLMQ_REDIS_URL", "configured BULLMQ_REDIS_URL", actual.REDIS_URL ? "<missing; REDIS_URL fallback not accepted for managed workers>" : "<missing>")
);
}
return drift;
}
function getMailWorkerRuntimeDrift(app, group, actual) {
if (hasEnvValue(actual, "CRYPTO_SECRET")) return [];
return [
{
key: "CRYPTO_SECRET",
expected: "configured shared tenant-envelope key matching hivegrid-web",
actual: "<missing>",
appUuid: app?.uuid ?? "",
appName: app?.name ?? `worker-${group.name}`,
group: group.name,
},
];
}
function getGeneralWorkerRuntimeDrift(app, group, actual) {
const drift = [];
const item = (key, expected, actualValue) => ({
@@ -316,6 +565,53 @@ function getGeneralWorkerRuntimeDrift(app, group, actual) {
}
}
const providerGate = actual.PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED?.trim();
if (providerGate && providerGate !== "true" && providerGate !== "false") {
drift.push(item("PRODUCT_ACQUISITION_PROVIDER_SIDE_EFFECT_REQUIRED", "true, false, or unset", "<invalid>"));
}
const providerSideEffectRequired = providerGate !== "false" && (providerGate === "true" || actual.RLS_RUNTIME_MODE === "required");
if (providerSideEffectRequired) {
for (const key of ["LAGO_API_URL", "LAGO_API_KEY", "MOLLIE_API_KEY", "BILLING_MOLLIE_WEBHOOK_URL"]) {
if (!hasEnvValue(actual, key)) {
drift.push(item(key, `configured ${key}`, "<missing>"));
}
}
if (hasEnvValue(actual, "LAGO_API_URL")) {
try {
const url = new URL(actual.LAGO_API_URL);
if ((url.protocol !== "http:" && url.protocol !== "https:") || url.username || url.password) {
throw new Error("invalid provider URL");
}
} catch {
drift.push(item("LAGO_API_URL", "credential-free absolute HTTP(S) URL", "<invalid URL>"));
}
}
if (hasEnvValue(actual, "BILLING_MOLLIE_WEBHOOK_URL")) {
try {
const url = new URL(actual.BILLING_MOLLIE_WEBHOOK_URL);
if (
url.protocol !== "https:" ||
url.username ||
url.password ||
url.search ||
url.hash ||
url.pathname !== "/v1/billing/mollie/webhooks"
) {
throw new Error("invalid Mollie webhook URL");
}
} catch {
drift.push(item("BILLING_MOLLIE_WEBHOOK_URL", "canonical HTTPS Mollie webhook URL", "<invalid URL>"));
}
}
for (const key of ["LAGO_TIMEOUT_MS", "MOLLIE_TIMEOUT_MS"]) {
const value = actual[key];
const parsed = Number(value);
if (hasEnvValue(actual, key) && (!Number.isSafeInteger(parsed) || parsed <= 0)) {
drift.push(item(key, "positive integer milliseconds when configured", "<invalid>"));
}
}
}
if (actual.PLUGIN_RUNTIME_PRODUCTION_ENABLED === "true") {
if (actual.PLUGIN_HOOK_FANOUT_ENABLED === "false") {
drift.push(item("PLUGIN_HOOK_FANOUT_ENABLED", "unset or true when PLUGIN_RUNTIME_PRODUCTION_ENABLED=true", "false"));
@@ -328,18 +624,23 @@ function getGeneralWorkerRuntimeDrift(app, group, actual) {
return drift;
}
async function cloneWorkerEnv(sourceUuid, targetUuid) {
if (!sourceUuid) return;
async function cloneWorkerEnv(sourceUuid, targetUuid, group, { sourceEnvs: providedSourceEnvs, targetEnvs: providedTargetEnvs } = {}) {
if (!sourceUuid) return providedTargetEnvs || [];
const [sourceEnvs, targetEnvs] = await Promise.all([
coolify(`/applications/${encodeURIComponent(sourceUuid)}/envs`).then(asArray),
coolify(`/applications/${encodeURIComponent(targetUuid)}/envs`).then(asArray),
providedSourceEnvs ? Promise.resolve(providedSourceEnvs) : coolify(`/applications/${encodeURIComponent(sourceUuid)}/envs`).then(asArray),
providedTargetEnvs ? Promise.resolve(providedTargetEnvs) : coolify(`/applications/${encodeURIComponent(targetUuid)}/envs`).then(asArray),
]);
const targetKeys = new Set(targetEnvs.map(envKey).filter(Boolean));
const runtimeSourceEnvs = canonicalRuntimeEnvEntries(sourceEnvs);
const runtimeTargetEnvs = canonicalRuntimeEnvEntries(targetEnvs);
const targetKeys = new Set(runtimeTargetEnvs.map(envKey).filter(Boolean));
const reconciledTargetEnvs = [...runtimeTargetEnvs];
for (const entry of sourceEnvs) {
for (const entry of runtimeSourceEnvs) {
const key = envKey(entry);
if (!key || targetKeys.has(key) || WORKER_ENV_OVERRIDE_KEYS.has(key)) continue;
if (!key || targetKeys.has(key) || WORKER_ENV_OVERRIDE_KEYS.has(key) || isWorkerPrivilegedEnvKey(key) || !canWorkerGroupReceiveProviderEnv(group, key)) {
continue;
}
await coolify(`/applications/${encodeURIComponent(targetUuid)}/envs`, {
method: "POST",
@@ -347,32 +648,32 @@ async function cloneWorkerEnv(sourceUuid, targetUuid) {
key,
value: envValue(entry),
is_literal: entry.is_literal ?? true,
is_preview: entry.is_preview ?? false,
is_preview: false,
is_multiline: entry.is_multiline ?? false,
is_shown_once: entry.is_shown_once ?? false,
}),
});
targetKeys.add(key);
reconciledTargetEnvs.push({ key, value: envValue(entry), is_preview: false });
}
return reconciledTargetEnvs;
}
async function createWorkerApplication(group, workerEnvSourceUuid) {
async function createWorkerApplication(group, workerEnvSourceUuid, sourceEnvs, provisioningScope) {
if (!provisionEnabled) {
fail(`Missing Coolify worker-${group.name} application. Set ${prefix}_PROVISION_WORKER_GROUPS=true with project/server/destination variables to create it automatically.`);
fail(
`Missing Coolify worker-${group.name} application. Set ${prefix}_PROVISION_WORKER_GROUPS=true with project/server/destination variables to create it automatically.`
);
}
const projectUuid = requireEnv(`${prefix}_PROJECT_UUID`);
const serverUuid = requireEnv(`${prefix}_SERVER_UUID`);
const destinationUuid = requireEnv(`${prefix}_DESTINATION_UUID`);
const environmentUuid = process.env[`${prefix}_ENVIRONMENT_UUID`] || "";
const environmentName = process.env[`${prefix}_ENVIRONMENT_NAME`] || environment;
const body = buildWorkerApplicationBody({
group,
projectUuid,
serverUuid,
destinationUuid,
environmentName,
environmentUuid,
projectUuid: provisioningScope.projectUuid,
serverUuid: provisioningScope.serverUuid,
destinationUuid: provisioningScope.destinationUuid,
environmentName: provisioningScope.environmentName,
environmentUuid: provisioningScope.environmentUuid,
workerImage,
imageTag,
});
@@ -385,11 +686,19 @@ async function createWorkerApplication(group, workerEnvSourceUuid) {
if (!uuid) {
fail(`Coolify did not return a UUID for worker-${group.name}`);
}
requireCoolifyCuid(uuid, `Coolify worker-${group.name} UUID`);
await cloneWorkerEnv(workerEnvSourceUuid, uuid);
await ensureWorkerEnv(uuid, group);
const createdApp = await coolify(`/applications/${encodeURIComponent(uuid)}`);
if (createdApp?.uuid !== uuid || !hasManagedWorkerRetryProvenance(createdApp, group) || !isInProvisioningScope(createdApp, provisioningScope)) {
fail(`Created Coolify worker-${group.name} application identity could not be verified`);
}
assertWorkerCommandHealthCanBeAuthoritative(createdApp, group);
const targetEnvs = asArray(await coolify(`/applications/${encodeURIComponent(uuid)}/envs`));
const clonedEnvs = await cloneWorkerEnv(workerEnvSourceUuid, uuid, group, { sourceEnvs, targetEnvs });
await ensureMissingWorkerEnv(uuid, group, clonedEnvs);
process.stdout.write(`Created Coolify worker-${group.name} application\n`);
return uuid;
return createdApp;
}
export function buildWorkerApplicationBody({ group, projectUuid, serverUuid, destinationUuid, environmentName, environmentUuid = "", workerImage, imageTag }) {
@@ -401,19 +710,8 @@ export function buildWorkerApplicationBody({ group, projectUuid, serverUuid, des
docker_registry_image_tag: imageTag,
destination_uuid: destinationUuid,
name: `worker-${group.name}`,
description: `Managed by deploy workflow. WORKER_QUEUE_GROUP=${group.name}`,
ports_exposes: group.healthPort,
health_check_enabled: true,
health_check_path: "/readyz",
health_check_port: group.healthPort,
health_check_host: "127.0.0.1",
health_check_method: "GET",
health_check_return_code: 200,
health_check_scheme: "http",
health_check_interval: 30,
health_check_timeout: 5,
health_check_retries: 3,
health_check_start_period: 20,
description: managedWorkerDescription(group),
...desiredWorkerAppConfig(group, imageTag),
instant_deploy: false,
connect_to_docker_network: true,
};
@@ -423,8 +721,10 @@ export function buildWorkerApplicationBody({ group, projectUuid, serverUuid, des
return body;
}
async function ensureWorkerEnv(uuid, group) {
async function ensureMissingWorkerEnv(uuid, group, entries) {
const actual = envEntriesToRecord(entries);
for (const [key, value] of Object.entries(desiredWorkerEnv(group))) {
if (Object.hasOwn(actual, key)) continue;
await coolify(`/applications/${encodeURIComponent(uuid)}/envs`, {
method: "POST",
body: JSON.stringify({
@@ -439,13 +739,237 @@ async function ensureWorkerEnv(uuid, group) {
}
}
async function assertWorkerEnvMatches(uuid, app, group) {
const envs = asArray(await coolify(`/applications/${encodeURIComponent(uuid)}/envs`));
const drift = [...getWorkerAppConfigDrift(app, group), ...getWorkerEnvDrift(app, group, envs)];
if (drift.length > 0) {
const summary = drift.map((item) => `${item.key}: expected ${item.expected}, got ${item.actual}`).join("; ");
fail(`Coolify worker-${group.name} drift detected for ${app?.name || uuid}: ${summary}`);
function getUnsafeManagedWorkerEnvKeys(group, entries) {
const actual = envEntriesToRecord(entries);
const desired = desiredWorkerEnv(group);
const unsafe = [];
if (Object.hasOwn(actual, "APP_REVISION")) unsafe.push("APP_REVISION");
unsafe.push(...Object.keys(actual).filter(isWorkerPrivilegedEnvKey));
if (!KWP_WORKER_GROUP_NAMES.has(group.name) && Object.hasOwn(actual, KWP_WORKER_ENV_KEY)) unsafe.push(KWP_WORKER_ENV_KEY);
for (const key of Object.keys(desired)) {
if (!Object.hasOwn(actual, key)) continue;
if (key === "WORKFLOW_TRIGGER_EXECUTOR_MODE") {
if (!normalizeWorkflowTriggerExecutorMode(actual[key])) unsafe.push(key);
} else if (actual[key] !== desired[key]) {
unsafe.push(key);
}
}
return [...new Set(unsafe)].sort();
}
function predictedManagedWorkerEnv(group, targetEnvs, sourceEnvs) {
const predicted = envEntriesToRecord(targetEnvs);
if (group.name !== "general") {
for (const key of WORKER_GENERAL_PROVIDER_ENV_KEYS) {
delete predicted[key];
}
}
if (!KWP_WORKER_GROUP_NAMES.has(group.name)) delete predicted[KWP_WORKER_ENV_KEY];
for (const entry of sourceEnvs) {
const key = envKey(entry);
if (
!key ||
Object.hasOwn(predicted, key) ||
WORKER_ENV_OVERRIDE_KEYS.has(key) ||
isWorkerPrivilegedEnvKey(key) ||
!canWorkerGroupReceiveProviderEnv(group, key)
) {
continue;
}
predicted[key] = envValue(entry);
}
for (const [key, value] of Object.entries(desiredWorkerEnv(group))) {
if (!Object.hasOwn(predicted, key)) predicted[key] = value;
}
return entriesFromRecord(predicted);
}
function buildProviderEnvSanitizationPlan(group, entries) {
const removals = [];
const sanitizedEnvs = [];
for (const entry of entries) {
const key = envKey(entry);
const disallowedBillingProvider = group.name !== "general" && WORKER_GENERAL_PROVIDER_ENV_KEYS.has(key);
const disallowedKwpPilot = key === KWP_WORKER_ENV_KEY && !KWP_WORKER_GROUP_NAMES.has(group.name);
if (!disallowedBillingProvider && !disallowedKwpPilot) {
sanitizedEnvs.push(entry);
continue;
}
const uuid = typeof entry?.uuid === "string" ? entry.uuid.trim() : "";
if (!uuid) {
fail(`Coolify worker-${group.name} provider environment cannot be removed safely because its env UUID is missing`);
}
removals.push({ uuid });
}
return { sanitizedEnvs, removals };
}
async function reconcileKwpWorkerEnv(resolvedGroups) {
const general = resolvedGroups.find((entry) => entry.group.name === "general");
const importWorker = resolvedGroups.find((entry) => entry.group.name === "import");
if (!general?.app || !importWorker?.app) {
fail("Coolify KWP worker environment requires worker-general and worker-import");
}
const generalEntry = canonicalRuntimeEnvEntries(general.envs).find((entry) => envKey(entry) === KWP_WORKER_ENV_KEY);
const importEntry = canonicalRuntimeEnvEntries(importWorker.envs).find((entry) => envKey(entry) === KWP_WORKER_ENV_KEY);
const desiredValue = generalEntry ? envValue(generalEntry).trim() : "";
const actualValue = importEntry ? envValue(importEntry).trim() : "";
if (!desiredValue) {
if (!importEntry) return;
const envUuid = typeof importEntry.uuid === "string" ? importEntry.uuid.trim() : "";
if (!envUuid) {
fail("Coolify worker-import KWP environment cannot be removed safely because its env UUID is missing");
}
await coolify(`/applications/${encodeURIComponent(importWorker.app.uuid)}/envs/${encodeURIComponent(envUuid)}`, { method: "DELETE" });
importWorker.envs = importWorker.envs.filter((entry) => entry !== importEntry);
process.stdout.write("Removed stale KWP pilot environment from Coolify worker-import\n");
return;
}
if (actualValue === desiredValue) return;
await coolify(`/applications/${encodeURIComponent(importWorker.app.uuid)}/envs`, {
method: importEntry ? "PATCH" : "POST",
body: JSON.stringify({
key: KWP_WORKER_ENV_KEY,
value: desiredValue,
is_literal: generalEntry.is_literal ?? true,
is_preview: false,
is_multiline: generalEntry.is_multiline ?? false,
is_shown_once: generalEntry.is_shown_once ?? false,
}),
});
importWorker.envs = [
...importWorker.envs.filter((entry) => envKey(entry) !== KWP_WORKER_ENV_KEY),
{ ...generalEntry, key: KWP_WORKER_ENV_KEY, value: desiredValue, is_preview: false },
];
process.stdout.write("Reconciled KWP pilot environment for Coolify worker-import\n");
}
async function removeForbiddenProviderEnv(uuid, group, removals) {
for (const removal of removals) {
await coolify(`/applications/${encodeURIComponent(uuid)}/envs/${encodeURIComponent(removal.uuid)}`, {
method: "DELETE",
});
}
if (removals.length > 0) {
process.stdout.write(`Removed disallowed provider environment from Coolify worker-${group.name}\n`);
}
}
function entriesFromRecord(record) {
return Object.entries(record).map(([key, value]) => ({ key, value }));
}
async function ensureWorkerAppConfig(uuid, app, group) {
assertWorkerCommandHealthCanBeAuthoritative(app, group);
const drift = getWorkerAppConfigDrift(app, group, imageTag);
if (drift.length === 0) {
return app;
}
await coolify(`/applications/${encodeURIComponent(uuid)}`, {
method: "PATCH",
body: JSON.stringify(desiredWorkerAppConfig(group, imageTag)),
});
const updated = await coolify(`/applications/${encodeURIComponent(uuid)}`);
const remainingDrift = getWorkerAppConfigDrift(updated, group, imageTag);
if (remainingDrift.length > 0) {
fail(`Coolify worker-${group.name} app config drift remains after reconciliation`);
}
process.stdout.write(`Reconciled Coolify worker-${group.name} deployment health\n`);
return updated;
}
function assertWorkerCommandHealthCanBeAuthoritative(app, group) {
if (normalizeCoolifyBoolean(app?.custom_healthcheck_found) !== "false") {
fail(`Coolify worker-${group.name} image healthcheck must be absent so command health can be authoritative`);
}
}
function assertWorkerEnvEntriesMatch(app, group, envs, { includeAppConfig = true } = {}) {
const drift = [...(includeAppConfig ? getWorkerAppConfigDrift(app, group, imageTag) : []), ...getWorkerEnvDrift(app, group, envs)];
if (drift.length > 0) {
const keys = [...new Set(drift.map((item) => item.key))].sort().join(", ");
fail(`Coolify worker-${group.name} drift detected in: ${keys}`);
}
}
async function assertWorkerEnvMatches(uuid, app, group, options = {}) {
const envs = asArray(await coolify(`/applications/${encodeURIComponent(uuid)}/envs`));
assertWorkerEnvEntriesMatch(app, group, envs, options);
}
async function hydrateManagedWorkerApps(apps, allowed, provisioningScope) {
return Promise.all(
apps.map(async (app) => {
const markerGroup = GROUPS.find((group) => hasManagedWorkerMarker(app, group));
const matchedGroup = markerGroup || GROUPS.find((group) => matchesWorkerGroup(app, group.name));
if (provisionEnabled && !isInProvisioningEnvironment(app, provisioningScope)) return app;
const candidateIsInScope = matchedGroup && (provisionEnabled || allowed.size === 0 || allowed.has(app.uuid));
if (!candidateIsInScope) return app;
const detailed = await coolify(`/applications/${encodeURIComponent(app.uuid)}`);
if (detailed?.uuid !== app.uuid) {
fail(`Coolify worker-${matchedGroup.name} application identity could not be verified`);
}
return detailed;
})
);
}
function resolveWorkerGroups(apps, allowed, provisioningScope) {
const resolvedGroups = GROUPS.map((group) => {
const isTargetScope = (app) => !provisionEnabled || isInProvisioningScope(app, provisioningScope);
const markedApps = apps.filter((app) => hasManagedWorkerMarker(app, group) && isTargetScope(app));
for (const app of markedApps) {
const trustedByAllowlist = allowed.has(app.uuid);
if ((provisionEnabled || allowed.size === 0 || trustedByAllowlist) && !hasManagedWorkerIdentity(app, group)) {
fail(`Managed Coolify worker-${group.name} application identity is invalid`);
}
if (provisionEnabled && !trustedByAllowlist) {
if (!hasManagedWorkerRetryProvenance(app, group)) {
fail(`Managed Coolify worker-${group.name} retry provenance is invalid`);
}
if (!isInProvisioningScope(app, provisioningScope)) {
fail(`Managed Coolify worker-${group.name} application is outside the configured provisioning scope`);
}
}
}
const allowedMatches = apps.filter((app) => matchesWorkerGroup(app, group.name) && isTargetScope(app) && (allowed.size === 0 || allowed.has(app.uuid)));
const retryMatches = provisionEnabled
? markedApps.filter(
(app) =>
hasManagedWorkerIdentity(app, group) &&
(allowed.has(app.uuid) || (hasManagedWorkerRetryProvenance(app, group) && isInProvisioningScope(app, provisioningScope)))
)
: [];
const candidates = [...new Map([...allowedMatches, ...retryMatches].map((app) => [app.uuid, app])).values()];
if (candidates.length > 1) {
fail(`Multiple Coolify worker-${group.name} applications matched the managed scope`);
}
const app = candidates[0];
return {
group,
app,
envs: [],
managed: Boolean(
provisionEnabled &&
app &&
hasManagedWorkerIdentity(app, group) &&
(allowed.has(app.uuid) || (hasManagedWorkerRetryProvenance(app, group) && isInProvisioningScope(app, provisioningScope)))
),
needsRepair: false,
};
});
return resolvedGroups;
}
async function main() {
@@ -455,30 +979,110 @@ async function main() {
if (!workerImage || workerImage.split("/").length < 4) {
fail("Worker image path could not be resolved from REGISTRY, IMAGE_NAMESPACE, IMAGE_PREFIX, and worker target");
}
const allowed = new Set(existingResourceUuids.split(",").filter(Boolean));
const apps = await coolify("/applications");
const workerEnvSourceUuid = resolveWorkerEnvSourceUuid(apps, allowed);
const resolvedWorkers = [];
for (const group of GROUPS) {
let app = apps.find((candidate) => matchesWorkerGroup(candidate, group.name) && (allowed.size === 0 || allowed.has(candidate.uuid)));
if (!app && provisionEnabled) {
const uuid = await createWorkerApplication(group, workerEnvSourceUuid);
// Re-fetch the freshly created application so config drift checks
// (ports_exposes/health_check_*) validate the persisted resource, not a
// bare { uuid } stub that always reports those fields as <missing>.
const created = await coolify(`/applications/${encodeURIComponent(uuid)}`);
app = created && created.uuid ? created : { uuid };
}
if (!app?.uuid) {
fail(`Missing Coolify worker-${group.name} application`);
}
await assertWorkerEnvMatches(app.uuid, app, group);
resolvedWorkers.push(app.uuid);
if (!/^[A-Z][A-Z0-9_]*$/.test(resolvedEnvName)) {
fail("Resolved Coolify resource environment variable name is invalid");
}
const resolved = [...allowed, ...resolvedWorkers].filter(Boolean).join(",");
const allowed = new Set(existingResourceUuids.split(",").filter(Boolean));
for (const uuid of allowed) {
requireCoolifyCuid(uuid, `${prefix}_RESOURCE_UUIDS entry`);
}
if (configuredWorkerEnvSourceUuid) {
requireCoolifyCuid(configuredWorkerEnvSourceUuid, `${prefix}_WORKER_ENV_SOURCE_UUID`);
}
const listedApps = asArray(await coolify("/applications"));
for (const app of listedApps) {
requireCoolifyCuid(typeof app?.uuid === "string" ? app.uuid : "", "Coolify application UUID");
}
const provisioningScope = provisionEnabled ? await resolveProvisioningScope() : null;
const apps = await hydrateManagedWorkerApps(listedApps, allowed, provisioningScope);
const resolvedGroups = resolveWorkerGroups(apps, allowed, provisioningScope);
for (const entry of resolvedGroups) {
if (!entry.app && !provisionEnabled) {
fail(`Missing Coolify worker-${entry.group.name} application`);
}
if (entry.app) {
assertWorkerCommandHealthCanBeAuthoritative(entry.app, entry.group);
entry.envs = asArray(await coolify(`/applications/${encodeURIComponent(entry.app.uuid)}/envs`));
const providerEnvSanitization = buildProviderEnvSanitizationPlan(entry.group, entry.envs);
entry.sanitizedEnvs = providerEnvSanitization.sanitizedEnvs;
entry.providerEnvRemovals = providerEnvSanitization.removals;
if (entry.managed) {
const unsafeKeys = getUnsafeManagedWorkerEnvKeys(entry.group, entry.sanitizedEnvs);
if (unsafeKeys.length > 0) {
fail(`Managed Coolify worker-${entry.group.name} partial environment is unsafe: ${unsafeKeys.join(", ")}`);
}
entry.needsRepair = getWorkerEnvDrift(entry.app, entry.group, entry.sanitizedEnvs).length > 0;
} else {
assertWorkerEnvEntriesMatch(entry.app, entry.group, entry.sanitizedEnvs, { includeAppConfig: false });
}
} else {
entry.sanitizedEnvs = [];
entry.providerEnvRemovals = [];
}
}
const needsProvisioningOrRepair = resolvedGroups.some((entry) => !entry.app || entry.needsRepair);
const workerEnvSourceUuid = needsProvisioningOrRepair ? resolveWorkerEnvSourceUuid(apps, allowed) : "";
const sourceEnvs =
needsProvisioningOrRepair && workerEnvSourceUuid
? canonicalRuntimeEnvEntries(asArray(await coolify(`/applications/${encodeURIComponent(workerEnvSourceUuid)}/envs`)))
: [];
for (const entry of resolvedGroups) {
if (!entry.app || entry.needsRepair) {
const predicted = predictedManagedWorkerEnv(entry.group, entry.sanitizedEnvs, sourceEnvs);
const drift = getWorkerEnvDrift(entry.app, entry.group, predicted);
if (drift.length > 0) {
const keys = [...new Set(drift.map((item) => item.key))].sort().join(", ");
fail(`Coolify worker-${entry.group.name} cannot be safely provisioned or repaired; predicted drift: ${keys}`);
}
}
}
for (const entry of resolvedGroups) {
if (entry.app && entry.providerEnvRemovals.length > 0) {
await removeForbiddenProviderEnv(entry.app.uuid, entry.group, entry.providerEnvRemovals);
entry.envs = entry.sanitizedEnvs;
}
}
for (const entry of resolvedGroups) {
if (!entry.app) {
entry.app = await createWorkerApplication(entry.group, workerEnvSourceUuid, sourceEnvs, provisioningScope);
await assertWorkerEnvMatches(entry.app.uuid, entry.app, entry.group, { includeAppConfig: false });
} else if (entry.needsRepair) {
const clonedEnvs = await cloneWorkerEnv(workerEnvSourceUuid, entry.app.uuid, entry.group, {
sourceEnvs,
targetEnvs: entry.sanitizedEnvs,
});
await ensureMissingWorkerEnv(entry.app.uuid, entry.group, clonedEnvs);
await assertWorkerEnvMatches(entry.app.uuid, entry.app, entry.group, { includeAppConfig: false });
process.stdout.write(`Repaired partial Coolify worker-${entry.group.name} application\n`);
}
}
for (const entry of resolvedGroups) {
entry.envs = asArray(await coolify(`/applications/${encodeURIComponent(entry.app.uuid)}/envs`));
}
await reconcileKwpWorkerEnv(resolvedGroups);
for (const { app, group } of resolvedGroups) {
assertWorkerCommandHealthCanBeAuthoritative(app, group);
}
for (const entry of resolvedGroups) {
entry.app = await ensureWorkerAppConfig(entry.app.uuid, entry.app, entry.group);
}
for (const { app, group } of resolvedGroups) {
await assertWorkerEnvMatches(app.uuid, app, group);
}
const resolvedWorkers = resolvedGroups.map(({ app }) => app.uuid);
const resolved = [...new Set([...allowed, ...resolvedWorkers].filter(Boolean))].join(",");
if (process.env.GITHUB_ENV) {
const fs = await import("node:fs");
fs.appendFileSync(process.env.GITHUB_ENV, `${resolvedEnvName}=${resolved}\n`);
@@ -488,5 +1092,12 @@ async function main() {
const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
if (invokedPath && fileURLToPath(import.meta.url) === invokedPath) {
await main();
try {
await main();
} catch (error) {
if (error instanceof CoolifyRuntimeEnvConflictError) {
fail(error.message);
}
throw error;
}
}
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,824 @@
#!/usr/bin/env node
import { timingSafeEqual } from "node:crypto";
import { domainToASCII } from "node:url";
const [, , command, ...args] = process.argv;
const apiUrl = (process.env.SELECTED_COOLIFY_API_URL || process.env.COOLIFY_STAGING_API_URL || process.env.COOLIFY_API_URL || "").replace(/\/+$/, "");
const token = process.env.SELECTED_COOLIFY_TOKEN || process.env.COOLIFY_STAGING_TOKEN || process.env.COOLIFY_TOKEN || "";
const apiTimeoutMs = Number(process.env.COOLIFY_API_TIMEOUT_MS || "20000");
const pollDelayMs = Number(process.env.COOLIFY_DEPLOYMENT_POLL_MS || "5000");
const pollAttempts = Number(process.env.COOLIFY_DEPLOYMENT_WAIT_ATTEMPTS || "90");
const failedStatusGraceMs = Number(process.env.COOLIFY_FAILED_STATUS_GRACE_MS || "60000");
const drainHealthUrlOverride = (process.env.COOLIFY_CONTROLLER_DRAIN_HEALTH_URL || "").trim();
const drainFenceMsOverride = (process.env.COOLIFY_CONTROLLER_DRAIN_FENCE_MS || "").trim();
const FULL_GIT_SHA_PATTERN = /^[0-9a-f]{40}$/u;
const COOLIFY_CUID_PATTERN = /^[a-z][a-z0-9]{23}$/u;
const CONTROLLER_NAME = "hivegrid-portal-domain-controller";
const CONTROLLER_DEPLOY_HEALTH_PATH = "apps/portal-domain-controller/dist/deploy-health.js";
const CONTROLLER_HEALTH_INTERVAL_SECONDS = 30;
const CONTROLLER_HEALTH_TIMEOUT_SECONDS = 10;
const CONTROLLER_HEALTH_RETRIES = 3;
const CONTROLLER_HEALTH_START_PERIOD_SECONDS = 20;
const CONTROLLER_DRAIN_CONFIRMATIONS = 2;
const CONTROLLER_LEGACY_SHUTDOWN_FENCE_MS = 31_000;
const CONTROLLER_HEALTH_PROBE_TIMEOUT_MS = 5_000;
const CONTROLLER_INTERNAL_PORT = "8080";
const WEB_SURFACE_IDENTITIES = Object.freeze({
core: "hivegrid-web",
portal: "hivegrid-portal",
});
const PORTAL_CNAME_BY_ENVIRONMENT = Object.freeze({
staging: "staging-domains.portal.hivegrid.de",
production: "domains.portal.hivegrid.de",
});
const CONTROLLER_METRICS_BINDING_BY_ENVIRONMENT = Object.freeze({
staging: "10.42.0.3:19120:8080",
production: "10.42.0.8:19120:8080",
});
const PORTAL_TRAEFIK_ENTRYPOINT = "https";
const CONTROLLER_CONFIG_DIR = "/data/coolify/proxy/dynamic/hivegrid-portal-domains";
const CONTROLLER_RELOAD_TRIGGER_FILE = "/data/coolify/proxy/dynamic/.hivegrid-portal-domains.reload";
const COMPLETED_DEPLOYMENT_STATUSES = new Set(["finished", "success", "succeeded", "completed", "done"]);
const FAILED_RUNTIME_STATUSES = /failed|exited|dead|cancelled|canceled/iu;
const STOPPED_RUNTIME_STATUSES = /^(?:stopped|exited(?::[^:]*)?)$/iu;
const CONTROLLER_REQUIRED_ENV_KEYS = Object.freeze([
"PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET",
"PORTAL_DOMAIN_CONTROLLER_METRICS_TOKEN",
"PORTAL_DOMAIN_CONTROLLER_REDIS_URL",
"PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME",
"PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE",
"PORTAL_DOMAIN_CONTROLLER_CONFIG_DIR",
"PORTAL_DOMAIN_CONTROLLER_RELOAD_TRIGGER_FILE",
]);
const CONTROLLER_ALLOWED_ENV_KEYS = new Set([
...CONTROLLER_REQUIRED_ENV_KEYS,
"PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT",
"PORTAL_DOMAIN_CONTROLLER_HOST",
"PORTAL_DOMAIN_CONTROLLER_PORT",
"PORTAL_DOMAIN_CONTROLLER_CONCURRENCY",
]);
const CONTROLLER_COOLIFY_AUTOMATIC_ENV_KEYS = new Set(["COOLIFY_BRANCH", "COOLIFY_CONTAINER_NAME", "COOLIFY_FQDN", "COOLIFY_RESOURCE_UUID", "COOLIFY_URL"]);
const CONTROLLER_FORBIDDEN_ENV_KEYS = new Set([
"APP_REVISION",
"DATABASE_URL",
"DATABASE_READ_URL",
"DIRECT_URL",
"DOCKER_HOST",
"PGHOST",
"PGPORT",
"PGDATABASE",
"PGUSER",
"PGPASSWORD",
"CLOUDFLARE_API_TOKEN",
"CLOUDFLARE_API_KEY",
"COOLIFY_TOKEN",
"SSH_AUTH_SOCK",
]);
const CONTROLLER_FORBIDDEN_ENV_PREFIXES = Object.freeze(["MIGRATOR_", "SEED_", "COOLIFY_", "CLOUDFLARE_", "SSH_"]);
function fail(message) {
throw new Error(message);
}
async function coolify(path, options = {}) {
if (!apiUrl || !token) fail("Coolify API URL and token are required");
if (!Number.isInteger(apiTimeoutMs) || apiTimeoutMs < 10 || apiTimeoutMs > 120_000) {
fail("COOLIFY_API_TIMEOUT_MS must be an integer between 10 and 120000");
}
let response;
try {
response = await fetch(`${apiUrl}${path}`, {
...options,
signal: options.signal ?? AbortSignal.timeout(apiTimeoutMs),
headers: {
Authorization: `Bearer ${token}`,
Accept: "application/json",
...(options.body ? { "Content-Type": "application/json" } : {}),
...options.headers,
},
});
} catch {
fail("Coolify API request failed or timed out");
}
const body = await response.text();
let payload = {};
if (body.trim()) {
try {
payload = JSON.parse(body);
} catch {
payload = {};
}
}
if (!response.ok) fail(`Coolify API request failed with HTTP ${response.status}`);
return payload;
}
function normalizeValue(value) {
return value === null || value === undefined ? "" : String(value).trim();
}
function normalizeBoolean(value) {
if (value === true || value === "true" || value === 1 || value === "1") return "true";
if (value === false || value === "false" || value === 0 || value === "0") return "false";
return "";
}
function normalizeEnvValue(entry) {
let value = normalizeValue(entry?.value ?? entry?.real_value);
while (value.length >= 2 && ((value.startsWith("'") && value.endsWith("'")) || (value.startsWith('"') && value.endsWith('"')))) {
value = value.slice(1, -1).trim();
}
return value;
}
function requireCoolifyCuid(value, label) {
if (!COOLIFY_CUID_PATTERN.test(value)) fail(`${label} must be a valid Coolify CUID`);
}
function allowedResourceSet(csv) {
const values = csv
.split(",")
.map((value) => value.trim())
.filter(Boolean);
if (values.length === 0) fail("Portal-domain controller deployment requires an explicit Coolify resource allowlist");
const resources = new Set(values);
if (resources.size !== values.length) fail("Coolify resource allowlist must not contain duplicates");
for (const value of resources) requireCoolifyCuid(value, "Coolify resource allowlist entry");
return resources;
}
function arrayPayload(payload, label) {
if (Array.isArray(payload)) return payload;
if (Array.isArray(payload?.data)) return payload.data;
fail(`Coolify ${label} response was malformed`);
}
function runtimeEnvEntries(payload) {
const entries = [];
const keys = new Set();
for (const entry of arrayPayload(payload, "environment")) {
if (normalizeBoolean(entry?.is_preview) === "true") continue;
const key = normalizeValue(entry?.key);
if (!key) continue;
if (keys.has(key)) fail("Coolify runtime environment contains duplicate non-preview keys");
keys.add(key);
entries.push(entry);
}
return entries;
}
function runtimeStorageEntries(payload) {
let entries;
if (Array.isArray(payload) || Array.isArray(payload?.data)) {
entries = arrayPayload(payload, "storage");
} else if (Array.isArray(payload?.file_storages) && Array.isArray(payload?.persistent_storages)) {
entries = [
...payload.file_storages.map((entry) => ({ ...entry, type: "file" })),
...payload.persistent_storages.map((entry) => ({ ...entry, type: "persistent" })),
];
} else {
fail("Coolify storage response was malformed");
}
return entries.filter((entry) => normalizeBoolean(entry?.is_preview) !== "true");
}
function valuesByKey(entries) {
return new Map(entries.map((entry) => [normalizeValue(entry?.key), normalizeEnvValue(entry)]));
}
function normalizedImage(value) {
return normalizeValue(value).replace(/\/+$/, "");
}
function assertPrivateControllerIdentity(app, resourceUuid, expectedImage, expectedMetricsBinding) {
if (
app?.uuid !== resourceUuid ||
normalizeValue(app?.name) !== CONTROLLER_NAME ||
normalizedImage(app?.docker_registry_image_name) !== expectedImage ||
normalizeValue(app?.build_pack) !== "dockerimage"
) {
fail("Portal-domain controller UUID, name, image, or dockerimage build-pack identity does not match");
}
const routeValues = [app?.fqdn, app?.domain, app?.domains]
.flatMap((value) => (Array.isArray(value) ? value : [value]))
.flatMap((value) => normalizeValue(value).split(/[\s,]+/u))
.filter(Boolean);
if (routeValues.length > 0) fail("Portal-domain controller must remain private without a public Coolify route");
if (normalizeValue(app?.ports_mappings) !== expectedMetricsBinding) {
fail(`Portal-domain controller must expose metrics only through the exact mesh binding ${expectedMetricsBinding}`);
}
}
function storagePath(entry, ...keys) {
for (const key of keys) {
const value = normalizeValue(entry?.[key]);
if (value) return value;
}
return "";
}
function assertControllerStorageContract(entries) {
if (entries.length !== 2) {
fail("Portal-domain controller requires exactly two narrow bind mounts");
}
const normalized = entries.map((entry) => ({
type: normalizeValue(entry?.type),
directory: normalizeBoolean(entry?.is_directory),
source: storagePath(entry, "fs_path", "host_path", "source"),
destination: storagePath(entry, "mount_path", "destination", "target"),
readOnly: normalizeBoolean(entry?.is_read_only ?? entry?.read_only),
}));
const configDirectory = normalized.filter(
(entry) =>
entry.type === "file" &&
entry.directory === "true" &&
entry.source === CONTROLLER_CONFIG_DIR &&
entry.destination === CONTROLLER_CONFIG_DIR &&
entry.readOnly !== "true"
);
const reloadSentinel = normalized.filter(
(entry) =>
(entry.type === "file" || entry.type === "persistent") &&
entry.directory !== "true" &&
entry.source === CONTROLLER_RELOAD_TRIGGER_FILE &&
entry.destination === CONTROLLER_RELOAD_TRIGGER_FILE &&
entry.readOnly !== "true"
);
if (configDirectory.length !== 1 || reloadSentinel.length !== 1) {
fail("Portal-domain controller bind mounts must expose only its RW config subdirectory and RW reload sentinel file");
}
}
function requireSecret(values, key) {
const value = values.get(key) || "";
const bytes = Buffer.byteLength(value, "utf8");
if (bytes < 32 || bytes > 512) fail(`${key} must contain between 32 and 512 bytes`);
return value;
}
function equalSecret(left, right) {
const leftBuffer = Buffer.from(left, "utf8");
const rightBuffer = Buffer.from(right, "utf8");
return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
}
function redisQueueIdentity(value, label) {
let parsed;
try {
parsed = new URL(value);
} catch {
fail(`${label} must be a valid Redis connection URL`);
}
if (!new Set(["redis:", "rediss:"]).has(parsed.protocol) || !parsed.hostname || parsed.hash) {
fail(`${label} must be a valid Redis connection URL`);
}
const database = parsed.pathname.replace(/^\//u, "") || "0";
if (!/^\d+$/u.test(database)) fail(`${label} must select a numeric Redis database`);
return `${parsed.protocol}//${parsed.hostname.toLowerCase()}:${parsed.port || "6379"}/${database}`;
}
function assertHostname(value) {
const normalized = value.toLowerCase().replace(/\.$/u, "");
const ascii = domainToASCII(normalized);
if (
!ascii ||
ascii.length > 253 ||
ascii.includes("*") ||
!ascii.includes(".") ||
ascii.split(".").some((label) => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label))
) {
fail("PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME must be an exact DNS hostname");
}
}
function assertBackendService(value) {
if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,126}@docker$/u.test(value)) {
fail("PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE must be a provider-qualified Docker service name");
}
}
function assertEntryPoint(value) {
const entryPoint = value || PORTAL_TRAEFIK_ENTRYPOINT;
if (entryPoint !== PORTAL_TRAEFIK_ENTRYPOINT) {
fail("PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT must be exactly https");
}
return entryPoint;
}
function assertWebSurfacePair(core, portal) {
const expected = [
[core, WEB_SURFACE_IDENTITIES.core],
[portal, WEB_SURFACE_IDENTITIES.portal],
];
for (const [app, expectedName] of expected) {
requireCoolifyCuid(app?.uuid || "", `${expectedName} resource UUID`);
if (normalizeValue(app?.name) !== expectedName || normalizeValue(app?.build_pack) !== "dockerimage" || !normalizedImage(app?.docker_registry_image_name)) {
fail("Coolify web surface identity must match its explicit name, dockerimage build pack, and image");
}
}
if (core.uuid === portal.uuid || normalizedImage(core.docker_registry_image_name) !== normalizedImage(portal.docker_registry_image_name)) {
fail("hivegrid-web and hivegrid-portal must be distinct resources using the same immutable web image");
}
}
function portalBackendService(portal) {
requireCoolifyCuid(portal?.uuid || "", "hivegrid-portal resource UUID");
return `https-0-${portal.uuid}@docker`;
}
function expectedCnameForEnvironment(environment) {
const expectedCname = PORTAL_CNAME_BY_ENVIRONMENT[environment];
if (!expectedCname) {
fail("Portal-domain controller deployment environment must be exactly staging or production");
}
return expectedCname;
}
function expectedMetricsBindingForEnvironment(environment) {
const binding = CONTROLLER_METRICS_BINDING_BY_ENVIRONMENT[environment];
if (!binding) {
fail("Portal-domain controller deployment environment must be exactly staging or production");
}
return binding;
}
function controllerHealthUrlForEnvironment(environment) {
const [host, publishedPort, internalPort, ...rest] = expectedMetricsBindingForEnvironment(environment).split(":");
if (rest.length > 0 || !/^10\.42\.0\.\d+$/u.test(host || "") || !/^\d{2,5}$/u.test(publishedPort || "") || internalPort !== CONTROLLER_INTERNAL_PORT) {
fail("Portal-domain controller mesh health binding is invalid");
}
if (!drainHealthUrlOverride) return `http://${host}:${publishedPort}/healthz`;
if (process.env.NODE_ENV !== "test") fail("Portal-domain controller drain health override is test-only");
let override;
let selectedApi;
try {
override = new URL(drainHealthUrlOverride);
selectedApi = new URL(apiUrl);
} catch {
fail("Portal-domain controller test drain health URL is invalid");
}
const loopbackHosts = new Set(["127.0.0.1", "localhost", "::1"]);
if (
override.protocol !== "http:" ||
!loopbackHosts.has(override.hostname) ||
!loopbackHosts.has(selectedApi.hostname) ||
override.origin !== selectedApi.origin ||
override.username ||
override.password ||
override.search ||
override.hash
) {
fail("Portal-domain controller test drain health URL must be loopback-only HTTP");
}
return override.href;
}
function controllerDrainFenceMs() {
if (!drainFenceMsOverride) return CONTROLLER_LEGACY_SHUTDOWN_FENCE_MS;
if (process.env.NODE_ENV !== "test" || !drainHealthUrlOverride) {
fail("Portal-domain controller drain fence override is test-only");
}
const value = Number(drainFenceMsOverride);
if (!Number.isSafeInteger(value) || value < 1 || value > 1_000) {
fail("Portal-domain controller test drain fence must be an integer between 1 and 1000");
}
return value;
}
function assertControllerEnv(entries, expectedCname) {
const values = valuesByKey(entries);
for (const key of CONTROLLER_REQUIRED_ENV_KEYS) {
if (!values.get(key)) fail(`Portal-domain controller runtime is missing ${key}`);
}
const forbidden = [...values.keys()].filter(
(key) =>
!CONTROLLER_COOLIFY_AUTOMATIC_ENV_KEYS.has(key) &&
(CONTROLLER_FORBIDDEN_ENV_KEYS.has(key) || CONTROLLER_FORBIDDEN_ENV_PREFIXES.some((prefix) => key.startsWith(prefix)))
);
if (forbidden.length > 0) fail("Portal-domain controller runtime contains forbidden privileged environment keys");
const unexpected = [...values.keys()].filter((key) => !CONTROLLER_ALLOWED_ENV_KEYS.has(key) && !CONTROLLER_COOLIFY_AUTOMATIC_ENV_KEYS.has(key));
if (unexpected.length > 0) {
fail("Portal-domain controller runtime must contain only its explicit least-privilege environment allowlist");
}
const configuredPort = values.get("PORTAL_DOMAIN_CONTROLLER_PORT") || CONTROLLER_INTERNAL_PORT;
if (configuredPort !== CONTROLLER_INTERNAL_PORT) {
fail(`PORTAL_DOMAIN_CONTROLLER_PORT must be exactly ${CONTROLLER_INTERNAL_PORT} for the mesh metrics binding`);
}
const commandSecret = requireSecret(values, "PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET");
const metricsToken = requireSecret(values, "PORTAL_DOMAIN_CONTROLLER_METRICS_TOKEN");
if (equalSecret(commandSecret, metricsToken)) fail("Portal-domain controller command and metrics secrets must differ");
const redisIdentity = redisQueueIdentity(values.get("PORTAL_DOMAIN_CONTROLLER_REDIS_URL") || "", "PORTAL_DOMAIN_CONTROLLER_REDIS_URL");
const configuredCname = values.get("PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME") || "";
assertHostname(configuredCname);
if (configuredCname !== expectedCname) {
fail(`PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME must be exactly ${expectedCname} for this deployment environment`);
}
const backendService = values.get("PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE") || "";
assertBackendService(backendService);
const entryPoint = assertEntryPoint(values.get("PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT") || "");
if (values.get("PORTAL_DOMAIN_CONTROLLER_CONFIG_DIR") !== CONTROLLER_CONFIG_DIR) {
fail("PORTAL_DOMAIN_CONTROLLER_CONFIG_DIR must use the dedicated Traefik subdirectory");
}
if (values.get("PORTAL_DOMAIN_CONTROLLER_RELOAD_TRIGGER_FILE") !== CONTROLLER_RELOAD_TRIGGER_FILE) {
fail("PORTAL_DOMAIN_CONTROLLER_RELOAD_TRIGGER_FILE must use the single watched-root sentinel file");
}
return { commandSecret, redisIdentity, expectedCname: configuredCname, backendService, entryPoint };
}
function assertWebCnameEnv(entries, expectedCname) {
const values = valuesByKey(entries);
if (values.get("PORTAL_CUSTOM_DOMAIN_CNAME_TARGET") !== expectedCname) {
fail(`hivegrid-web must use exactly ${expectedCname} for this deployment environment`);
}
}
function assertStagingWebCustomDomainRuntime(entries, environment, surfaceName) {
if (environment !== "staging") return;
if (valuesByKey(entries).get("PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED") !== "true") {
fail(`${surfaceName} must set PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED exactly to true in staging`);
}
}
function assertWorkerGeneralEnv(entries, controllerContract) {
const values = valuesByKey(entries);
if (values.get("WORKER_QUEUE_GROUP") !== "general") fail("Portal-domain orchestration must use worker-general");
if (values.get("PORTAL_DOMAIN_ORCHESTRATION_REQUIRED") !== "true") {
fail("worker-general must set PORTAL_DOMAIN_ORCHESTRATION_REQUIRED=true");
}
if (values.has("PORTAL_DOMAIN_CONTROLLER_METRICS_TOKEN")) {
fail("worker-general must not receive the portal-domain controller metrics token");
}
const commandSecret = requireSecret(values, "PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET");
if (!equalSecret(commandSecret, controllerContract.commandSecret)) {
fail("worker-general and portal-domain controller command HMAC secrets must match");
}
const workerRedisUrl = values.get("BULLMQ_REDIS_URL") || values.get("REDIS_URL") || "";
const workerRedisIdentity = redisQueueIdentity(workerRedisUrl, "worker-general Redis URL");
if (workerRedisIdentity !== controllerContract.redisIdentity) {
fail("worker-general and portal-domain controller must use the same Redis queue endpoint and database");
}
}
async function resolveRuntimeContract(environment, resourceUuid, allowedCsv, controllerImage, workerImage) {
const expectedCname = expectedCnameForEnvironment(environment);
const expectedMetricsBinding = expectedMetricsBindingForEnvironment(environment);
requireCoolifyCuid(resourceUuid, "Portal-domain controller resource UUID");
const allowed = allowedResourceSet(allowedCsv);
if (!allowed.has(resourceUuid)) fail("Portal-domain controller resource UUID is outside the Coolify allowlist");
const expectedControllerImage = normalizedImage(controllerImage);
const expectedWorkerImage = normalizedImage(workerImage);
if (!expectedControllerImage || !expectedWorkerImage) fail("Controller and worker image identities are required");
const resourcePath = `/applications/${encodeURIComponent(resourceUuid)}`;
const [appsPayload, controller, controllerEnvPayload, storagePayload] = await Promise.all([
coolify("/applications"),
coolify(resourcePath),
coolify(`${resourcePath}/envs`),
coolify(`${resourcePath}/storages`),
]);
const apps = arrayPayload(appsPayload, "applications");
if (!apps.some((app) => app?.uuid === resourceUuid)) {
fail("Portal-domain controller resource is absent from the Coolify application inventory");
}
assertPrivateControllerIdentity(controller, resourceUuid, expectedControllerImage, expectedMetricsBinding);
assertControllerStorageContract(runtimeStorageEntries(storagePayload));
const controllerContract = assertControllerEnv(runtimeEnvEntries(controllerEnvPayload), expectedCname);
const runtimeCandidatesWithEnv = await Promise.all(
apps
.filter((app) => allowed.has(app?.uuid) && app?.uuid !== resourceUuid)
.map(async (app) => ({
app,
entries: runtimeEnvEntries(await coolify(`/applications/${encodeURIComponent(app.uuid)}/envs`)),
}))
);
const workerGeneralMatches = runtimeCandidatesWithEnv.filter(
({ app, entries }) =>
normalizedImage(app?.docker_registry_image_name) === expectedWorkerImage && valuesByKey(entries).get("WORKER_QUEUE_GROUP") === "general"
);
if (workerGeneralMatches.length !== 1) {
fail("Coolify must expose exactly one allowlisted worker-general for portal-domain orchestration");
}
assertWorkerGeneralEnv(workerGeneralMatches[0].entries, controllerContract);
const webCoreMatches = runtimeCandidatesWithEnv.filter(({ entries }) => valuesByKey(entries).get("WEB_RUNTIME_SURFACE") === "core");
if (webCoreMatches.length !== 1) {
fail("Coolify must expose exactly one allowlisted hivegrid-web core surface for CNAME verification");
}
assertWebCnameEnv(webCoreMatches[0].entries, expectedCname);
assertStagingWebCustomDomainRuntime(webCoreMatches[0].entries, environment, WEB_SURFACE_IDENTITIES.core);
const webPortalMatches = runtimeCandidatesWithEnv.filter(({ entries }) => valuesByKey(entries).get("WEB_RUNTIME_SURFACE") === "portal");
if (webPortalMatches.length !== 1) {
fail("Coolify must expose exactly one allowlisted hivegrid-portal surface for custom-domain routing");
}
assertStagingWebCustomDomainRuntime(webPortalMatches[0].entries, environment, WEB_SURFACE_IDENTITIES.portal);
assertWebSurfacePair(webCoreMatches[0].app, webPortalMatches[0].app);
if (controllerContract.backendService !== portalBackendService(webPortalMatches[0].app)) {
fail("PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE must target the exact allowlisted hivegrid-portal Docker service");
}
return { controller, expectedControllerImage };
}
async function assertRuntime(environment, resourceUuid, allowedCsv, controllerImage, workerImage) {
await resolveRuntimeContract(environment, resourceUuid, allowedCsv, controllerImage, workerImage);
process.stdout.write("Portal-domain controller runtime, mounts, and worker-general HMAC wiring verified\n");
}
async function snapshotRelease(environment, resourceUuid, allowedCsv, controllerImage, workerImage) {
const { controller, expectedControllerImage } = await resolveRuntimeContract(environment, resourceUuid, allowedCsv, controllerImage, workerImage);
const revision = normalizeValue(controller?.docker_registry_image_tag);
if (!FULL_GIT_SHA_PATTERN.test(revision)) {
fail("Portal-domain controller previous release must be a full lowercase Git SHA");
}
assertReleaseConfig(controller, resourceUuid, expectedControllerImage, revision, expectedMetricsBindingForEnvironment(environment));
process.stdout.write(revision);
}
function assertPollingContract() {
if (!Number.isInteger(pollDelayMs) || pollDelayMs < 1 || pollDelayMs > 60_000) {
fail("COOLIFY_DEPLOYMENT_POLL_MS must be an integer between 1 and 60000");
}
if (!Number.isInteger(pollAttempts) || pollAttempts < 1 || pollAttempts > 180) {
fail("COOLIFY_DEPLOYMENT_WAIT_ATTEMPTS must be an integer between 1 and 180");
}
if (!Number.isSafeInteger(failedStatusGraceMs) || failedStatusGraceMs < 0) {
fail("COOLIFY_FAILED_STATUS_GRACE_MS must be a non-negative safe integer");
}
}
async function probeControllerHealth(healthUrl, expectedRevision) {
let response;
try {
response = await fetch(healthUrl, {
cache: "no-store",
redirect: "error",
signal: AbortSignal.timeout(CONTROLLER_HEALTH_PROBE_TIMEOUT_MS),
});
} catch {
return { reachable: false, revisionBound: false };
}
if (!response.ok) return { reachable: true, revisionBound: false };
let payload;
try {
payload = await response.json();
} catch {
return { reachable: true, revisionBound: false };
}
return {
reachable: true,
revisionBound:
payload?.status === "ok" && payload?.service === CONTROLLER_NAME && normalizeValue(payload?.revision) === expectedRevision,
};
}
async function stopAndDrain(environment, resourceUuid, allowedCsv, controllerImage, workerImage) {
assertPollingContract();
if (pollAttempts < CONTROLLER_DRAIN_CONFIRMATIONS) {
fail(`Portal-domain controller drain requires at least ${CONTROLLER_DRAIN_CONFIRMATIONS} polling attempts`);
}
const { controller, expectedControllerImage } = await resolveRuntimeContract(environment, resourceUuid, allowedCsv, controllerImage, workerImage);
const expectedMetricsBinding = expectedMetricsBindingForEnvironment(environment);
const resourcePath = `/applications/${encodeURIComponent(resourceUuid)}`;
const expectedRevision = normalizeValue(controller?.docker_registry_image_tag);
if (!FULL_GIT_SHA_PATTERN.test(expectedRevision)) {
fail("Portal-domain controller drain requires the current immutable full-SHA release");
}
const healthUrl = controllerHealthUrlForEnvironment(environment);
const requiredDrainFenceMs = controllerDrainFenceMs();
const beforeStop = await probeControllerHealth(healthUrl, expectedRevision);
if (!beforeStop.reachable || !beforeStop.revisionBound) {
fail("Portal-domain controller pre-stop health is unreachable or not revision-bound; operator recovery is required");
}
// Coolify queues this action and its application status may be stale. The
// pre-stop revision-bound mesh probe proves which worker is live. After the
// request, both Coolify's stopped state and health-port disappearance must be
// observed twice. The first rollout also keeps that evidence continuous for
// 31 seconds, beyond the legacy controller's 30-second hard shutdown; future
// releases additionally close /healthz only after queue and lock drainage.
await coolify(`${resourcePath}/stop`, { method: "POST" });
let drainConfirmations = 0;
let drainEvidenceSinceMs;
for (let attempt = 1; attempt <= pollAttempts; attempt += 1) {
const current = await coolify(resourcePath);
assertPrivateControllerIdentity(current, resourceUuid, expectedControllerImage, expectedMetricsBinding);
const afterStop = await probeControllerHealth(healthUrl, expectedRevision);
if (STOPPED_RUNTIME_STATUSES.test(normalizeValue(current?.status)) && !afterStop.reachable) {
drainConfirmations += 1;
drainEvidenceSinceMs ??= performance.now();
} else {
drainConfirmations = 0;
drainEvidenceSinceMs = undefined;
}
if (
drainConfirmations >= CONTROLLER_DRAIN_CONFIRMATIONS &&
drainEvidenceSinceMs !== undefined &&
performance.now() - drainEvidenceSinceMs >= requiredDrainFenceMs
) {
process.stdout.write("Portal-domain controller stopped and command worker drained before web rollout\n");
return;
}
if (attempt < pollAttempts) await new Promise((resolve) => setTimeout(resolve, pollDelayMs));
}
fail("Portal-domain controller did not stop and drain before the web rollout");
}
function controllerHealthCommand(revision) {
return `node ${CONTROLLER_DEPLOY_HEALTH_PATH} ${revision}`;
}
function releasePayload(revision) {
return {
pre_deployment_command: "",
post_deployment_command: "",
docker_registry_image_tag: revision,
health_check_enabled: true,
health_check_type: "cmd",
health_check_command: controllerHealthCommand(revision),
health_check_interval: CONTROLLER_HEALTH_INTERVAL_SECONDS,
health_check_timeout: CONTROLLER_HEALTH_TIMEOUT_SECONDS,
health_check_retries: CONTROLLER_HEALTH_RETRIES,
health_check_start_period: CONTROLLER_HEALTH_START_PERIOD_SECONDS,
};
}
function snapshotReleaseNumber(value, key) {
if (value === null || value === undefined || normalizeValue(value) === "") {
fail(`Portal-domain controller existing ${key} configuration is missing`);
}
const number = Number(value);
if (!Number.isFinite(number)) {
fail(`Portal-domain controller existing ${key} configuration is invalid`);
}
return number;
}
function previousReleasePayload(app) {
const healthCheckEnabled = normalizeBoolean(app?.health_check_enabled);
if (!healthCheckEnabled) {
fail("Portal-domain controller existing health_check_enabled configuration is invalid");
}
return {
pre_deployment_command: normalizeValue(app?.pre_deployment_command),
post_deployment_command: normalizeValue(app?.post_deployment_command),
docker_registry_image_tag: normalizeValue(app?.docker_registry_image_tag),
health_check_enabled: healthCheckEnabled === "true",
health_check_type: normalizeValue(app?.health_check_type),
health_check_command: normalizeValue(app?.health_check_command),
health_check_interval: snapshotReleaseNumber(app?.health_check_interval, "health_check_interval"),
health_check_timeout: snapshotReleaseNumber(app?.health_check_timeout, "health_check_timeout"),
health_check_retries: snapshotReleaseNumber(app?.health_check_retries, "health_check_retries"),
health_check_start_period: snapshotReleaseNumber(app?.health_check_start_period, "health_check_start_period"),
};
}
function normalizedMutableReleaseConfig(app) {
return {
pre_deployment_command: normalizeValue(app?.pre_deployment_command),
post_deployment_command: normalizeValue(app?.post_deployment_command),
docker_registry_image_tag: normalizeValue(app?.docker_registry_image_tag),
health_check_enabled: normalizeBoolean(app?.health_check_enabled),
health_check_type: normalizeValue(app?.health_check_type),
health_check_command: normalizeValue(app?.health_check_command),
health_check_interval: Number(app?.health_check_interval),
health_check_timeout: Number(app?.health_check_timeout),
health_check_retries: Number(app?.health_check_retries),
health_check_start_period: Number(app?.health_check_start_period),
};
}
function mutableReleaseConfigDrift(app, expected) {
const actualConfig = normalizedMutableReleaseConfig(app);
const expectedConfig = normalizedMutableReleaseConfig(expected);
return Object.keys(expectedConfig).filter((key) => actualConfig[key] !== expectedConfig[key]);
}
function assertReleaseConfig(app, resourceUuid, image, revision, expectedMetricsBinding) {
assertPrivateControllerIdentity(app, resourceUuid, image, expectedMetricsBinding);
const actual = {
...normalizedMutableReleaseConfig(app),
custom_healthcheck_found: normalizeBoolean(app?.custom_healthcheck_found),
};
const expected = {
...releasePayload(revision),
health_check_enabled: "true",
custom_healthcheck_found: "false",
};
const drift = Object.keys(expected).filter((key) => actual[key] !== expected[key]);
if (drift.length > 0) {
fail("Portal-domain controller release or revision-bound command health configuration drifted");
}
}
async function setRelease(environment, resourceUuid, allowedCsv, controllerImage, workerImage, revision) {
if (!FULL_GIT_SHA_PATTERN.test(revision)) {
fail("Portal-domain controller release requires a full lowercase Git SHA");
}
const { controller, expectedControllerImage } = await resolveRuntimeContract(environment, resourceUuid, allowedCsv, controllerImage, workerImage);
const resourcePath = `/applications/${encodeURIComponent(resourceUuid)}`;
const previous = previousReleasePayload(controller);
try {
await coolify(resourcePath, { method: "PATCH", body: JSON.stringify(releasePayload(revision)) });
const updated = await coolify(resourcePath);
assertReleaseConfig(updated, resourceUuid, expectedControllerImage, revision, expectedMetricsBindingForEnvironment(environment));
} catch {
let restored = false;
try {
await coolify(resourcePath, { method: "PATCH", body: JSON.stringify(previous) });
const restoredApp = await coolify(resourcePath);
restored = mutableReleaseConfigDrift(restoredApp, previous).length === 0;
} catch {
restored = false;
}
fail(
restored
? "Portal-domain controller release mutation failed and previous configuration was restored"
: "Portal-domain controller release mutation failed and compensation was incomplete"
);
}
process.stdout.write("Portal-domain controller immutable release configured\n");
}
function deploymentStatus(payload) {
return normalizeValue(payload?.status || payload?.deployment?.status || payload?.data?.status).toLowerCase();
}
function assertCompletedDeployment(payload, deploymentUuid, app) {
if (normalizeValue(payload?.deployment_uuid) !== deploymentUuid) {
fail("Portal-domain controller deployment identity does not match the triggered deployment");
}
if (!COMPLETED_DEPLOYMENT_STATUSES.has(deploymentStatus(payload))) {
fail("Portal-domain controller deployment is not completed");
}
if (normalizeValue(payload?.application_name) !== CONTROLLER_NAME) {
fail("Portal-domain controller deployment belongs to an unexpected application");
}
const applicationId = normalizeValue(app?.id);
const deploymentApplicationId = normalizeValue(payload?.application_id);
if (applicationId && deploymentApplicationId && applicationId !== deploymentApplicationId) {
fail("Portal-domain controller deployment application identity does not match the live resource");
}
}
async function assertRelease(environment, resourceUuid, allowedCsv, controllerImage, workerImage, revision, deploymentUuid) {
if (!FULL_GIT_SHA_PATTERN.test(revision)) {
fail("Portal-domain controller release verification requires a full lowercase Git SHA");
}
requireCoolifyCuid(deploymentUuid, "Portal-domain controller deployment UUID");
assertPollingContract();
const { controller, expectedControllerImage } = await resolveRuntimeContract(environment, resourceUuid, allowedCsv, controllerImage, workerImage);
const deployment = await coolify(`/deployments/${encodeURIComponent(deploymentUuid)}`);
assertCompletedDeployment(deployment, deploymentUuid, controller);
const resourcePath = `/applications/${encodeURIComponent(resourceUuid)}`;
// The controller is deliberately stopped-and-drained before the rollout, so Coolify's
// cached application status can still read "exited" for a while after the deployment
// reports finished. Keep the fail-closed boundary time-based so a polling-frequency
// change cannot shorten the stale-status grace period.
let failedStatusSinceMs;
for (let attempt = 1; attempt <= pollAttempts; attempt += 1) {
const current = await coolify(resourcePath);
assertReleaseConfig(current, resourceUuid, expectedControllerImage, revision, expectedMetricsBindingForEnvironment(environment));
const status = normalizeValue(current?.status).toLowerCase();
if (status === "running:healthy") {
process.stdout.write("Portal-domain controller revision-bound healthz, readyz, and immutable revision verified\n");
return;
}
if (FAILED_RUNTIME_STATUSES.test(status)) {
const nowMs = performance.now();
failedStatusSinceMs ??= nowMs;
if (nowMs - failedStatusSinceMs >= failedStatusGraceMs) {
fail("Portal-domain controller entered a terminal runtime state");
}
} else {
failedStatusSinceMs = undefined;
}
if (attempt < pollAttempts) await new Promise((resolve) => setTimeout(resolve, pollDelayMs));
}
fail("Portal-domain controller did not become running:healthy in time");
}
try {
if (command === "assert-runtime") {
await assertRuntime(args[0] || "", args[1] || "", args[2] || "", args[3] || "", args[4] || "");
} else if (command === "snapshot-release") {
await snapshotRelease(args[0] || "", args[1] || "", args[2] || "", args[3] || "", args[4] || "");
} else if (command === "stop-and-drain") {
await stopAndDrain(args[0] || "", args[1] || "", args[2] || "", args[3] || "", args[4] || "");
} else if (command === "set-release") {
await setRelease(args[0] || "", args[1] || "", args[2] || "", args[3] || "", args[4] || "", args[5] || "");
} else if (command === "assert-release") {
await assertRelease(args[0] || "", args[1] || "", args[2] || "", args[3] || "", args[4] || "", args[5] || "", args[6] || "");
} else {
fail(
"Usage: coolify-portal-domain-controller.mjs assert-runtime|snapshot-release|stop-and-drain <staging|production> <controller-resource-uuid> <allowed-resource-csv> <controller-image> <worker-image> | set-release <staging|production> <controller-resource-uuid> <allowed-resource-csv> <controller-image> <worker-image> <full-git-sha> | assert-release <staging|production> <controller-resource-uuid> <allowed-resource-csv> <controller-image> <worker-image> <full-git-sha> <deployment-uuid>"
);
}
} catch (error) {
process.stderr.write(`${error instanceof Error ? error.message : "Portal-domain controller Coolify helper failed"}\n`);
process.exitCode = 1;
}
@@ -0,0 +1,977 @@
// @vitest-environment node
import assert from "node:assert/strict";
import { spawn } from "node:child_process";
import http from "node:http";
import path from "node:path";
import { describe, it } from "vitest";
const scriptPath = path.resolve("scripts/coolify-portal-domain-controller.mjs");
const bearerToken = "controller-coolify-token-sentinel";
const controllerUuid = "c".repeat(24);
const workerGeneralUuid = "g".repeat(24);
const workerMailUuid = "m".repeat(24);
const webCoreUuid = "w".repeat(24);
const webPortalUuid = "p".repeat(24);
const deploymentUuid = "d".repeat(24);
const revision = "a".repeat(40);
const controllerImage = "registry.example.test/toolctrl-labs/hivegrid/portal-domain-controller";
const workerImage = "registry.example.test/toolctrl-labs/hivegrid/worker";
const webImage = "registry.example.test/toolctrl-labs/hivegrid/web";
const commandSecret = "controller-command-secret-sentinel-value";
const otherCommandSecret = "different-controller-command-secret-value";
const metricsToken = "controller-metrics-token-sentinel-value";
const configDirectory = "/data/coolify/proxy/dynamic/hivegrid-portal-domains";
const reloadTriggerFile = "/data/coolify/proxy/dynamic/.hivegrid-portal-domains.reload";
const stagingCname = "staging-domains.portal.hivegrid.de";
const productionCname = "domains.portal.hivegrid.de";
const stagingMetricsBinding = "10.42.0.3:19120:8080";
const productionMetricsBinding = "10.42.0.8:19120:8080";
function expectedControllerHealthConfig(expectedRevision = revision) {
return {
health_check_enabled: true,
health_check_type: "cmd",
health_check_command: `node apps/portal-domain-controller/dist/deploy-health.js ${expectedRevision}`,
health_check_interval: 30,
health_check_timeout: 10,
health_check_retries: 3,
health_check_start_period: 20,
};
}
function controllerEnv(overrides = {}) {
return envEntries({
PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET: commandSecret,
PORTAL_DOMAIN_CONTROLLER_METRICS_TOKEN: metricsToken,
PORTAL_DOMAIN_CONTROLLER_REDIS_URL: "rediss://controller:secret@redis.example.test:6380/7",
PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME: stagingCname,
PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE: `https-0-${webPortalUuid}@docker`,
PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT: "https",
PORTAL_DOMAIN_CONTROLLER_CONFIG_DIR: configDirectory,
PORTAL_DOMAIN_CONTROLLER_RELOAD_TRIGGER_FILE: reloadTriggerFile,
...overrides,
});
}
function workerEnv(group, overrides = {}) {
return envEntries({
WORKER_QUEUE_GROUP: group,
BULLMQ_REDIS_URL: "rediss://worker:other-secret@redis.example.test:6380/7",
...(group === "general"
? {
PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET: commandSecret,
PORTAL_DOMAIN_ORCHESTRATION_REQUIRED: "true",
}
: {}),
...overrides,
});
}
function envEntries(values) {
return Object.entries(values)
.filter(([, value]) => value !== undefined)
.map(([key, value]) => ({ key, value, is_preview: false }));
}
function exactStorages() {
return {
file_storages: [
{
uuid: "storage-config",
is_directory: true,
fs_path: configDirectory,
mount_path: configDirectory,
},
],
persistent_storages: [
{
uuid: "storage-reload",
host_path: reloadTriggerFile,
mount_path: reloadTriggerFile,
},
],
};
}
function fixture(overrides = {}) {
const controller = {
id: 101,
uuid: controllerUuid,
name: "hivegrid-portal-domain-controller",
build_pack: "dockerimage",
docker_registry_image_name: controllerImage,
docker_registry_image_tag: "previous",
pre_deployment_command: "",
post_deployment_command: "",
fqdn: "",
ports_mappings: stagingMetricsBinding,
status: "stopped",
custom_healthcheck_found: false,
health_check_enabled: true,
health_check_type: "http",
health_check_command: "",
health_check_interval: 30,
health_check_timeout: 10,
health_check_retries: 3,
health_check_start_period: 20,
...overrides.controller,
};
const workers = [
{ uuid: workerGeneralUuid, name: "worker-general", docker_registry_image_name: workerImage },
{ uuid: workerMailUuid, name: "worker-mail", docker_registry_image_name: workerImage },
];
const webCore = {
uuid: webCoreUuid,
name: "hivegrid-web",
build_pack: "dockerimage",
docker_registry_image_name: webImage,
};
const webPortal = {
uuid: webPortalUuid,
name: "hivegrid-portal",
build_pack: "dockerimage",
docker_registry_image_name: webImage,
};
return {
controller,
apps: [controller, webCore, webPortal, ...workers],
envByUuid: new Map([
[controllerUuid, controllerEnv(overrides.controllerEnv)],
[
webCoreUuid,
envEntries({
WEB_RUNTIME_SURFACE: "core",
PORTAL_CUSTOM_DOMAIN_CNAME_TARGET: overrides.webCnameTarget ?? stagingCname,
PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED: overrides.webCoreRuntimeEnabled ?? "true",
...overrides.webCoreEnv,
}),
],
[
webPortalUuid,
envEntries({
WEB_RUNTIME_SURFACE: "portal",
PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED: overrides.webPortalRuntimeEnabled ?? "true",
...overrides.webPortalEnv,
}),
],
[workerGeneralUuid, workerEnv("general", overrides.workerGeneralEnv)],
[workerMailUuid, workerEnv("mail")],
]),
storages: overrides.storages ?? exactStorages(),
stopDoesNotTransition: overrides.stopDoesNotTransition ?? false,
controllerProcessRunning: overrides.controllerProcessRunning ?? true,
controllerHealthRevision: overrides.controllerHealthRevision ?? controller.docker_registry_image_tag,
postStopHealthSequence: overrides.postStopHealthSequence ? [...overrides.postStopHealthSequence] : null,
stopRequested: false,
releaseMutationDrifts: overrides.releaseMutationDrifts ?? false,
compensationDoesNotRestore: overrides.compensationDoesNotRestore ?? false,
releasePatchCount: 0,
statusSequence: overrides.statusSequence ?? null,
allowedCsv: [controllerUuid, webCoreUuid, webPortalUuid, workerGeneralUuid, workerMailUuid].join(","),
};
}
function startFixtureServer(state) {
return startServer((request) => {
if (request.url === "/controller-healthz") {
const reachable = state.stopRequested && state.postStopHealthSequence?.length
? state.postStopHealthSequence.shift()
: state.controllerProcessRunning;
if (!reachable) return { destroy: true };
return {
payload: {
status: "ok",
service: "hivegrid-portal-domain-controller",
revision: state.controllerHealthRevision,
},
};
}
if (request.url === "/applications") return { payload: state.apps };
if (request.url === `/applications/${controllerUuid}/storages`) return { payload: state.storages };
const envMatch = /^\/applications\/([a-z0-9]{24})\/envs$/u.exec(request.url);
if (envMatch) return { payload: state.envByUuid.get(envMatch[1]) ?? [] };
if (request.url === `/deployments/${deploymentUuid}`) {
return {
payload: {
deployment_uuid: deploymentUuid,
application_id: state.controller.id,
application_name: "hivegrid-portal-domain-controller",
status: "finished",
},
};
}
if (request.url === `/applications/${controllerUuid}` && request.method === "PATCH") {
state.releasePatchCount += 1;
const patch = JSON.parse(request.body);
if (state.releaseMutationDrifts && state.releasePatchCount === 1) {
Object.assign(state.controller, patch, { health_check_command: "drifted-command" });
} else if (!(state.compensationDoesNotRestore && state.releasePatchCount > 1)) {
Object.assign(state.controller, patch);
}
return { payload: state.controller };
}
if (request.url === `/applications/${controllerUuid}/stop` && request.method === "POST") {
state.stopRequested = true;
if (!state.stopDoesNotTransition) {
state.controller.status = "exited:unhealthy";
state.controllerProcessRunning = false;
}
return { payload: { message: "Application stopping request queued." } };
}
if (request.url === `/applications/${controllerUuid}`) {
if (state.statusSequence?.length) state.controller.status = state.statusSequence.shift();
return { payload: state.controller };
}
return { status: 404, payload: {} };
});
}
function runHelper(serverUrl, ...args) {
const envOverrides = typeof args[0] === "object" && args[0] !== null ? args.shift() : {};
return new Promise((resolve) => {
const child = spawn(process.execPath, [scriptPath, ...args], {
env: {
PATH: process.env.PATH || "",
NODE_ENV: "test",
SELECTED_COOLIFY_API_URL: serverUrl,
SELECTED_COOLIFY_TOKEN: bearerToken,
COOLIFY_DEPLOYMENT_POLL_MS: "1",
COOLIFY_DEPLOYMENT_WAIT_ATTEMPTS: "2",
COOLIFY_CONTROLLER_DRAIN_HEALTH_URL: `${serverUrl}/controller-healthz`,
COOLIFY_CONTROLLER_DRAIN_FENCE_MS: "1",
...envOverrides,
},
stdio: ["ignore", "pipe", "pipe"],
});
let stdout = "";
let stderr = "";
child.stdout.setEncoding("utf8");
child.stderr.setEncoding("utf8");
child.stdout.on("data", (chunk) => {
stdout += chunk;
});
child.stderr.on("data", (chunk) => {
stderr += chunk;
});
child.on("close", (status) => resolve({ status, stdout, stderr }));
});
}
async function readBody(request) {
let body = "";
request.setEncoding("utf8");
for await (const chunk of request) body += chunk;
return body;
}
function startServer(responder) {
const requests = [];
const serverErrors = [];
const server = http.createServer(async (request, response) => {
const recorded = {
method: request.method,
url: request.url,
authorization: request.headers.authorization,
body: await readBody(request),
};
requests.push(recorded);
try {
const result = await responder(recorded);
if (result?.destroy) {
response.destroy();
return;
}
response.writeHead(result?.status || 200, { "content-type": "application/json" });
response.end(JSON.stringify(result?.payload ?? {}));
} catch (error) {
serverErrors.push(error);
response.writeHead(500, { "content-type": "application/json" });
response.end("{}");
}
});
return new Promise((resolve, reject) => {
server.once("error", reject);
server.listen(0, "127.0.0.1", () =>
resolve({
url: `http://127.0.0.1:${server.address().port}`,
requests,
serverErrors,
close: () => new Promise((done, failed) => server.close((error) => (error ? failed(error) : done()))),
})
);
});
}
function assertSecretSafe(result) {
for (const secret of [bearerToken, commandSecret, otherCommandSecret, metricsToken, "controller:secret", "worker:other-secret"]) {
assert.doesNotMatch(`${result.stdout}${result.stderr}`, new RegExp(secret.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&")));
}
}
describe("portal-domain controller Coolify deployment helper", () => {
it("accepts only the private two-mount runtime with matched worker-general HMAC wiring", async () => {
const state = fixture();
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "assert-runtime", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /runtime, mounts, and worker-general HMAC wiring verified/);
assert.equal(result.stderr, "");
assertSecretSafe(result);
assert.deepEqual(server.serverErrors, []);
assert.ok(server.requests.some(({ url }) => url === `/applications/${controllerUuid}/storages`));
assert.ok(server.requests.some(({ url }) => url === `/applications/${workerGeneralUuid}/envs`));
assert.ok(server.requests.some(({ url }) => url === `/applications/${webPortalUuid}/envs`));
assert.ok(server.requests.every(({ authorization }) => authorization === `Bearer ${bearerToken}`));
} finally {
await server.close();
}
});
it("accepts only Coolify's exact automatic metadata keys", async () => {
const accepted = fixture({
controllerEnv: {
COOLIFY_BRANCH: "main",
COOLIFY_CONTAINER_NAME: "controller-container",
COOLIFY_FQDN: "",
COOLIFY_RESOURCE_UUID: controllerUuid,
COOLIFY_URL: "",
},
});
const acceptedServer = await startFixtureServer(accepted);
try {
const result = await runHelper(acceptedServer.url, "assert-runtime", "staging", controllerUuid, accepted.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 0, result.stderr);
assertSecretSafe(result);
} finally {
await acceptedServer.close();
}
const rejected = fixture({ controllerEnv: { COOLIFY_DEPLOYMENT_TOKEN: "not-allowed" } });
const rejectedServer = await startFixtureServer(rejected);
try {
const result = await runHelper(rejectedServer.url, "assert-runtime", "staging", controllerUuid, rejected.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /forbidden privileged environment keys/);
assertSecretSafe(result);
} finally {
await rejectedServer.close();
}
});
it("keeps the controller probe on the exact internal port behind the mesh metrics binding", async () => {
const accepted = fixture({ controllerEnv: { PORTAL_DOMAIN_CONTROLLER_PORT: "8080" } });
const acceptedServer = await startFixtureServer(accepted);
try {
const result = await runHelper(acceptedServer.url, "assert-runtime", "staging", controllerUuid, accepted.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 0, result.stderr);
assertSecretSafe(result);
} finally {
await acceptedServer.close();
}
const rejected = fixture({ controllerEnv: { PORTAL_DOMAIN_CONTROLLER_PORT: "8081" } });
const rejectedServer = await startFixtureServer(rejected);
try {
const result = await runHelper(rejectedServer.url, "assert-runtime", "staging", controllerUuid, rejected.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /must be exactly 8080/);
assertSecretSafe(result);
} finally {
await rejectedServer.close();
}
});
it("rejects a worker-general HMAC mismatch before any mutation", async () => {
const state = fixture({ workerGeneralEnv: { PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET: otherCommandSecret } });
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(result.stderr, /HMAC secrets must match/);
assert.ok(server.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("rejects a broad Traefik root mount or missing reload sentinel", async () => {
for (const storages of [
[{ type: "file", is_directory: true, fs_path: "/data/coolify/proxy/dynamic", mount_path: "/data/coolify/proxy/dynamic" }],
{
file_storages: exactStorages().file_storages,
persistent_storages: [
{
...exactStorages().persistent_storages[0],
host_path: "/data/coolify/proxy/dynamic/not-the-reload-sentinel",
},
],
},
]) {
const state = fixture({ storages });
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "assert-runtime", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /exactly two narrow bind mounts|config subdirectory and RW reload sentinel/);
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("rejects missing or malformed environment-specific Traefik routing identities", async () => {
for (const controllerEnvOverride of [
{ PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE: undefined },
{ PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE: "http://hivegrid-portal:8080" },
{ PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT: "https;malformed" },
{ PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT: "websecure" },
]) {
const state = fixture({ controllerEnv: controllerEnvOverride });
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "assert-runtime", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /BACKEND_SERVICE|ENTRYPOINT/);
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("rejects a missing or ambiguous allowlisted portal surface before any mutation", async () => {
const duplicatePortalUuid = "q".repeat(24);
const missing = fixture({ webPortalEnv: { WEB_RUNTIME_SURFACE: undefined } });
const ambiguous = fixture();
ambiguous.apps.push({
uuid: duplicatePortalUuid,
name: "hivegrid-portal-shadow",
build_pack: "dockerimage",
docker_registry_image_name: webImage,
});
ambiguous.envByUuid.set(duplicatePortalUuid, envEntries({ WEB_RUNTIME_SURFACE: "portal" }));
ambiguous.allowedCsv = `${ambiguous.allowedCsv},${duplicatePortalUuid}`;
for (const state of [missing, ambiguous]) {
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(result.stderr, /exactly one allowlisted hivegrid-portal surface/);
assert.ok(server.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("rejects a valid Docker service name that does not identify the resolved portal resource", async () => {
const state = fixture({
controllerEnv: {
PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE: `https-0-${webCoreUuid}@docker`,
},
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(result.stderr, /must target the exact allowlisted hivegrid-portal Docker service/);
assert.ok(server.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("rejects CNAME drift and unexpected controller credentials before mutation", async () => {
for (const state of [
fixture({ webCnameTarget: "production-ingress.example.test" }),
fixture({ controllerEnv: { STORAGE_SECRET_ACCESS_KEY: "must-never-reach-controller" } }),
]) {
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(result.stderr, /hivegrid-web must use exactly|least-privilege environment allowlist/);
assert.ok(server.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("requires the exact custom-domain runtime opt-in on both staging web surfaces", async () => {
for (const state of [
fixture({ webCoreEnv: { PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED: undefined } }),
fixture({ webCoreRuntimeEnabled: "false" }),
fixture({ webCoreRuntimeEnabled: "1" }),
fixture({ webPortalEnv: { PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED: undefined } }),
fixture({ webPortalRuntimeEnabled: "false" }),
fixture({ webPortalRuntimeEnabled: "TRUE" }),
]) {
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(result.stderr, /PORTAL_CUSTOM_DOMAIN_RUNTIME_ENABLED exactly to true in staging/);
assert.ok(server.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("pins each deployment environment to its exact CNAME target before mutation", async () => {
const cases = [
{
environment: "production",
state: fixture({ controller: { ports_mappings: productionMetricsBinding } }),
expected: new RegExp(`EXPECTED_CNAME must be exactly ${productionCname}`),
},
{
environment: "staging",
state: fixture({
controllerEnv: { PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME: productionCname },
webCnameTarget: productionCname,
}),
expected: new RegExp(`EXPECTED_CNAME must be exactly ${stagingCname}`),
},
{
environment: "preview",
state: fixture(),
expected: /deployment environment must be exactly staging or production/,
},
];
for (const { environment, state, expected } of cases) {
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", environment, controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(result.stderr, expected);
assert.ok(server.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("accepts the production environment only with the production CNAME target", async () => {
const state = fixture({
controller: { ports_mappings: productionMetricsBinding },
controllerEnv: { PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME: productionCname },
webCnameTarget: productionCname,
webCoreRuntimeEnabled: "false",
webPortalRuntimeEnabled: "false",
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "assert-runtime", "production", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 0, result.stderr);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("pins the explicit resource to the full SHA and clears deployment hooks", async () => {
const state = fixture();
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /immutable release configured/);
const patches = server.requests.filter(({ method }) => method === "PATCH");
assert.equal(patches.length, 1);
assert.deepEqual(JSON.parse(patches[0].body), {
pre_deployment_command: "",
post_deployment_command: "",
docker_registry_image_tag: revision,
...expectedControllerHealthConfig(),
});
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("verifies compensation after a rejected release mutation", async () => {
for (const compensationDoesNotRestore of [false, true]) {
const state = fixture({
controller: { health_check_interval: 0, health_check_start_period: 0 },
releaseMutationDrifts: true,
compensationDoesNotRestore,
});
const previousTag = state.controller.docker_registry_image_tag;
const previousHealthType = state.controller.health_check_type;
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision);
assert.equal(result.status, 1);
assert.match(
result.stderr,
compensationDoesNotRestore ? /compensation was incomplete/ : /previous configuration was restored/
);
assert.equal(server.requests.filter(({ method }) => method === "PATCH").length, 2);
if (!compensationDoesNotRestore) {
assert.equal(state.controller.docker_registry_image_tag, previousTag);
assert.equal(state.controller.health_check_type, previousHealthType);
assert.equal(state.controller.health_check_interval, 0);
assert.equal(state.controller.health_check_start_period, 0);
}
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("stops and drains the old controller before a paired web rollout", async () => {
const state = fixture({ controller: { docker_registry_image_tag: revision, status: "running:healthy" } });
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "stop-and-drain", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /stopped and command worker drained/);
assert.deepEqual(
server.requests.filter(({ method, url }) => method === "POST" && url.endsWith("/stop")).map(({ url }) => url),
[`/applications/${controllerUuid}/stop`]
);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("fails closed for operator recovery when pre-stop health is unreachable despite exited status", async () => {
const state = fixture({
controller: { docker_registry_image_tag: revision, status: "exited:unhealthy" },
controllerProcessRunning: false,
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "stop-and-drain", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /pre-stop health is unreachable or not revision-bound; operator recovery is required/);
assert.equal(server.requests.some(({ method, url }) => method === "POST" && url.endsWith("/stop")), false);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("does not trust stale exited status while the queued stop and live health lag", async () => {
const state = fixture({
controller: { docker_registry_image_tag: revision, status: "exited:unhealthy" },
statusSequence: ["exited:unhealthy", "exited:unhealthy", "running:healthy", "exited:unhealthy", "exited:unhealthy"],
postStopHealthSequence: [true, true, false, false],
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(
server.url,
{ COOLIFY_DEPLOYMENT_WAIT_ATTEMPTS: "4" },
"stop-and-drain",
"staging",
controllerUuid,
state.allowedCsv,
controllerImage,
workerImage
);
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /stopped and command worker drained/);
assert.deepEqual(
server.requests.filter(({ method, url }) => method === "POST" && url.endsWith("/stop")).map(({ url }) => url),
[`/applications/${controllerUuid}/stop`]
);
assert.equal(server.requests.filter(({ method, url }) => method === "GET" && url === `/applications/${controllerUuid}`).length, 5);
assert.equal(server.requests.filter(({ url }) => url === "/controller-healthz").length, 5);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("fails closed when Coolify cannot prove the controller stopped", async () => {
const state = fixture({
controller: { docker_registry_image_tag: revision, status: "running:healthy" },
stopDoesNotTransition: true,
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "stop-and-drain", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /did not stop and drain/);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("fails closed before stop when mesh health belongs to another revision", async () => {
const state = fixture({
controller: { docker_registry_image_tag: revision, status: "running:healthy" },
controllerHealthRevision: "b".repeat(40),
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "stop-and-drain", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /pre-stop health is unreachable or not revision-bound/);
assert.equal(server.requests.some(({ method, url }) => method === "POST" && url.endsWith("/stop")), false);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("snapshots only a validated immutable controller release without mutation", async () => {
const valid = fixture({
controller: {
docker_registry_image_tag: revision,
custom_healthcheck_found: false,
...expectedControllerHealthConfig(),
},
});
const validServer = await startFixtureServer(valid);
try {
const result = await runHelper(validServer.url, "snapshot-release", "staging", controllerUuid, valid.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 0, result.stderr);
assert.equal(result.stdout, revision);
assert.equal(result.stderr, "");
assert.ok(validServer.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await validServer.close();
}
for (const controller of [
{ docker_registry_image_tag: "staging" },
{ docker_registry_image_tag: revision, custom_healthcheck_found: false, ...expectedControllerHealthConfig(), health_check_command: "drifted" },
]) {
const invalid = fixture({ controller });
const invalidServer = await startFixtureServer(invalid);
try {
const result = await runHelper(
invalidServer.url,
"snapshot-release",
"staging",
controllerUuid,
invalid.allowedCsv,
controllerImage,
workerImage,
);
assert.equal(result.status, 1);
assert.match(result.stderr, /full lowercase Git SHA|revision-bound command health configuration drifted/);
assert.ok(invalidServer.requests.every(({ method }) => method === "GET"));
assertSecretSafe(result);
} finally {
await invalidServer.close();
}
}
});
it("rejects a mutable release tag before contacting Coolify", async () => {
const state = fixture();
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "set-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, "staging");
assert.equal(result.status, 1);
assert.match(result.stderr, /full lowercase Git SHA/);
assert.deepEqual(server.requests, []);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("binds the completed deployment to a revision-bound command healthz and readyz contract", async () => {
const state = fixture({
controller: {
docker_registry_image_tag: revision,
status: "running:healthy",
custom_healthcheck_found: false,
...expectedControllerHealthConfig(),
},
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(
server.url,
"assert-release",
"staging",
controllerUuid,
state.allowedCsv,
controllerImage,
workerImage,
revision,
deploymentUuid,
);
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /healthz, readyz, and immutable revision verified/);
assert.ok(server.requests.some(({ url }) => url === `/deployments/${deploymentUuid}`));
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("tolerates at least eight stale exited statuses within the freshly deployed controller grace period", async () => {
const state = fixture({
controller: {
docker_registry_image_tag: revision,
status: "exited:unhealthy",
custom_healthcheck_found: false,
...expectedControllerHealthConfig(),
},
// First entry feeds the runtime-contract lookup, the rest the poll loop.
statusSequence: [
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"exited:unhealthy",
"running:healthy",
],
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(
server.url,
{ COOLIFY_DEPLOYMENT_WAIT_ATTEMPTS: "10", COOLIFY_FAILED_STATUS_GRACE_MS: "60000" },
"assert-release",
"staging",
controllerUuid,
state.allowedCsv,
controllerImage,
workerImage,
revision,
deploymentUuid
);
assert.equal(result.status, 0, result.stderr);
assert.match(result.stdout, /healthz, readyz, and immutable revision verified/);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("still fails closed when the controller stays in a failed runtime state", async () => {
const state = fixture({
controller: {
docker_registry_image_tag: revision,
status: "exited:unhealthy",
custom_healthcheck_found: false,
...expectedControllerHealthConfig(),
},
});
const server = await startFixtureServer(state);
try {
const result = await runHelper(
server.url,
{
COOLIFY_DEPLOYMENT_POLL_MS: "10",
COOLIFY_DEPLOYMENT_WAIT_ATTEMPTS: "6",
COOLIFY_FAILED_STATUS_GRACE_MS: "5",
},
"assert-release",
"staging",
controllerUuid,
state.allowedCsv,
controllerImage,
workerImage,
revision,
deploymentUuid
);
assert.equal(result.status, 1);
assert.match(result.stderr, /entered a terminal runtime state/);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("rejects an invalid failed-status grace before contacting Coolify", async () => {
const state = fixture();
const server = await startFixtureServer(state);
try {
const result = await runHelper(
server.url,
{ COOLIFY_FAILED_STATUS_GRACE_MS: "-1" },
"assert-release",
"staging",
controllerUuid,
state.allowedCsv,
controllerImage,
workerImage,
revision,
deploymentUuid
);
assert.equal(result.status, 1);
assert.match(result.stderr, /COOLIFY_FAILED_STATUS_GRACE_MS must be a non-negative safe integer/);
assert.deepEqual(server.requests, []);
assertSecretSafe(result);
} finally {
await server.close();
}
});
it("rejects a public controller route, an image-healthcheck override, or command-health drift", async () => {
for (const controller of [
{ fqdn: "https://controller.example.test" },
{
docker_registry_image_tag: revision,
status: "running:healthy",
custom_healthcheck_found: true,
...expectedControllerHealthConfig(),
},
{
docker_registry_image_tag: revision,
status: "running:healthy",
custom_healthcheck_found: false,
...expectedControllerHealthConfig(),
health_check_command: "curl http://127.0.0.1:8080/readyz",
},
]) {
const state = fixture({ controller });
const server = await startFixtureServer(state);
try {
const args = controller.fqdn
? ["assert-runtime", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage]
: ["assert-release", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage, revision, deploymentUuid];
const result = await runHelper(server.url, ...args);
assert.equal(result.status, 1);
assert.match(result.stderr, /must remain private|command health configuration drifted/);
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
it("rejects a public or missing metrics port instead of exposing the controller beyond the mesh", async () => {
for (const ports_mappings of [null, "0.0.0.0:19120:8080", "10.42.0.3:19120:8080,10.42.0.3:19121:8080"]) {
const state = fixture({ controller: { ports_mappings } });
const server = await startFixtureServer(state);
try {
const result = await runHelper(server.url, "assert-runtime", "staging", controllerUuid, state.allowedCsv, controllerImage, workerImage);
assert.equal(result.status, 1);
assert.match(result.stderr, /metrics only through the exact mesh binding/);
assertSecretSafe(result);
} finally {
await server.close();
}
}
});
});
@@ -36,7 +36,7 @@
{
"name": "apps/web auth services (critical-path: Auth)",
"pathPrefixes": ["apps/web/app/services/auth/"],
"includeGlobs": ["apps/web/app/services/auth"],
"includeGlobs": ["apps/web/app/services/auth", "apps/web/app/routes/login.magic-link-security.test.ts"],
"statements": 97,
"branches": 88,
"sprintTarget": { "statements": 90, "branches": 85 },
@@ -297,14 +297,6 @@
"branches": 80,
"sprintTarget": { "statements": 70, "branches": 60 }
},
{
"name": "packages/plugins",
"pathPrefixes": ["packages/plugins/src/"],
"includeGlobs": ["packages/plugins/src", "packages/plugins/test"],
"statements": 99,
"branches": 86,
"sprintTarget": { "statements": 98, "branches": 80 }
},
{
"name": "packages/plugin-sdk",
"pathPrefixes": ["packages/plugin-sdk/src/"],
@@ -1,138 +0,0 @@
#!/usr/bin/env node
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const manifestRoot = path.join(repoRoot, "docs", "feature-manifests");
const classifications = new Set(["core", "plugin-candidate", "remove-candidate", "mixed"]);
const ownerships = new Set(["tenant-owned", "admin-managed", "hybrid", "system-only"]);
export function parseArgs(argv) {
const args = {};
for (let index = 0; index < argv.length; index += 1) {
const token = argv[index];
if (!token.startsWith("--")) {
throw new Error(`Unexpected argument: ${token}`);
}
const key = token.slice(2);
if (key === "force") {
args.force = true;
continue;
}
const value = argv[index + 1];
if (!value || value.startsWith("--")) {
throw new Error(`Missing value for --${key}`);
}
args[key] = value;
index += 1;
}
return args;
}
export function createFeatureManifest({
id,
title,
classification = "plugin-candidate",
ownership = "hybrid",
owner = "hivegrid",
description = "Describe the feature contract before implementation.",
lastReviewed = process.env.HIVEGRID_MANIFEST_DATE ?? new Date().toISOString().slice(0, 10),
}) {
if (!/^[a-z0-9][a-z0-9-]*$/.test(id ?? "")) {
throw new Error("--id must match ^[a-z0-9][a-z0-9-]*$");
}
if (!title?.trim()) {
throw new Error("--title is required");
}
if (!classifications.has(classification)) {
throw new Error(`--classification must be one of ${Array.from(classifications).join(", ")}`);
}
if (!ownerships.has(ownership)) {
throw new Error(`--ownership must be one of ${Array.from(ownerships).join(", ")}`);
}
const pruningAction = classification === "core" ? "keep" : classification === "remove-candidate" ? "remove" : classification === "plugin-candidate" ? "extract-plugin" : "review";
return {
schemaVersion: "1.0",
id,
title,
classification,
status: "proposed",
owner,
description,
rationale: ["Document why this belongs in HiveGrid, a plugin, or the removal backlog before code changes land."],
codeAreas: ["Add concrete source paths before implementation, for example apps/web/app/routes/... or packages/..."],
dependencies: [],
consumers: [],
integration: {
ownership,
surfaces: {
adminRoutes: [],
tenantRoutes: [],
publicRoutes: [],
apiRoutes: [],
},
configuration: {
admin: [],
tenant: [],
environment: [],
secrets: [],
},
workers: {
required: false,
queues: [],
jobs: [],
notes: [],
},
externalProviders: [],
permissions: ["app.feature.view"],
auditEvents: ["feature.viewed"],
billingImpacts: ["None declared yet; confirm plan gates, metering, and provider costs before implementation."],
uat: ["Verify positive access, denied access, tenant isolation, i18n output, and host-aware routing for this feature."],
},
boundaries: {
mustKeep: [],
mayMoveToPlugin: [],
mustNotTouch: [],
},
pruning: {
phase: "planning",
action: pruningAction,
notes: ["Generated scaffold. Replace placeholders before treating this manifest as implementation-ready."],
},
validation: {
source: [`docs/feature-manifests/${id}.json`],
lastReviewed,
},
};
}
export function writeFeatureManifest(args, root = repoRoot) {
const manifest = createFeatureManifest(args);
const target = path.join(root, "docs", "feature-manifests", `${manifest.id}.json`);
if (fs.existsSync(target) && !args.force) {
throw new Error(`${path.relative(root, target)} already exists. Pass --force to overwrite.`);
}
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, `${JSON.stringify(manifest, null, 2)}\n`);
return { manifest, target };
}
function printUsage() {
console.error("Usage: node scripts/create-feature-manifest.mjs --id my-feature --title \"My Feature\" [--classification plugin-candidate] [--ownership hybrid] [--owner hivegrid] [--description text] [--force]");
}
const isCli = process.argv[1] && fileURLToPath(import.meta.url) === path.resolve(process.argv[1]);
if (isCli) {
try {
const result = writeFeatureManifest(parseArgs(process.argv.slice(2)));
console.log(`Created ${path.relative(repoRoot, result.target)}`);
} catch (error) {
printUsage();
console.error(`FAIL ${error.message}`);
process.exit(1);
}
}
@@ -1,69 +0,0 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import assert from "node:assert/strict";
import { afterEach, describe, it } from "vitest";
import { createFeatureManifest, parseArgs, writeFeatureManifest } from "./create-feature-manifest.mjs";
const fixtures = [];
function createRoot() {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "feature-manifest-"));
fixtures.push(root);
return root;
}
afterEach(() => {
while (fixtures.length > 0) {
fs.rmSync(fixtures.pop(), { recursive: true, force: true });
}
});
describe("create-feature-manifest", () => {
it("creates an integration-aware manifest scaffold", () => {
const manifest = createFeatureManifest({
id: "customer-health",
title: "Customer Health",
classification: "plugin-candidate",
ownership: "admin-managed",
lastReviewed: "2026-05-15",
});
assert.equal(manifest.schemaVersion, "1.0");
assert.equal(manifest.id, "customer-health");
assert.equal(manifest.pruning.action, "extract-plugin");
assert.equal(manifest.integration.ownership, "admin-managed");
assert.deepEqual(Object.keys(manifest.integration.surfaces), ["adminRoutes", "tenantRoutes", "publicRoutes", "apiRoutes"]);
assert.match(manifest.integration.permissions[0], /^app\./);
assert.match(manifest.integration.auditEvents[0], /^feature\./);
assert.equal(manifest.validation.lastReviewed, "2026-05-15");
});
it("writes without overwriting existing manifests unless forced", () => {
const root = createRoot();
const args = {
id: "agent-demo",
title: "Agent Demo",
classification: "core",
ownership: "system-only",
lastReviewed: "2026-05-15",
};
const first = writeFeatureManifest(args, root);
assert.equal(path.relative(root, first.target), "docs/feature-manifests/agent-demo.json");
assert.equal(JSON.parse(fs.readFileSync(first.target, "utf8")).pruning.action, "keep");
assert.throws(() => writeFeatureManifest(args, root), /already exists/);
assert.doesNotThrow(() => writeFeatureManifest({ ...args, force: true }, root));
});
it("parses CLI flags and rejects invalid values", () => {
assert.deepEqual(parseArgs(["--id", "my-feature", "--title", "My Feature", "--force"]), {
id: "my-feature",
title: "My Feature",
force: true,
});
assert.throws(() => createFeatureManifest({ id: "Bad_ID", title: "Bad" }), /--id must match/);
assert.throws(() => createFeatureManifest({ id: "ok", title: "" }), /--title is required/);
assert.throws(() => createFeatureManifest({ id: "ok", title: "OK", classification: "legacy" }), /--classification must be/);
});
});
@@ -0,0 +1,369 @@
// @vitest-environment node
import { createHash } from "node:crypto";
import type { DbClient } from "@hivegrid/db/client.server";
import {
customerPortalCommercialProducts,
entitlementLimitTypes,
featureKeys,
getFeatureGate,
standardEntitlementPlans,
type EntitlementPlanId,
} from "@hivegrid/entitlements";
import { describe, expect, it, vi } from "vitest";
import {
assessDatabaseCatalog,
buildCustomerPortalCatalogPlan,
customerPortalCatalogPlanIsBlocked,
customerPortalCatalogPlanIsComplete,
LagoCatalogClient,
planProviderCatalog,
reconcileBasePlanPortalFeatures,
type DatabaseCatalogSnapshot,
type DatabaseBasePlanSnapshot,
type DatabaseProductSnapshot,
type ProviderCatalogSnapshot,
} from "./catalog";
const testLagoOrganizationId = "test-staging-organization-id";
const testLagoIdentity = {
expectedOrganizationIdSha256: createHash("sha256").update(testLagoOrganizationId).digest("hex"),
};
function lagoOrganizationResponse(name = "HiveGrid Staging", id = testLagoOrganizationId): Response {
return Response.json({ organization: { lago_id: id, name } });
}
function providerSnapshot(): ProviderCatalogSnapshot {
return {
plan: {
code: "customer_portal_monthly",
name: "Customer Portal",
description: customerPortalCommercialProducts.monthlyAddOn.description,
interval: "monthly",
amount_cents: 1_999,
amount_currency: "EUR",
pay_in_advance: true,
taxes: [{ code: "de-vat-19" }],
},
addOn: {
code: "customer_portal_domain_setup",
name: "Customer Portal Domain Setup",
description: customerPortalCommercialProducts.customDomainSetup.description,
amount_cents: 29_999,
amount_currency: "EUR",
taxes: [{ code: "de-vat-19" }],
},
};
}
function commercialProduct(definition: (typeof customerPortalCommercialProducts)[keyof typeof customerPortalCommercialProducts]): DatabaseProductSnapshot {
return {
billingProviderId: `hivegrid_commercial_product_${definition.code}`,
code: definition.code,
title: definition.title,
description: definition.description,
kind: definition.source,
order: definition.catalogOrder,
model: 0,
active: true,
public: definition.public,
groupTitle: "Customer Portal",
groupDescription: null,
badge: null,
billingAddressCollection: "auto",
hasQuantity: false,
canBuyAgain: definition.source === "one_time_setup",
lagoPlanCode: definition.source === "recurring_add_on" ? definition.code : null,
features: definition.featureKeys.map((name, index) => ({
order: index + 1,
title: getFeatureGate(name)!.title,
name,
code: null,
type: entitlementLimitTypes.included,
value: definition.includedQuantity ?? entitlementLimitTypes.included,
quotaValue: null,
href: null,
badge: getFeatureGate(name)!.title,
accumulate: false,
})),
prices:
definition.amountCents === null || definition.currency === null
? []
: [
{
billingProviderId: `hivegrid_commercial_price_${definition.code}`,
lagoFeeCode: definition.code,
molliePriceReference: `hivegrid_commercial_price_${definition.code}`,
type: definition.source === "recurring_add_on" ? 1 : 0,
billingPeriod: definition.source === "recurring_add_on" ? 3 : 0,
price: (definition.amountCents / 100).toFixed(2),
currency: definition.currency.toLowerCase(),
trialDays: 0,
active: true,
},
],
};
}
function databaseSnapshot(): DatabaseCatalogSnapshot {
return {
commercialProducts: Object.values(customerPortalCommercialProducts).map(commercialProduct),
basePlans: [basePlan("starter"), basePlan("pro"), basePlan("business")],
};
}
function basePlan(planCode: EntitlementPlanId): DatabaseBasePlanSnapshot {
const plan = standardEntitlementPlans.find((candidate) => candidate.id === planCode)!;
const feature = plan.features.find((candidate) => candidate.featureKey === featureKeys.customerPortal)!;
return {
id: `${planCode}-product-id`,
code: planCode,
kind: "base_plan",
portalFeatures: [
{
order: Math.round(feature.order),
title: feature.label,
name: feature.featureKey,
code: null,
type: feature.limitType,
value: feature.limit ?? feature.limitType,
quotaValue: null,
href: null,
badge: getFeatureGate(featureKeys.customerPortal)!.title,
accumulate: feature.limitType === entitlementLimitTypes.monthly,
},
],
};
}
describe("customer-portal catalog plan", () => {
it("recognizes the canonical provider and database state", () => {
const plan = buildCustomerPortalCatalogPlan(providerSnapshot(), databaseSnapshot());
expect(customerPortalCatalogPlanIsComplete(plan)).toBe(true);
expect(customerPortalCatalogPlanIsBlocked(plan)).toBe(false);
});
it("creates missing resources, safely updates tax-only drift, and blocks commercial provider drift", () => {
expect(planProviderCatalog({ plan: null, addOn: null }).map((action) => action.action)).toEqual(["create", "create"]);
const missingTax = providerSnapshot();
missingTax.plan!.taxes = [];
missingTax.addOn!.taxes = [];
expect(planProviderCatalog(missingTax)).toEqual([
expect.objectContaining({ action: "update", driftFields: ["taxCodes"] }),
expect.objectContaining({ action: "update", driftFields: ["taxCodes"] }),
]);
const drifted = providerSnapshot();
drifted.plan!.amount_cents = 1;
const actions = planProviderCatalog(drifted);
expect(actions[0]).toMatchObject({ action: "drift", driftFields: ["amountCents"] });
});
it("distinguishes reconcilable commercial rows from a safely missing base-plan portal feature", () => {
const missing = databaseSnapshot();
const reconcilable = assessDatabaseCatalog({ ...missing, commercialProducts: missing.commercialProducts.slice(1) });
expect(reconcilable.reconcileIssues).toContain("customer_portal_monthly: product missing");
expect(reconcilable.blockingIssues).toEqual([]);
const missingFeature = databaseSnapshot();
const baseFeatureReconciliation = assessDatabaseCatalog({
...missingFeature,
basePlans: missingFeature.basePlans.map((plan) => (plan.code === "business" ? { ...plan, portalFeatures: [] } : plan)),
});
expect(baseFeatureReconciliation.reconcileIssues).toContain("business: canonical customer_portal feature missing");
expect(baseFeatureReconciliation.blockingIssues).toEqual([]);
});
it("blocks a missing base-plan product and never invents a replacement", () => {
const snapshot = databaseSnapshot();
const assessment = assessDatabaseCatalog({
...snapshot,
basePlans: snapshot.basePlans.filter((plan) => plan.code !== "business"),
});
expect(assessment.blockingIssues).toContain("business: expected exactly one canonical base-plan product");
expect(assessment.reconcileIssues).not.toContain("business: canonical customer_portal feature missing");
const duplicateAssessment = assessDatabaseCatalog({
...snapshot,
basePlans: [...snapshot.basePlans, basePlan("business")],
});
expect(duplicateAssessment.blockingIssues).toContain("business: expected exactly one canonical base-plan product");
});
it("blocks an existing wrong or duplicate portal feature instead of updating or deleting it", () => {
const snapshot = databaseSnapshot();
const business = snapshot.basePlans.find((plan) => plan.code === "business")!;
const wrongFeature = {
...business,
portalFeatures: business.portalFeatures.map((feature) => ({ ...feature, type: entitlementLimitTypes.notIncluded, value: 0 })),
};
const wrongAssessment = assessDatabaseCatalog({
...snapshot,
basePlans: snapshot.basePlans.map((plan) => (plan === business ? wrongFeature : plan)),
});
expect(wrongAssessment.blockingIssues).toContain("business: existing customer_portal feature differs from the canonical contract");
const duplicateAssessment = assessDatabaseCatalog({
...snapshot,
basePlans: snapshot.basePlans.map((plan) =>
plan === business ? { ...business, portalFeatures: [...business.portalFeatures, ...business.portalFeatures] } : plan
),
});
expect(duplicateAssessment.blockingIssues).toContain("business: duplicate customer_portal feature rows");
});
it("creates only a missing canonical portal feature and leaves every other plan feature untouched", async () => {
const snapshot = databaseSnapshot();
const baseProducts = snapshot.basePlans.map((plan) => ({
id: plan.id,
code: plan.code,
kind: "base_plan",
features: plan.code === "business" ? [] : plan.portalFeatures,
prices: [],
}));
const create = vi.fn().mockResolvedValue({});
const db = {
subscriptionProduct: { findMany: vi.fn().mockResolvedValue(baseProducts) },
subscriptionFeature: { create },
} as unknown as DbClient;
await expect(reconcileBasePlanPortalFeatures(db)).resolves.toEqual(["business"]);
expect(create).toHaveBeenCalledTimes(1);
expect(create).toHaveBeenCalledWith({
data: expect.objectContaining({
subscriptionProductId: "business-product-id",
order: Math.round(
standardEntitlementPlans
.find((candidate) => candidate.id === "business")!
.features.find((candidate) => candidate.featureKey === featureKeys.customerPortal)!.order
),
name: featureKeys.customerPortal,
type: entitlementLimitTypes.included,
value: entitlementLimitTypes.included,
}),
});
});
it("blocks a title collision that the shared seed helper could otherwise take over", () => {
const snapshot = databaseSnapshot();
const monthly = snapshot.commercialProducts.find((product) => product.code === "customer_portal_monthly")!;
const collision = { ...monthly, billingProviderId: "legacy-product", code: "legacy_customer_portal" };
const assessment = assessDatabaseCatalog({
...snapshot,
commercialProducts: [collision, ...snapshot.commercialProducts.filter((product) => product !== monthly)],
});
expect(assessment.blockingIssues).toContain("customer_portal_monthly: existing seed-key collision would mutate another product");
});
it("does not report checkout-relevant product or price drift as complete", () => {
const snapshot = databaseSnapshot();
const monthly = snapshot.commercialProducts.find((product) => product.code === "customer_portal_monthly")!;
const driftedMonthly = {
...monthly,
canBuyAgain: true,
prices: monthly.prices.map((price) => ({ ...price, molliePriceReference: "wrong-reference", trialDays: 14 })),
};
const assessment = assessDatabaseCatalog({
...snapshot,
commercialProducts: snapshot.commercialProducts.map((product) => (product === monthly ? driftedMonthly : product)),
});
expect(assessment.reconcileIssues).toEqual(
expect.arrayContaining(["customer_portal_monthly: product metadata differs", "customer_portal_monthly: canonical price contract differs"])
);
});
it("does not report commercial feature property drift as complete", () => {
const snapshot = databaseSnapshot();
const monthly = snapshot.commercialProducts.find((product) => product.code === "customer_portal_monthly")!;
const driftedMonthly = {
...monthly,
features: monthly.features.map((feature, index) =>
index === 0 ? { ...feature, order: 99, title: "Wrong", type: entitlementLimitTypes.notIncluded, value: 0, badge: null, accumulate: true } : feature
),
};
const assessment = assessDatabaseCatalog({
...snapshot,
commercialProducts: snapshot.commercialProducts.map((product) => (product === monthly ? driftedMonthly : product)),
});
expect(assessment.reconcileIssues).toContain("customer_portal_monthly: feature contract differs");
});
it("blocks additional active prices that the shared seed helper cannot remove", () => {
const snapshot = databaseSnapshot();
const monthly = snapshot.commercialProducts.find((product) => product.code === "customer_portal_monthly")!;
const withUnexpectedActivePrice = {
...monthly,
prices: [...monthly.prices, { ...monthly.prices[0]!, billingPeriod: 4, billingProviderId: "unexpected-yearly", lagoFeeCode: "unexpected-yearly" }],
};
const assessment = assessDatabaseCatalog({
...snapshot,
commercialProducts: snapshot.commercialProducts.map((product) => (product === monthly ? withUnexpectedActivePrice : product)),
});
expect(assessment.blockingIssues).toContain("customer_portal_monthly: unexpected active price cannot be removed by reconciliation");
});
});
describe("Lago customer-portal catalog client", () => {
it("treats 404 reads as missing without leaking credentials", async () => {
const fetchImpl = vi
.fn<typeof fetch>()
.mockImplementation(async (url) => (String(url).endsWith("/organizations") ? lagoOrganizationResponse() : new Response(null, { status: 404 })));
const client = new LagoCatalogClient({ apiUrl: "https://lago.example.test", apiKey: "secret-key", fetchImpl }, testLagoIdentity);
await expect(client.readCatalog()).resolves.toEqual({ plan: null, addOn: null });
for (const call of fetchImpl.mock.calls) {
expect(String(call[0])).not.toContain("secret-key");
expect(new Headers(call[1]?.headers).get("authorization")).toBe("Bearer secret-key");
}
});
it("creates and updates the exact taxed recurring plan and one-time add-on contracts", async () => {
const fetchImpl = vi.fn<typeof fetch>().mockImplementation(async (url, init) => {
if (String(url).endsWith("/organizations")) return lagoOrganizationResponse();
const body = JSON.parse(String(init?.body)) as { plan?: unknown; add_on?: unknown };
if (body.plan) return Response.json({ plan: providerSnapshot().plan });
return Response.json({ add_on: providerSnapshot().addOn });
});
const client = new LagoCatalogClient({ apiUrl: "https://lago.example.test", apiKey: "secret-key", fetchImpl }, testLagoIdentity);
await client.createPlan();
await client.createAddOn();
await client.updatePlan();
await client.updateAddOn();
expect(JSON.parse(String(fetchImpl.mock.calls[1]?.[1]?.body))).toEqual({
plan: expect.objectContaining({
code: "customer_portal_monthly",
interval: "monthly",
amount_cents: 1_999,
pay_in_advance: true,
tax_codes: ["de-vat-19"],
}),
});
expect(JSON.parse(String(fetchImpl.mock.calls[3]?.[1]?.body))).toEqual({
add_on: expect.objectContaining({
code: "customer_portal_domain_setup",
amount_cents: 29_999,
amount_currency: "EUR",
tax_codes: ["de-vat-19"],
}),
});
expect(fetchImpl.mock.calls[5]?.[1]?.method).toBe("PUT");
expect(JSON.parse(String(fetchImpl.mock.calls[5]?.[1]?.body))).toEqual({
plan: expect.objectContaining({ code: "customer_portal_monthly", tax_codes: ["de-vat-19"] }),
});
expect(fetchImpl.mock.calls[7]?.[1]?.method).toBe("PUT");
expect(JSON.parse(String(fetchImpl.mock.calls[7]?.[1]?.body))).toEqual({
add_on: expect.objectContaining({ code: "customer_portal_domain_setup", tax_codes: ["de-vat-19"] }),
});
});
it.each([
["different name", "HiveGrid Production", testLagoOrganizationId],
["different id fingerprint", "HiveGrid Staging", "different-organization-id"],
])("rejects a Lago organization with a %s before catalog reads or mutations", async (_label, name, id) => {
const fetchImpl = vi.fn<typeof fetch>().mockResolvedValue(lagoOrganizationResponse(name, id));
const client = new LagoCatalogClient({ apiUrl: "https://lago.example.test", apiKey: "secret-key", fetchImpl }, testLagoIdentity);
await expect(client.readCatalog()).rejects.toThrow("Lago organization does not match the canonical staging identity");
expect(fetchImpl).toHaveBeenCalledTimes(1);
});
});
@@ -0,0 +1,716 @@
import { createHash } from "node:crypto";
import { normalizeLagoApiUrl } from "../../packages/billing/src/lago";
import type { DbClient } from "@hivegrid/db/client.server";
import {
customerPortalCommercialProducts,
customerPortalProductCodes,
entitlementLimitTypes,
featureKeys,
getFeatureGate,
hiveGridVat,
standardEntitlementPlans,
type EntitlementPlanId,
} from "@hivegrid/entitlements";
import { z } from "zod";
import { CustomerPortalUatError, normalizeCustomerPortalStagingLagoApiUrl } from "./contracts";
const DEFAULT_TIMEOUT_MS = 10_000;
const BASE_PLAN_CODES = ["starter", "pro", "business"] as const;
const COMMERCIAL_PRODUCT_CODES = Object.values(customerPortalProductCodes);
const STAGING_LAGO_ORGANIZATION_NAME = "HiveGrid Staging";
const STAGING_LAGO_ORGANIZATION_ID_SHA256 = "3b1134a731c67b704bb0b3298ce031213079966b348aa762800f9c92556085a8";
const desiredLagoPlan = Object.freeze({
code: customerPortalCommercialProducts.monthlyAddOn.code,
name: customerPortalCommercialProducts.monthlyAddOn.title,
description: customerPortalCommercialProducts.monthlyAddOn.description,
interval: "monthly" as const,
amountCents: customerPortalCommercialProducts.monthlyAddOn.amountCents!,
amountCurrency: customerPortalCommercialProducts.monthlyAddOn.currency!,
payInAdvance: true,
taxCodes: Object.freeze([hiveGridVat.code]),
});
const desiredLagoAddOn = Object.freeze({
code: customerPortalCommercialProducts.customDomainSetup.code,
name: customerPortalCommercialProducts.customDomainSetup.title,
description: customerPortalCommercialProducts.customDomainSetup.description,
amountCents: customerPortalCommercialProducts.customDomainSetup.amountCents!,
amountCurrency: customerPortalCommercialProducts.customDomainSetup.currency!,
taxCodes: Object.freeze([hiveGridVat.code]),
});
const lagoAppliedTaxSchema = z.object({ code: z.string() });
const lagoPlanSchema = z.object({
code: z.string(),
name: z.string(),
description: z.string().nullable().optional(),
interval: z.string(),
amount_cents: z.number().int(),
amount_currency: z.string(),
pay_in_advance: z.boolean(),
taxes: z.array(lagoAppliedTaxSchema).default([]),
});
const lagoAddOnSchema = z.object({
code: z.string(),
name: z.string(),
description: z.string().nullable().optional(),
amount_cents: z.number().int(),
amount_currency: z.string(),
taxes: z.array(lagoAppliedTaxSchema).default([]),
});
const lagoPlanResponseSchema = z.object({ plan: lagoPlanSchema });
const lagoAddOnResponseSchema = z.object({ add_on: lagoAddOnSchema });
const lagoOrganizationResponseSchema = z.object({
organization: z.object({ lago_id: z.string().min(1), name: z.string() }),
});
export type LagoPlanSnapshot = z.infer<typeof lagoPlanSchema>;
export type LagoAddOnSnapshot = z.infer<typeof lagoAddOnSchema>;
export type ProviderCatalogSnapshot = {
readonly plan: LagoPlanSnapshot | null;
readonly addOn: LagoAddOnSnapshot | null;
};
export type ProviderCatalogAction = {
readonly resource: "plan" | "add_on";
readonly code: string;
readonly action: "create" | "update" | "noop" | "drift";
readonly driftFields: readonly string[];
};
export type DatabasePriceSnapshot = {
readonly billingProviderId: string;
readonly lagoFeeCode: string | null;
readonly molliePriceReference: string | null;
readonly type: number;
readonly billingPeriod: number;
readonly price: string;
readonly currency: string;
readonly trialDays: number;
readonly active: boolean;
};
export type DatabaseProductSnapshot = {
readonly billingProviderId: string;
readonly code: string | null;
readonly title: string;
readonly description: string | null;
readonly kind: string;
readonly order: number;
readonly model: number;
readonly active: boolean;
readonly public: boolean;
readonly groupTitle: string | null;
readonly groupDescription: string | null;
readonly badge: string | null;
readonly billingAddressCollection: string;
readonly hasQuantity: boolean;
readonly canBuyAgain: boolean;
readonly lagoPlanCode: string | null;
readonly features: readonly DatabaseFeatureSnapshot[];
readonly prices: readonly DatabasePriceSnapshot[];
};
export type DatabaseFeatureSnapshot = {
readonly order: number;
readonly title: string;
readonly name: string;
readonly code: string | null;
readonly type: number;
readonly value: number;
readonly quotaValue: unknown;
readonly href: string | null;
readonly badge: string | null;
readonly accumulate: boolean;
};
export type DatabaseBasePlanSnapshot = {
readonly id: string;
readonly code: string | null;
readonly kind: string;
readonly portalFeatures: readonly DatabaseFeatureSnapshot[];
};
export type DatabaseCatalogSnapshot = {
readonly commercialProducts: readonly DatabaseProductSnapshot[];
readonly basePlans: readonly DatabaseBasePlanSnapshot[];
};
export type DatabaseCatalogAssessment = {
readonly reconcileIssues: readonly string[];
readonly blockingIssues: readonly string[];
};
export type CustomerPortalCatalogPlan = {
readonly provider: readonly ProviderCatalogAction[];
readonly database: {
readonly action: "noop" | "reconcile" | "blocked";
readonly reconcileIssues: readonly string[];
readonly blockingIssues: readonly string[];
};
};
function differentFields<T extends Record<string, unknown>>(actual: T, desired: T, fields: readonly (keyof T)[]): string[] {
return fields.filter((field) => actual[field] !== desired[field]).map(String);
}
export function planProviderCatalog(snapshot: ProviderCatalogSnapshot): ProviderCatalogAction[] {
const planDrift = snapshot.plan
? differentFields(
{
code: snapshot.plan.code,
name: snapshot.plan.name,
description: snapshot.plan.description ?? "",
interval: snapshot.plan.interval,
amountCents: snapshot.plan.amount_cents,
amountCurrency: snapshot.plan.amount_currency.toUpperCase(),
payInAdvance: snapshot.plan.pay_in_advance,
taxCodes: snapshot.plan.taxes
.map((tax) => tax.code)
.sort()
.join(","),
},
{ ...desiredLagoPlan, taxCodes: [...desiredLagoPlan.taxCodes].sort().join(",") },
["code", "name", "description", "interval", "amountCents", "amountCurrency", "payInAdvance", "taxCodes"]
)
: [];
const addOnDrift = snapshot.addOn
? differentFields(
{
code: snapshot.addOn.code,
name: snapshot.addOn.name,
description: snapshot.addOn.description ?? "",
amountCents: snapshot.addOn.amount_cents,
amountCurrency: snapshot.addOn.amount_currency.toUpperCase(),
taxCodes: snapshot.addOn.taxes
.map((tax) => tax.code)
.sort()
.join(","),
},
{ ...desiredLagoAddOn, taxCodes: [...desiredLagoAddOn.taxCodes].sort().join(",") },
["code", "name", "description", "amountCents", "amountCurrency", "taxCodes"]
)
: [];
return [
{
resource: "plan",
code: desiredLagoPlan.code,
action: snapshot.plan ? (planDrift.length === 0 ? "noop" : planDrift.every((field) => field === "taxCodes") ? "update" : "drift") : "create",
driftFields: planDrift,
},
{
resource: "add_on",
code: desiredLagoAddOn.code,
action: snapshot.addOn ? (addOnDrift.length === 0 ? "noop" : addOnDrift.every((field) => field === "taxCodes") ? "update" : "drift") : "create",
driftFields: addOnDrift,
},
];
}
type BasePlanPortalFeatureAction = {
readonly planCode: EntitlementPlanId;
readonly productId: string | null;
readonly action: "create" | "noop" | "blocked";
readonly issue: string | null;
};
function getBasePlanPortalFeatureDefinition(planCode: EntitlementPlanId): DatabaseFeatureSnapshot {
const plan = standardEntitlementPlans.find((candidate) => candidate.id === planCode);
const feature = plan?.features.find((candidate) => candidate.featureKey === featureKeys.customerPortal);
const registryItem = getFeatureGate(featureKeys.customerPortal);
if (!feature || !registryItem) {
throw new CustomerPortalUatError(`customer-portal UAT: canonical ${planCode} portal feature definition is unavailable`);
}
return {
// SubscriptionFeature.order is an Int. The entitlement registry deliberately
// uses fractional values to place adjacent features, while Prisma/Postgres
// persists those values as the nearest integer.
order: Math.round(feature.order),
title: feature.label,
name: feature.featureKey,
code: null,
type: feature.limitType,
value: feature.limit ?? feature.limitType,
quotaValue: null,
href: null,
badge: registryItem.title,
accumulate: feature.limitType === entitlementLimitTypes.monthly,
};
}
function databaseFeatureMatches(actual: DatabaseFeatureSnapshot, expected: DatabaseFeatureSnapshot): boolean {
return (
actual.order === expected.order &&
actual.title === expected.title &&
actual.name === expected.name &&
actual.code === expected.code &&
actual.type === expected.type &&
actual.value === expected.value &&
actual.quotaValue === expected.quotaValue &&
actual.href === expected.href &&
actual.badge === expected.badge &&
actual.accumulate === expected.accumulate
);
}
function commercialFeaturesMatch(
product: DatabaseProductSnapshot,
definition: (typeof customerPortalCommercialProducts)[keyof typeof customerPortalCommercialProducts]
): boolean {
if (product.features.length !== definition.featureKeys.length) return false;
return definition.featureKeys.every((featureKey, index) => {
const matches = product.features.filter((feature) => feature.name === featureKey);
const registryItem = getFeatureGate(featureKey);
if (matches.length !== 1 || !registryItem) return false;
return databaseFeatureMatches(matches[0]!, {
order: index + 1,
title: registryItem.title,
name: featureKey,
code: null,
type: entitlementLimitTypes.included,
value: definition.includedQuantity ?? entitlementLimitTypes.included,
quotaValue: null,
href: null,
badge: registryItem.title,
accumulate: false,
});
});
}
export function planBasePlanPortalFeatureReconciliation(snapshot: DatabaseCatalogSnapshot): readonly BasePlanPortalFeatureAction[] {
return BASE_PLAN_CODES.map((planCode) => {
const matches = snapshot.basePlans.filter((plan) => plan.code === planCode);
if (matches.length !== 1) {
return {
planCode,
productId: null,
action: "blocked",
issue: `${planCode}: expected exactly one canonical base-plan product`,
};
}
const plan = matches[0]!;
if (plan.kind !== "base_plan") {
return {
planCode,
productId: plan.id,
action: "blocked",
issue: `${planCode}: canonical product is not a base plan`,
};
}
if (plan.portalFeatures.length > 1) {
return {
planCode,
productId: plan.id,
action: "blocked",
issue: `${planCode}: duplicate customer_portal feature rows`,
};
}
const feature = plan.portalFeatures[0];
if (!feature) {
return {
planCode,
productId: plan.id,
action: "create",
issue: `${planCode}: canonical customer_portal feature missing`,
};
}
if (!databaseFeatureMatches(feature, getBasePlanPortalFeatureDefinition(planCode))) {
return {
planCode,
productId: plan.id,
action: "blocked",
issue: `${planCode}: existing customer_portal feature differs from the canonical contract`,
};
}
return { planCode, productId: plan.id, action: "noop", issue: null };
});
}
export function assessDatabaseCatalog(snapshot: DatabaseCatalogSnapshot): DatabaseCatalogAssessment {
const reconcileIssues: string[] = [];
const blockingIssues: string[] = [];
for (const definition of Object.values(customerPortalCommercialProducts)) {
const expectedBillingProviderId = `hivegrid_commercial_product_${definition.code}`;
const seedCollisions = snapshot.commercialProducts.filter(
(product) => product.code !== definition.code && (product.title === definition.title || product.billingProviderId === expectedBillingProviderId)
);
if (seedCollisions.length > 0) {
blockingIssues.push(`${definition.code}: existing seed-key collision would mutate another product`);
continue;
}
const matches = snapshot.commercialProducts.filter((product) => product.code === definition.code);
if (matches.length > 1) {
blockingIssues.push(`${definition.code}: duplicate database products`);
continue;
}
const product = matches[0];
if (!product) {
reconcileIssues.push(`${definition.code}: product missing`);
continue;
}
if (product.title !== definition.title && product.billingProviderId !== expectedBillingProviderId) {
blockingIssues.push(`${definition.code}: canonical code is not reachable through the existing seed keys`);
continue;
}
const expectedLagoPlanCode = definition.source === "recurring_add_on" ? definition.code : null;
if (
product.billingProviderId !== expectedBillingProviderId ||
product.title !== definition.title ||
product.description !== definition.description ||
product.kind !== definition.source ||
product.order !== definition.catalogOrder ||
product.model !== 0 ||
product.active !== true ||
product.public !== definition.public ||
product.groupTitle !== "Customer Portal" ||
product.groupDescription !== null ||
product.badge !== null ||
product.billingAddressCollection !== "auto" ||
product.hasQuantity !== false ||
product.canBuyAgain !== (definition.source === "one_time_setup") ||
product.lagoPlanCode !== expectedLagoPlanCode
) {
reconcileIssues.push(`${definition.code}: product metadata differs`);
}
if (!commercialFeaturesMatch(product, definition)) {
reconcileIssues.push(`${definition.code}: feature contract differs`);
}
const activePrices = product.prices.filter((price) => price.active);
if (definition.amountCents === null || definition.currency === null) {
if (activePrices.length > 0) blockingIssues.push(`${definition.code}: unexpected active price cannot be removed by reconciliation`);
continue;
}
const expectedPeriod = definition.source === "recurring_add_on" ? 3 : 0;
const expectedPrice = (definition.amountCents / 100).toFixed(2);
const expectedCurrency = definition.currency.toLowerCase();
const seedPriceCandidates = product.prices.filter((price) => price.billingPeriod === expectedPeriod && price.currency.toLowerCase() === expectedCurrency);
if (seedPriceCandidates.length > 1) {
blockingIssues.push(`${definition.code}: duplicate seed-key prices`);
continue;
}
const price = seedPriceCandidates[0];
if (!price) {
reconcileIssues.push(`${definition.code}: canonical active price missing`);
} else {
const expectedPriceProviderId = `hivegrid_commercial_price_${definition.code}`;
const expectedType = definition.source === "recurring_add_on" ? 1 : 0;
if (
price.billingProviderId !== expectedPriceProviderId ||
price.lagoFeeCode !== definition.code ||
price.molliePriceReference !== expectedPriceProviderId ||
price.type !== expectedType ||
price.price !== expectedPrice ||
price.currency !== expectedCurrency ||
price.trialDays !== 0 ||
!price.active
) {
reconcileIssues.push(`${definition.code}: canonical price contract differs`);
}
}
const unexpectedActivePrices = activePrices.filter((candidate) => candidate !== price);
if (unexpectedActivePrices.length > 0) {
blockingIssues.push(`${definition.code}: unexpected active price cannot be removed by reconciliation`);
}
}
for (const action of planBasePlanPortalFeatureReconciliation(snapshot)) {
if (action.action === "create") reconcileIssues.push(action.issue!);
if (action.action === "blocked") blockingIssues.push(action.issue!);
}
return { reconcileIssues, blockingIssues };
}
export function buildCustomerPortalCatalogPlan(provider: ProviderCatalogSnapshot, database: DatabaseCatalogSnapshot): CustomerPortalCatalogPlan {
const providerPlan = planProviderCatalog(provider);
const databaseAssessment = assessDatabaseCatalog(database);
return {
provider: providerPlan,
database: {
action: databaseAssessment.blockingIssues.length > 0 ? "blocked" : databaseAssessment.reconcileIssues.length > 0 ? "reconcile" : "noop",
...databaseAssessment,
},
};
}
export function customerPortalCatalogPlanIsComplete(plan: CustomerPortalCatalogPlan): boolean {
return plan.provider.every((action) => action.action === "noop") && plan.database.action === "noop";
}
export function customerPortalCatalogPlanIsBlocked(plan: CustomerPortalCatalogPlan): boolean {
return plan.provider.some((action) => action.action === "drift") || plan.database.action === "blocked";
}
export async function readDatabaseCatalog(db: DbClient): Promise<DatabaseCatalogSnapshot> {
const commercialTitles = Object.values(customerPortalCommercialProducts).map((product) => product.title);
const commercialBillingProviderIds = Object.values(customerPortalCommercialProducts).map((product) => `hivegrid_commercial_product_${product.code}`);
const products = await db.subscriptionProduct.findMany({
where: {
OR: [
{ code: { in: [...COMMERCIAL_PRODUCT_CODES, ...BASE_PLAN_CODES] } },
{ title: { in: commercialTitles } },
{ billingProviderId: { in: commercialBillingProviderIds } },
],
},
select: {
id: true,
billingProviderId: true,
code: true,
title: true,
description: true,
kind: true,
order: true,
model: true,
active: true,
public: true,
groupTitle: true,
groupDescription: true,
badge: true,
billingAddressCollection: true,
hasQuantity: true,
canBuyAgain: true,
lagoPlanCode: true,
features: {
select: {
order: true,
title: true,
name: true,
code: true,
type: true,
value: true,
quotaValue: true,
href: true,
badge: true,
accumulate: true,
},
},
prices: {
select: {
billingProviderId: true,
lagoFeeCode: true,
molliePriceReference: true,
type: true,
billingPeriod: true,
price: true,
currency: true,
trialDays: true,
active: true,
},
},
},
});
const snapshots: DatabaseProductSnapshot[] = products.map((product) => ({
...product,
kind: String(product.kind),
features: product.features,
prices: product.prices.map((price) => ({ ...price, price: price.price.toFixed(2) })),
}));
return {
commercialProducts: snapshots.filter(
(product) =>
(product.code !== null && COMMERCIAL_PRODUCT_CODES.includes(product.code as never)) ||
commercialTitles.includes(product.title) ||
commercialBillingProviderIds.includes(product.billingProviderId)
),
basePlans: products
.filter((product) => product.code !== null && BASE_PLAN_CODES.includes(product.code as never))
.map((product) => ({
id: product.id,
code: product.code,
kind: String(product.kind),
portalFeatures: product.features.filter((feature) => feature.name === featureKeys.customerPortal),
})),
};
}
export async function reconcileBasePlanPortalFeatures(db: DbClient): Promise<readonly EntitlementPlanId[]> {
const actions = planBasePlanPortalFeatureReconciliation(await readDatabaseCatalog(db));
const blocked = actions.find((action) => action.action === "blocked");
if (blocked) {
throw new CustomerPortalUatError(`customer-portal UAT: ${blocked.issue}`);
}
const created: EntitlementPlanId[] = [];
for (const action of actions) {
if (action.action !== "create" || !action.productId) continue;
const feature = getBasePlanPortalFeatureDefinition(action.planCode);
await db.subscriptionFeature.create({
data: {
subscriptionProductId: action.productId,
order: feature.order,
title: feature.title,
name: feature.name,
code: feature.code,
type: feature.type,
value: feature.value,
href: feature.href,
badge: feature.badge,
accumulate: feature.accumulate,
},
});
created.push(action.planCode);
}
return created;
}
export class LagoCatalogClient {
private readonly apiUrl: string;
private readonly apiKey: string;
private readonly fetchImpl: typeof fetch;
private readonly timeoutMs: number;
private readonly expectedOrganizationIdSha256: string;
constructor(
input: { apiUrl: string; apiKey: string; fetchImpl?: typeof fetch; timeoutMs?: number },
testOverrides?: { expectedOrganizationIdSha256: string }
) {
if (testOverrides && !input.fetchImpl) {
throw new CustomerPortalUatError("customer-portal UAT: Lago identity test override requires an injected transport");
}
try {
this.apiUrl = testOverrides ? normalizeLagoApiUrl(input.apiUrl) : normalizeCustomerPortalStagingLagoApiUrl(input.apiUrl);
} catch {
throw new CustomerPortalUatError("customer-portal UAT: LAGO_API_URL is invalid");
}
this.apiKey = input.apiKey.trim();
if (!this.apiKey) throw new CustomerPortalUatError("customer-portal UAT: LAGO_API_KEY is required");
this.fetchImpl = input.fetchImpl ?? fetch;
this.timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
this.expectedOrganizationIdSha256 = testOverrides?.expectedOrganizationIdSha256 ?? STAGING_LAGO_ORGANIZATION_ID_SHA256;
}
async readCatalog(): Promise<ProviderCatalogSnapshot> {
await this.assertStagingOrganization();
const [plan, addOn] = await Promise.all([
this.request(`/plans/${encodeURIComponent(desiredLagoPlan.code)}`, "GET", undefined, lagoPlanResponseSchema, true),
this.request(`/add_ons/${encodeURIComponent(desiredLagoAddOn.code)}`, "GET", undefined, lagoAddOnResponseSchema, true),
]);
return { plan: plan?.plan ?? null, addOn: addOn?.add_on ?? null };
}
async createPlan(): Promise<void> {
await this.assertStagingOrganization();
await this.request(
"/plans",
"POST",
{
plan: {
name: desiredLagoPlan.name,
code: desiredLagoPlan.code,
description: desiredLagoPlan.description,
interval: desiredLagoPlan.interval,
amount_cents: desiredLagoPlan.amountCents,
amount_currency: desiredLagoPlan.amountCurrency,
pay_in_advance: desiredLagoPlan.payInAdvance,
tax_codes: desiredLagoPlan.taxCodes,
},
},
lagoPlanResponseSchema
);
}
async updatePlan(): Promise<void> {
await this.assertStagingOrganization();
await this.request(
`/plans/${encodeURIComponent(desiredLagoPlan.code)}`,
"PUT",
{
plan: {
name: desiredLagoPlan.name,
code: desiredLagoPlan.code,
description: desiredLagoPlan.description,
interval: desiredLagoPlan.interval,
amount_cents: desiredLagoPlan.amountCents,
amount_currency: desiredLagoPlan.amountCurrency,
pay_in_advance: desiredLagoPlan.payInAdvance,
tax_codes: desiredLagoPlan.taxCodes,
},
},
lagoPlanResponseSchema
);
}
async createAddOn(): Promise<void> {
await this.assertStagingOrganization();
await this.request(
"/add_ons",
"POST",
{
add_on: {
name: desiredLagoAddOn.name,
code: desiredLagoAddOn.code,
description: desiredLagoAddOn.description,
amount_cents: desiredLagoAddOn.amountCents,
amount_currency: desiredLagoAddOn.amountCurrency,
tax_codes: desiredLagoAddOn.taxCodes,
},
},
lagoAddOnResponseSchema
);
}
async updateAddOn(): Promise<void> {
await this.assertStagingOrganization();
await this.request(
`/add_ons/${encodeURIComponent(desiredLagoAddOn.code)}`,
"PUT",
{
add_on: {
name: desiredLagoAddOn.name,
code: desiredLagoAddOn.code,
description: desiredLagoAddOn.description,
amount_cents: desiredLagoAddOn.amountCents,
amount_currency: desiredLagoAddOn.amountCurrency,
tax_codes: desiredLagoAddOn.taxCodes,
},
},
lagoAddOnResponseSchema
);
}
private async assertStagingOrganization(): Promise<void> {
const response = await this.request("/organizations", "GET", undefined, lagoOrganizationResponseSchema);
const organization = response?.organization;
const idSha256 = organization ? createHash("sha256").update(organization.lago_id).digest("hex") : "";
if (organization?.name !== STAGING_LAGO_ORGANIZATION_NAME || idSha256 !== this.expectedOrganizationIdSha256) {
throw new CustomerPortalUatError("customer-portal UAT: Lago organization does not match the canonical staging identity");
}
}
private async request<T>(path: string, method: "GET" | "POST" | "PUT", body: unknown, schema: z.ZodType<T>, allowNotFound = false): Promise<T | null> {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
try {
const response = await this.fetchImpl(`${this.apiUrl}/api/v1${path}`, {
method,
headers: {
authorization: `Bearer ${this.apiKey}`,
accept: "application/json",
...(body === undefined ? {} : { "content-type": "application/json" }),
},
body: body === undefined ? undefined : JSON.stringify(body),
redirect: "error",
signal: controller.signal,
});
if (allowNotFound && response.status === 404) return null;
if (!response.ok) throw new CustomerPortalUatError(`customer-portal UAT: Lago catalog request failed with status ${response.status}`);
const parsed = schema.safeParse(await response.json());
if (!parsed.success) throw new CustomerPortalUatError("customer-portal UAT: Lago catalog response shape is invalid");
return parsed.data;
} catch (error) {
if (error instanceof CustomerPortalUatError) throw error;
throw new CustomerPortalUatError("customer-portal UAT: Lago catalog request failed");
} finally {
clearTimeout(timeout);
}
}
}
@@ -0,0 +1,112 @@
// @vitest-environment node
import { describe, expect, it } from "vitest";
import {
CUSTOMER_PORTAL_UAT_COMMERCIAL_CONFIRMATION,
CUSTOMER_PORTAL_UAT_TENANT_SLUG,
parseCustomerPortalUatCommand,
safeCustomerPortalUatError,
} from "./contracts";
const baseEnvironment = {
NODE_ENV: "production",
SENTRY_ENVIRONMENT: "staging",
RLS_RUNTIME_MODE: "required",
DATABASE_RUNTIME_ROLE: "hivegrid_app",
DATABASE_URL: "postgresql://hivegrid_app:runtime-secret@db.staging.internal:6432/hivegrid_staging",
CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE_HOST: "db.staging.internal",
CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE_PORT: "6432",
CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE: "hivegrid_staging",
CUSTOMER_PORTAL_UAT_OPERATOR_USER_ID: "operator-user-id",
CUSTOMER_PORTAL_UAT_EXPECTED_TENANT_ID: "tenant-demo-pro",
CUSTOMER_PORTAL_UAT_EXPECTED_STARTER_TENANT_ID: "tenant-demo-starter",
CUSTOMER_PORTAL_UAT_EXPECTED_PRO_TENANT_ID: "tenant-demo-pro",
CUSTOMER_PORTAL_UAT_EXPECTED_ENTERPRISE_TENANT_ID: "tenant-demo-enterprise",
CUSTOMER_PORTAL_UAT_PASSWORD: "Q7!portal-UAT-strong-random-2026",
LAGO_API_URL: "http://127.0.0.1:3108",
LAGO_API_KEY: "lago-staging-key",
AUDIT_CHAIN_SECRET: "staging-audit-chain-secret-at-least-32-bytes",
} as const;
describe("customer-portal UAT command contract", () => {
it("defaults to a read-only plan and keeps catalog and fixture inputs separate", () => {
const catalog = parseCustomerPortalUatCommand("catalog", [], baseEnvironment);
const fixture = parseCustomerPortalUatCommand("fixture", ["--verify"], baseEnvironment);
expect(catalog).toMatchObject({ target: "catalog", mode: "plan", lagoApiUrl: "http://127.0.0.1:3108" });
expect(fixture).toMatchObject({ target: "fixture", mode: "verify", expectedTenantId: "tenant-demo-pro" });
expect("password" in catalog).toBe(false);
expect("lagoApiKey" in fixture).toBe(false);
});
it("binds the commercial fixture to three distinct explicit tenant ids", () => {
const fixture = parseCustomerPortalUatCommand("commercial-fixture", ["--verify"], baseEnvironment);
expect(fixture).toMatchObject({
target: "commercial-fixture",
mode: "verify",
expectedStarterTenantId: "tenant-demo-starter",
expectedProTenantId: "tenant-demo-pro",
expectedEnterpriseTenantId: "tenant-demo-enterprise",
});
expect(() =>
parseCustomerPortalUatCommand("commercial-fixture", [], {
...baseEnvironment,
CUSTOMER_PORTAL_UAT_EXPECTED_STARTER_TENANT_ID: "same-tenant",
CUSTOMER_PORTAL_UAT_EXPECTED_PRO_TENANT_ID: "same-tenant",
CUSTOMER_PORTAL_UAT_EXPECTED_ENTERPRISE_TENANT_ID: "tenant-demo-enterprise",
})
).toThrow("must be distinct");
});
it("requires an exact tenant confirmation for every mutation", () => {
expect(() => parseCustomerPortalUatCommand("catalog", ["--apply"], baseEnvironment)).toThrow(`--confirm=${CUSTOMER_PORTAL_UAT_TENANT_SLUG}`);
expect(() => parseCustomerPortalUatCommand("catalog", ["--apply", `--confirm=${CUSTOMER_PORTAL_UAT_TENANT_SLUG}`], baseEnvironment)).not.toThrow();
expect(() => parseCustomerPortalUatCommand("fixture", ["--plan", `--confirm=${CUSTOMER_PORTAL_UAT_TENANT_SLUG}`], baseEnvironment)).toThrow(
"only with --apply"
);
expect(() => parseCustomerPortalUatCommand("commercial-fixture", ["--apply", `--confirm=${CUSTOMER_PORTAL_UAT_TENANT_SLUG}`], baseEnvironment)).toThrow(
`--confirm=${CUSTOMER_PORTAL_UAT_COMMERCIAL_CONFIRMATION}`
);
expect(() =>
parseCustomerPortalUatCommand("commercial-fixture", ["--apply", `--confirm=${CUSTOMER_PORTAL_UAT_COMMERCIAL_CONFIRMATION}`], baseEnvironment)
).not.toThrow();
});
it.each([
["non-production Node runtime", { NODE_ENV: "development" }],
["production environment", { SENTRY_ENVIRONMENT: "production" }],
["RLS disabled", { RLS_RUNTIME_MODE: "off" }],
["wrong runtime role", { DATABASE_RUNTIME_ROLE: "postgres" }],
["wrong URL role", { DATABASE_URL: "postgresql://postgres:secret@db.staging.internal:6432/hivegrid_staging" }],
["URL host override", { DATABASE_URL: "postgresql://hivegrid_app:secret@db.staging.internal:6432/hivegrid_staging?host=production-db" }],
["URL user override", { DATABASE_URL: "postgresql://hivegrid_app:secret@db.staging.internal:6432/hivegrid_staging?user=postgres" }],
[
"URL options override",
{ DATABASE_URL: "postgresql://hivegrid_app:secret@db.staging.internal:6432/hivegrid_staging?options=-c%20hivegrid.environment%3Dstaging" },
],
["URL service override", { DATABASE_URL: "postgresql://hivegrid_app:secret@db.staging.internal:6432/hivegrid_staging?service=production" }],
["libpq PGOPTIONS override", { PGOPTIONS: "-c hivegrid.environment=staging" }],
["libpq PGHOST override", { PGHOST: "production-db" }],
["libpq PGSERVICE override", { PGSERVICE: "production" }],
["wrong database binding", { CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE: "other" }],
["migration credential present", { DIRECT_URL: "postgresql://migrator:secret@db/hivegrid" }],
["migrator credential present", { MIGRATOR_PASSWORD: "do-not-use" }],
["runtime seed flag present", { SEED_ON_BOOT: "true" }],
["non-staging Lago endpoint", { LAGO_API_URL: "https://billing.example.test" }],
["credential-bearing Lago URL", { LAGO_API_URL: "http://user:pass@127.0.0.1:3108" }],
["missing audit secret", { AUDIT_CHAIN_SECRET: "" }],
["short audit secret", { AUDIT_CHAIN_SECRET: "too-short" }],
])("fails closed for %s", (_label, override) => {
expect(() => parseCustomerPortalUatCommand("catalog", [], { ...baseEnvironment, ...override })).toThrow();
});
it("rejects weak fixture passwords without disclosing the supplied value", () => {
expect(() => parseCustomerPortalUatCommand("fixture", [], { ...baseEnvironment, CUSTOMER_PORTAL_UAT_PASSWORD: "password" })).toThrow(
"strong random secret"
);
});
it("does not expose unexpected error details", () => {
expect(safeCustomerPortalUatError(new Error("postgresql://user:secret@host/database"))).not.toContain("secret");
});
});
@@ -0,0 +1,250 @@
export const CUSTOMER_PORTAL_UAT_TENANT_SLUG = "demo-pro-crm" as const;
export const CUSTOMER_PORTAL_UAT_STARTER_TENANT_SLUG = "demo-starter-crm" as const;
export const CUSTOMER_PORTAL_UAT_ENTERPRISE_TENANT_SLUG = "demo-enterprise-crm" as const;
export const CUSTOMER_PORTAL_UAT_COMMERCIAL_CONFIRMATION = "demo-starter-crm+demo-pro-crm+demo-enterprise-crm" as const;
export const CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN = "https://staging-portal.hivegrid.de" as const;
export const CUSTOMER_PORTAL_UAT_ADMIN_EMAIL = "customer-portal-admin-uat@saas-ctrl.com" as const;
export const CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL = "customer-portal-uat@saas-ctrl.com" as const;
export const CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL = "customer-portal-subcontractor-uat@saas-ctrl.com" as const;
export const CUSTOMER_PORTAL_UAT_PROJECT_ID = "rheinmain-shk-v1-project-0001" as const;
export const CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID = "rheinmain-shk-v1-project-0002" as const;
export type CustomerPortalUatMode = "plan" | "verify" | "apply";
export type CustomerPortalUatTarget = "catalog" | "fixture" | "commercial-fixture";
export type CustomerPortalUatEnvironment = Readonly<Record<string, string | undefined>>;
export type CustomerPortalUatDatabaseBinding = {
readonly databaseUrl: string;
readonly expectedDatabaseHost: string;
readonly expectedDatabasePort: string;
readonly expectedDatabaseName: string;
readonly operatorUserId: string;
readonly auditChainSecret: string;
};
export type CustomerPortalCatalogCommand = CustomerPortalUatDatabaseBinding & {
readonly target: "catalog";
readonly mode: CustomerPortalUatMode;
readonly lagoApiUrl: string;
readonly lagoApiKey: string;
};
export type CustomerPortalFixtureCommand = CustomerPortalUatDatabaseBinding & {
readonly target: "fixture";
readonly mode: CustomerPortalUatMode;
readonly expectedTenantId: string;
readonly password: string;
};
export type CustomerPortalCommercialFixtureCommand = CustomerPortalUatDatabaseBinding & {
readonly target: "commercial-fixture";
readonly mode: CustomerPortalUatMode;
readonly expectedStarterTenantId: string;
readonly expectedProTenantId: string;
readonly expectedEnterpriseTenantId: string;
readonly password: string;
};
export type CustomerPortalUatCommand = CustomerPortalCatalogCommand | CustomerPortalFixtureCommand | CustomerPortalCommercialFixtureCommand;
const modeArguments = new Map<string, CustomerPortalUatMode>([
["--plan", "plan"],
["--verify", "verify"],
["--apply", "apply"],
]);
const forbiddenEnvironmentKeys = new Set(["DIRECT_URL", "MIGRATE_ON_BOOT", "SEED_ON_BOOT"]);
const allowedStagingLagoApiUrls = new Set(["http://127.0.0.1:3108", "http://10.42.0.4:3108"]);
export class CustomerPortalUatError extends Error {
constructor(message: string) {
super(message);
this.name = "CustomerPortalUatError";
}
}
function requiredEnvironmentValue(env: CustomerPortalUatEnvironment, name: string): string {
const value = env[name]?.trim();
if (!value) throw new CustomerPortalUatError(`customer-portal UAT: ${name} is required`);
return value;
}
function parseSingleValueArgument(argv: readonly string[], name: string): string | undefined {
const prefix = `${name}=`;
const values = argv.filter((argument) => argument.startsWith(prefix)).map((argument) => argument.slice(prefix.length));
if (values.length > 1) throw new CustomerPortalUatError(`customer-portal UAT: ${name} may only be provided once`);
return values[0];
}
function parseMode(argv: readonly string[]): CustomerPortalUatMode {
const modes = argv.flatMap((argument) => {
const mode = modeArguments.get(argument);
return mode ? [mode] : [];
});
if (modes.length > 1) throw new CustomerPortalUatError("customer-portal UAT: provide exactly one mode");
return modes[0] ?? "plan";
}
function assertKnownArguments(argv: readonly string[]): void {
for (const argument of argv) {
if (modeArguments.has(argument) || argument.startsWith("--confirm=")) continue;
throw new CustomerPortalUatError("customer-portal UAT: unknown argument");
}
}
function assertOperatorEnvironment(env: CustomerPortalUatEnvironment): void {
if (env.NODE_ENV?.trim() !== "production") {
throw new CustomerPortalUatError("customer-portal UAT: NODE_ENV must be production so production audit guarantees stay active");
}
if (env.SENTRY_ENVIRONMENT?.trim() !== "staging") {
throw new CustomerPortalUatError("customer-portal UAT: SENTRY_ENVIRONMENT must be staging");
}
if (env.RLS_RUNTIME_MODE?.trim() !== "required") {
throw new CustomerPortalUatError("customer-portal UAT: RLS_RUNTIME_MODE must be required");
}
if (env.DATABASE_RUNTIME_ROLE?.trim() !== "hivegrid_app") {
throw new CustomerPortalUatError("customer-portal UAT: DATABASE_RUNTIME_ROLE must be hivegrid_app");
}
const auditChainSecret = env.AUDIT_CHAIN_SECRET;
if (!auditChainSecret || Buffer.byteLength(auditChainSecret, "utf8") < 32) {
throw new CustomerPortalUatError("customer-portal UAT: AUDIT_CHAIN_SECRET must contain the canonical staging audit secret");
}
for (const [name, value] of Object.entries(env)) {
if (!value) continue;
if (forbiddenEnvironmentKeys.has(name) || name.startsWith("SEED_") || name.startsWith("MIGRATOR_") || name.toUpperCase().startsWith("PG")) {
throw new CustomerPortalUatError(`customer-portal UAT: forbidden operator environment key ${name}`);
}
}
}
export function normalizeCustomerPortalStagingLagoApiUrl(value: string): string {
let parsed: URL;
try {
parsed = new URL(value);
} catch {
throw new CustomerPortalUatError("customer-portal UAT: LAGO_API_URL must be the canonical staging endpoint");
}
if (parsed.username || parsed.password || parsed.search || parsed.hash || (parsed.pathname !== "" && parsed.pathname !== "/")) {
throw new CustomerPortalUatError("customer-portal UAT: LAGO_API_URL must be the canonical staging endpoint");
}
const normalized = parsed.origin;
if (!allowedStagingLagoApiUrls.has(normalized)) {
throw new CustomerPortalUatError("customer-portal UAT: LAGO_API_URL must be the canonical staging endpoint");
}
return normalized;
}
function requireStagingLagoApiUrl(env: CustomerPortalUatEnvironment): string {
return normalizeCustomerPortalStagingLagoApiUrl(requiredEnvironmentValue(env, "LAGO_API_URL"));
}
function parseDatabaseBinding(env: CustomerPortalUatEnvironment): CustomerPortalUatDatabaseBinding {
const databaseUrl = requiredEnvironmentValue(env, "DATABASE_URL");
const expectedDatabaseHost = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE_HOST");
const expectedDatabasePort = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE_PORT");
const expectedDatabaseName = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_DATABASE");
const operatorUserId = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_OPERATOR_USER_ID");
const auditChainSecret = requiredEnvironmentValue(env, "AUDIT_CHAIN_SECRET");
let parsed: URL;
try {
parsed = new URL(databaseUrl);
} catch {
throw new CustomerPortalUatError("customer-portal UAT: DATABASE_URL must be a valid PostgreSQL URL");
}
const databaseName = decodeURIComponent(parsed.pathname.replace(/^\//u, ""));
if (!new Set(["postgres:", "postgresql:"]).has(parsed.protocol)) {
throw new CustomerPortalUatError("customer-portal UAT: DATABASE_URL must use PostgreSQL");
}
if (parsed.username !== "hivegrid_app" || !parsed.password) {
throw new CustomerPortalUatError("customer-portal UAT: DATABASE_URL must authenticate as hivegrid_app");
}
// pg-connection-string treats URI query parameters such as host, user,
// port, database, service and options as connection-setting overrides.
// Reject the entire query/fragment surface instead of trying to maintain a
// partial deny-list that can silently grow behind this staging mutation
// boundary.
if (parsed.search || parsed.hash) {
throw new CustomerPortalUatError("customer-portal UAT: DATABASE_URL must not contain PostgreSQL connection overrides");
}
if (parsed.hostname !== expectedDatabaseHost || parsed.port !== expectedDatabasePort || databaseName !== expectedDatabaseName) {
throw new CustomerPortalUatError("customer-portal UAT: DATABASE_URL does not match the explicit staging database binding");
}
return { databaseUrl, expectedDatabaseHost, expectedDatabasePort, expectedDatabaseName, operatorUserId, auditChainSecret };
}
function assertMutationConfirmation(argv: readonly string[], mode: CustomerPortalUatMode, target: CustomerPortalUatTarget): void {
const confirmation = parseSingleValueArgument(argv, "--confirm");
const expectedConfirmation = target === "commercial-fixture" ? CUSTOMER_PORTAL_UAT_COMMERCIAL_CONFIRMATION : CUSTOMER_PORTAL_UAT_TENANT_SLUG;
if (mode === "apply") {
if (confirmation !== expectedConfirmation) {
throw new CustomerPortalUatError(`customer-portal UAT: apply requires --confirm=${expectedConfirmation}`);
}
return;
}
if (confirmation !== undefined) {
throw new CustomerPortalUatError("customer-portal UAT: --confirm is valid only with --apply");
}
}
function requireStrongUatPassword(env: CustomerPortalUatEnvironment): string {
const password = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_PASSWORD");
if (password.length < 20 || new Set(password).size < 10 || /^(?:password|passwort|demo|hivegrid)/iu.test(password)) {
throw new CustomerPortalUatError("customer-portal UAT: CUSTOMER_PORTAL_UAT_PASSWORD must be a strong random secret of at least 20 characters");
}
return password;
}
export function parseCustomerPortalUatCommand(
target: CustomerPortalUatTarget,
argv: readonly string[],
env: CustomerPortalUatEnvironment
): CustomerPortalUatCommand {
assertKnownArguments(argv);
const mode = parseMode(argv);
assertMutationConfirmation(argv, mode, target);
assertOperatorEnvironment(env);
const database = parseDatabaseBinding(env);
if (target === "catalog") {
return {
...database,
target,
mode,
lagoApiUrl: requireStagingLagoApiUrl(env),
lagoApiKey: requiredEnvironmentValue(env, "LAGO_API_KEY"),
};
}
if (target === "fixture") {
return {
...database,
target,
mode,
expectedTenantId: requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_TENANT_ID"),
password: requireStrongUatPassword(env),
};
}
const expectedStarterTenantId = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_STARTER_TENANT_ID");
const expectedProTenantId = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_PRO_TENANT_ID");
const expectedEnterpriseTenantId = requiredEnvironmentValue(env, "CUSTOMER_PORTAL_UAT_EXPECTED_ENTERPRISE_TENANT_ID");
if (new Set([expectedStarterTenantId, expectedProTenantId, expectedEnterpriseTenantId]).size !== 3) {
throw new CustomerPortalUatError("customer-portal UAT: starter, pro, and Enterprise tenant bindings must be distinct");
}
return {
...database,
target,
mode,
expectedStarterTenantId,
expectedProTenantId,
expectedEnterpriseTenantId,
password: requireStrongUatPassword(env),
};
}
export function safeCustomerPortalUatError(error: unknown): string {
if (error instanceof CustomerPortalUatError) return error.message;
return "customer-portal UAT: operator command failed; inspect redacted service logs";
}
@@ -0,0 +1,76 @@
// @vitest-environment node
import { describe, expect, it } from "vitest";
import { computeAuditChainHeadMac, type AuditChainHeadRecord } from "@hivegrid/db/audit-chain-checkpoint.server";
import { assertCustomerPortalAuditAnchor, assertCustomerPortalDatabaseSession, assertCustomerPortalOperatorIdentity } from "./database";
const stagingSession = {
sessionUser: "hivegrid_app",
currentUser: "hivegrid_app",
databaseName: "hivegrid_staging",
databaseEnvironmentMarked: true,
roleIsSuperuser: false,
roleBypassesRls: false,
roleCanCreateRole: false,
roleCanCreateDatabase: false,
} as const;
describe("customer-portal operator database guard", () => {
it("accepts only the restricted runtime role on the explicitly bound staging database", () => {
expect(() => assertCustomerPortalDatabaseSession(stagingSession, "hivegrid_staging")).not.toThrow();
});
it("fails closed when the independent staging marker is missing or different", () => {
expect(() => assertCustomerPortalDatabaseSession({ ...stagingSession, databaseEnvironmentMarked: false }, "hivegrid_staging")).toThrow(
"database is not independently marked as staging"
);
});
it("rejects a privileged role or a different database even with the staging marker", () => {
expect(() => assertCustomerPortalDatabaseSession({ ...stagingSession, sessionUser: "postgres" }, "hivegrid_staging")).toThrow(
"database session is not the restricted hivegrid_app role"
);
expect(() => assertCustomerPortalDatabaseSession(stagingSession, "hivegrid_production")).toThrow(
"connected database does not match the explicit staging binding"
);
});
it.each([
["superuser", { roleIsSuperuser: true }],
["BYPASSRLS", { roleBypassesRls: true }],
["CREATEROLE", { roleCanCreateRole: true }],
["CREATEDB", { roleCanCreateDatabase: true }],
])("rejects a hivegrid_app role with %s privilege", (_label, privilege) => {
expect(() => assertCustomerPortalDatabaseSession({ ...stagingSession, ...privilege }, "hivegrid_staging")).toThrow(
"database session is not the restricted hivegrid_app role"
);
});
it("authenticates the existing platform audit anchor and rejects a different long secret", () => {
const anchorWithoutMac: Omit<AuditChainHeadRecord, "headMac"> = {
chainKey: "platform",
tenantId: null,
eventId: "event-1",
eventHash: "a".repeat(64),
eventCreatedAt: new Date("2026-07-17T00:00:00.000Z"),
};
const canonicalSecret = "canonical-staging-audit-secret-at-least-32-bytes";
const anchor = { ...anchorWithoutMac, headMac: computeAuditChainHeadMac(anchorWithoutMac, canonicalSecret) };
expect(() => assertCustomerPortalAuditAnchor(anchor, canonicalSecret)).not.toThrow();
expect(() => assertCustomerPortalAuditAnchor(anchor, "wrong-but-still-long-audit-secret-at-least-32-bytes")).toThrow(
"audit-chain anchor authentication failed"
);
expect(() => assertCustomerPortalAuditAnchor(null, canonicalSecret)).toThrow("audit-chain anchor authentication failed");
});
it("accepts only the explicitly bound active platform AdminUser", () => {
expect(() => assertCustomerPortalOperatorIdentity({ id: "admin-1", status: "active" }, "admin-1")).not.toThrow();
expect(() => assertCustomerPortalOperatorIdentity({ id: "admin-2", status: "active" }, "admin-1")).toThrow(
"operator identity is not an active AdminUser"
);
expect(() => assertCustomerPortalOperatorIdentity({ id: "admin-1", status: "disabled" }, "admin-1")).toThrow(
"operator identity is not an active AdminUser"
);
expect(() => assertCustomerPortalOperatorIdentity(null, "admin-1")).toThrow("operator identity is not an active AdminUser");
});
});
@@ -0,0 +1,99 @@
import { getDbClient, type DbClient } from "@hivegrid/db/client.server";
import {
auditChainKey,
verifyAuditChainHead,
type AuditChainHeadRecord,
} from "@hivegrid/db/audit-chain-checkpoint.server";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
import { CustomerPortalUatError, type CustomerPortalUatDatabaseBinding } from "./contracts";
type DatabaseSession = {
readonly sessionUser: string;
readonly currentUser: string;
readonly databaseName: string;
readonly databaseEnvironmentMarked: boolean;
readonly roleIsSuperuser: boolean;
readonly roleBypassesRls: boolean;
readonly roleCanCreateRole: boolean;
readonly roleCanCreateDatabase: boolean;
};
type OperatorIdentity = {
readonly id: string;
readonly status: string;
};
export function assertCustomerPortalDatabaseSession(session: DatabaseSession | undefined, expectedDatabaseName: string): void {
if (
!session ||
session.sessionUser !== "hivegrid_app" ||
session.currentUser !== "hivegrid_app" ||
session.roleIsSuperuser ||
session.roleBypassesRls ||
session.roleCanCreateRole ||
session.roleCanCreateDatabase
) {
throw new CustomerPortalUatError("customer-portal UAT: database session is not the restricted hivegrid_app role");
}
if (session.databaseName !== expectedDatabaseName) {
throw new CustomerPortalUatError("customer-portal UAT: connected database does not match the explicit staging binding");
}
if (!session.databaseEnvironmentMarked) {
throw new CustomerPortalUatError("customer-portal UAT: database is not independently marked as staging");
}
}
export function assertCustomerPortalAuditAnchor(head: AuditChainHeadRecord | null, auditChainSecret: string): void {
if (!head || head.chainKey !== auditChainKey(null) || head.tenantId !== null || !verifyAuditChainHead(head, auditChainSecret)) {
throw new CustomerPortalUatError("customer-portal UAT: canonical platform audit-chain anchor authentication failed");
}
}
export function assertCustomerPortalOperatorIdentity(operator: OperatorIdentity | null, expectedOperatorId: string): void {
if (!operator || operator.id !== expectedOperatorId || operator.status !== "active") {
throw new CustomerPortalUatError("customer-portal UAT: operator identity is not an active AdminUser");
}
}
export async function withCustomerPortalOperatorDatabase<T>(binding: CustomerPortalUatDatabaseBinding, callback: (db: DbClient) => Promise<T>): Promise<T> {
const db = getDbClient({ connectionString: binding.databaseUrl, poolMax: 2 });
try {
return await runWithRlsContext({ userId: binding.operatorUserId }, async () => {
const sessions = await db.$queryRaw<DatabaseSession[]>`
SELECT
session_user::text AS "sessionUser",
current_user::text AS "currentUser",
current_database()::text AS "databaseName",
role.rolsuper AS "roleIsSuperuser",
role.rolbypassrls AS "roleBypassesRls",
role.rolcreaterole AS "roleCanCreateRole",
role.rolcreatedb AS "roleCanCreateDatabase",
EXISTS (
SELECT 1
FROM pg_catalog.pg_db_role_setting AS setting
JOIN pg_catalog.pg_database AS database
ON database.oid = setting.setdatabase
WHERE database.datname = current_database()
AND setting.setrole = 0
AND 'hivegrid.environment=staging' = ANY(setting.setconfig)
) AS "databaseEnvironmentMarked"
FROM pg_catalog.pg_roles AS role
WHERE role.rolname = current_user
`;
const session = sessions[0];
assertCustomerPortalDatabaseSession(session, binding.expectedDatabaseName);
const operator = await db.adminUser.findUnique({
where: { id: binding.operatorUserId },
select: { id: true, status: true },
});
assertCustomerPortalOperatorIdentity(operator, binding.operatorUserId);
const platformAuditHead = await db.auditChainHead.findUnique({ where: { chainKey: auditChainKey(null) } });
assertCustomerPortalAuditAnchor(platformAuditHead, binding.auditChainSecret);
return callback(db);
});
} finally {
await db.$disconnect();
}
}
@@ -0,0 +1,276 @@
// @vitest-environment node
import { readFileSync } from "node:fs";
import { FormDefinitionSchema } from "../../packages/form-widget/src";
import { describe, expect, it } from "vitest";
import {
CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID,
CUSTOMER_PORTAL_UAT_PROJECT_ID,
CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN,
CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
CUSTOMER_PORTAL_UAT_TENANT_SLUG,
} from "./contracts";
import { assessCustomerPortalFixture, customerPortalUatComplaintDefinition, type CustomerPortalFixtureSnapshot } from "./fixture";
const tenantId = "tenant-demo-pro";
const expectedStageId = "stage-expected";
const forbiddenStageId = "stage-forbidden";
function healthySnapshot(): CustomerPortalFixtureSnapshot {
return {
tenant: {
id: tenantId,
slug: CUSTOMER_PORTAL_UAT_TENANT_SLUG,
active: true,
subscription: { planCode: "business", status: "active", frozenAt: null },
},
projects: [
{
id: CUSTOMER_PORTAL_UAT_PROJECT_ID,
projektname: "Wärmepumpe Mustermann",
projekttyp: "waermepumpe",
stageId: expectedStageId,
archivedAt: null,
stage: { name: "Montage", archivedAt: null },
},
{
id: CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID,
projektname: "Badsanierung Beispiel",
projekttyp: "bad",
stageId: forbiddenStageId,
archivedAt: null,
stage: { name: "Planung", archivedAt: null },
},
],
portal: {
id: "portal-1",
subdomain: CUSTOMER_PORTAL_UAT_TENANT_SLUG,
title: "Demo Pro CRM Kundenportal",
isPublished: true,
authRequireEmailVerification: false,
authRequireOrganization: false,
authRequireName: true,
metadata: { uatFixture: "VA-P26" },
},
configuration: {
lifecycleMode: "customer",
enabledProjectTypes: ["waermepumpe", "bad"],
uploadMaxFiles: 10,
uploadMaxFileSizeBytes: 52_428_800,
statusEmailsEnabled: true,
welcomeMessage: "Willkommen im HiveGrid Test-Kundenportal.",
supportEmail: "support@saas-ctrl.com",
imprintUrl: "https://saas-ctrl.com/impressum",
privacyUrl: "https://saas-ctrl.com/datenschutz",
isDemoData: true,
},
users: [
{
id: "customer-1",
emailNormalized: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
passwordHash: "hash",
passwordMatches: true,
firstName: "Karla",
lastName: "Kundin",
kind: "customer",
status: "active",
archivedAt: null,
emailVerifiedAt: new Date("2026-07-17T00:00:00.000Z"),
isDemoData: true,
},
{
id: "subcontractor-1",
emailNormalized: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
passwordHash: "hash",
passwordMatches: true,
firstName: "Sascha",
lastName: "Subunternehmer",
kind: "subcontractor",
status: "active",
archivedAt: null,
emailVerifiedAt: new Date("2026-07-17T00:00:00.000Z"),
isDemoData: true,
},
],
accesses: [
{
id: "access-customer",
portalUserId: "customer-1",
projectId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
active: true,
revokedAt: null,
isDemoData: true,
subcontractorAccess: null,
},
{
id: "access-subcontractor",
portalUserId: "subcontractor-1",
projectId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
active: true,
revokedAt: null,
isDemoData: true,
subcontractorAccess: { active: true, revokedAt: null, canUpload: true, isDemoData: true },
},
],
stageVisibilities: [
{ stageId: expectedStageId, visible: true, isDemoData: true },
{ stageId: forbiddenStageId, visible: true, isDemoData: true },
],
form: {
key: "customer-portal-uat-complaint-key",
name: "Kundenportal UAT Reklamation",
subtype: "portal_form",
status: "published",
publishedAt: new Date("2026-07-17T00:00:00.000Z"),
isPublic: true,
isEnabled: true,
isDemoData: true,
definition: customerPortalUatComplaintDefinition,
targetType: "project",
targetEntityId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
allowedOrigins: [CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN],
notifyEmails: [],
config: { honeypotEnabled: false },
},
inbox: {
portalId: "portal-1",
portalUserId: "customer-1",
projectId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
kind: "complaint",
status: "open",
priority: 100,
sourceId: "customer-portal-uat",
titleKey: "customerPortal.inbox.items.complaint",
metadata: { fixture: "VA-P26" },
bundledCount: 1,
ownerUserId: null,
resolvedAt: null,
expiresAt: new Date("2026-07-24T00:00:00.000Z"),
isDemoData: true,
},
};
}
describe("customer-portal UAT fixture contract", () => {
it("locks UAT-owned rows and revalidates the fixture inside the write transaction", () => {
const source = readFileSync(new URL("./fixture.ts", import.meta.url), "utf8");
expect(source).toContain("lockCustomerPortalFixtureRows(transactionDb, command)");
expect(source).toContain("const lockedSnapshot = await readCustomerPortalFixture(transactionDb, command)");
expect(source.match(/FOR UPDATE/gu)?.length).toBeGreaterThanOrEqual(8);
expect(source).toContain("key: UAT_FORM_KEY");
});
it("accepts the complete deterministic fixture and emits safe E2E handoff data", () => {
const assessment = assessCustomerPortalFixture(healthySnapshot(), tenantId, new Date("2026-07-17T10:00:00.000Z"));
expect(assessment.action).toBe("noop");
expect(assessment.e2e).toEqual({
portalBaseUrl: CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN,
tenantSlug: CUSTOMER_PORTAL_UAT_TENANT_SLUG,
customerEmail: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
subcontractorEmail: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
subcontractorExpectedProject: "Wärmepumpe Mustermann",
subcontractorForbiddenProject: "Badsanierung Beispiel",
});
expect(JSON.stringify(assessment)).not.toContain("passwordHash");
});
it("marks missing UAT-owned rows as reconcilable", () => {
const snapshot = healthySnapshot();
const assessment = assessCustomerPortalFixture({ ...snapshot, portal: null, configuration: null, users: [], accesses: [] }, tenantId);
expect(assessment.action).toBe("reconcile");
expect(assessment.blockingIssues).toEqual([]);
});
it("blocks collisions with non-demo identities and access rows", () => {
const snapshot = healthySnapshot();
const users = snapshot.users.map((user) => (user.emailNormalized === CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL ? { ...user, isDemoData: false } : user));
const accesses = [
...snapshot.accesses,
{
id: "unsafe-extra",
portalUserId: "subcontractor-1",
projectId: CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID,
active: true,
revokedAt: null,
isDemoData: false,
subcontractorAccess: null,
},
];
const assessment = assessCustomerPortalFixture({ ...snapshot, users, accesses }, tenantId);
expect(assessment.action).toBe("blocked");
expect(assessment.blockingIssues).toEqual(
expect.arrayContaining(["customer UAT identity is not UAT-owned demo data", "subcontractor has a non-demo extra project access"])
);
});
it("does not take over an existing unmarked portal", () => {
const snapshot = healthySnapshot();
const assessment = assessCustomerPortalFixture({ ...snapshot, portal: { ...snapshot.portal!, metadata: null } }, tenantId);
expect(assessment.action).toBe("blocked");
expect(assessment.blockingIssues).toContain("existing portal is not marked as the VA-P26 UAT fixture");
});
it.each([
["portal standard-host", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, portal: { ...snapshot.portal!, subdomain: "wrong" } })],
["portal title", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, portal: { ...snapshot.portal!, title: "Wrong" } })],
[
"canonical user name",
(snapshot: CustomerPortalFixtureSnapshot) => ({
...snapshot,
users: snapshot.users.map((user) => (user.emailNormalized === CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL ? { ...user, firstName: "Wrong" } : user)),
}),
],
["form definition", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, form: { ...snapshot.form!, definition: { fields: [] } } })],
["form key", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, form: { ...snapshot.form!, key: "wrong-key" } })],
["form config", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, form: { ...snapshot.form!, config: { honeypotEnabled: true } } })],
[
"portal configuration",
(snapshot: CustomerPortalFixtureSnapshot) => ({
...snapshot,
configuration: { ...snapshot.configuration!, lifecycleMode: "subcontractor", statusEmailsEnabled: false, supportEmail: "wrong@example.test" },
}),
],
["form origin", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, form: { ...snapshot.form!, allowedOrigins: [CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN, "https://extra.example"] } })],
["inbox project", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, inbox: { ...snapshot.inbox!, projectId: CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID } })],
["inbox customer", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, inbox: { ...snapshot.inbox!, portalUserId: "subcontractor-1" } })],
["inbox kind", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, inbox: { ...snapshot.inbox!, kind: "upload" } })],
["inbox source", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, inbox: { ...snapshot.inbox!, sourceId: "foreign" } })],
["inbox title", (snapshot: CustomerPortalFixtureSnapshot) => ({ ...snapshot, inbox: { ...snapshot.inbox!, titleKey: "foreign.title" } })],
])("reports %s drift instead of accepting fixture verify", (_label, drift) => {
const assessment = assessCustomerPortalFixture(drift(healthySnapshot()), tenantId, new Date("2026-07-17T10:00:00.000Z"));
expect(assessment.action).toBe("reconcile");
});
it("does not reactivate non-UAT subcontractor scopes or stage visibility", () => {
const snapshot = healthySnapshot();
const accesses = snapshot.accesses.map((access) =>
access.portalUserId === "subcontractor-1"
? {
...access,
subcontractorAccess: { active: false, revokedAt: new Date("2026-07-16T00:00:00.000Z"), canUpload: false, isDemoData: false },
}
: access
);
const stageVisibilities = snapshot.stageVisibilities.map((visibility) =>
visibility.stageId === forbiddenStageId ? { ...visibility, visible: false, isDemoData: false } : visibility
);
const assessment = assessCustomerPortalFixture({ ...snapshot, accesses, stageVisibilities }, tenantId);
expect(assessment.action).toBe("blocked");
expect(assessment.blockingIssues).toEqual(
expect.arrayContaining(["subcontractor scope record is not UAT-owned demo data", `stage visibility ${forbiddenStageId} is not UAT-owned demo data`])
);
});
it("does not take over the deterministic project access when it is not demo-owned", () => {
const snapshot = healthySnapshot();
const accesses = snapshot.accesses.map((access) => (access.portalUserId === "customer-1" ? { ...access, isDemoData: false } : access));
const assessment = assessCustomerPortalFixture({ ...snapshot, accesses }, tenantId);
expect(assessment.action).toBe("blocked");
expect(assessment.blockingIssues).toContain("customer project access is not UAT-owned demo data");
});
it("keeps the fixture complaint form on the shared FormDefinition contract", () => {
expect(FormDefinitionSchema.safeParse(customerPortalUatComplaintDefinition).success).toBe(true);
});
});
@@ -0,0 +1,951 @@
import { hashCurrentPassword, verifySupportedPassword } from "../../apps/api/src/auth/password";
import { isDeepStrictEqual } from "node:util";
import { publishAuditEventViaOutbox } from "@hivegrid/db/audit-events.server";
import type { DbClient } from "@hivegrid/db/client.server";
import type { Prisma } from "@hivegrid/db/prisma-browser";
import {
CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID,
CUSTOMER_PORTAL_UAT_PROJECT_ID,
CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN,
CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
CUSTOMER_PORTAL_UAT_TENANT_SLUG,
CustomerPortalUatError,
type CustomerPortalFixtureCommand,
} from "./contracts";
const UAT_FORM_SLUG = "customer-portal-uat-complaint";
const UAT_FORM_KEY = "customer-portal-uat-complaint-key";
const UAT_FORM_NAME = "Kundenportal UAT Reklamation";
const UAT_INBOX_SOURCE_KEY = "customer-portal-uat:initial-service-item";
const UAT_INBOX_SOURCE_ID = "customer-portal-uat";
const UAT_INBOX_TITLE_KEY = "customerPortal.inbox.items.complaint";
const UAT_LEGAL_ORIGIN = "https://saas-ctrl.com";
const UAT_PORTAL_TITLE = "Demo Pro CRM Kundenportal";
const UAT_VERIFIED_AT = new Date("2026-07-17T00:00:00.000Z");
export const customerPortalUatComplaintDefinition = Object.freeze({
title: "Reklamation",
submitLabel: "Reklamation senden",
successMessage: "Deine Reklamation wurde gespeichert und das Projektteam informiert.",
gdprConsentLabel: "Ich stimme der Verarbeitung meiner Angaben zur Bearbeitung der Reklamation zu.",
fields: Object.freeze([
Object.freeze({ key: "subject", type: "text", label: "Betreff", required: true, validationRules: { minLength: 3, maxLength: 200 } }),
Object.freeze({ key: "details", type: "textarea", label: "Beschreibung", required: true, validationRules: { minLength: 3, maxLength: 5_000 } }),
]),
});
type FixtureProject = {
readonly id: string;
readonly projektname: string;
readonly projekttyp: string | null;
readonly stageId: string;
readonly archivedAt: Date | null;
readonly stage: { readonly name: string; readonly archivedAt: Date | null };
};
type FixtureUser = {
readonly id: string;
readonly emailNormalized: string;
readonly passwordHash: string | null;
readonly passwordMatches: boolean;
readonly firstName: string;
readonly lastName: string;
readonly kind: string;
readonly status: string;
readonly archivedAt: Date | null;
readonly emailVerifiedAt: Date | null;
readonly isDemoData: boolean;
};
type FixtureAccess = {
readonly id: string;
readonly portalUserId: string;
readonly projectId: string;
readonly active: boolean;
readonly revokedAt: Date | null;
readonly isDemoData: boolean;
readonly subcontractorAccess: {
readonly active: boolean;
readonly revokedAt: Date | null;
readonly canUpload: boolean;
readonly isDemoData: boolean;
} | null;
};
export type CustomerPortalFixtureSnapshot = {
readonly tenant: {
readonly id: string;
readonly slug: string;
readonly active: boolean;
readonly subscription: { readonly planCode: string | null; readonly status: string; readonly frozenAt: Date | null } | null;
} | null;
readonly projects: readonly FixtureProject[];
readonly portal: {
readonly id: string;
readonly subdomain: string;
readonly title: string;
readonly isPublished: boolean;
readonly authRequireEmailVerification: boolean;
readonly authRequireOrganization: boolean;
readonly authRequireName: boolean;
readonly metadata: unknown;
} | null;
readonly configuration: {
readonly lifecycleMode: string;
readonly enabledProjectTypes: readonly string[];
readonly uploadMaxFiles: number;
readonly uploadMaxFileSizeBytes: number;
readonly statusEmailsEnabled: boolean;
readonly welcomeMessage: string | null;
readonly supportEmail: string | null;
readonly imprintUrl: string | null;
readonly privacyUrl: string | null;
readonly isDemoData: boolean;
} | null;
readonly users: readonly FixtureUser[];
readonly accesses: readonly FixtureAccess[];
readonly stageVisibilities: readonly {
readonly stageId: string;
readonly visible: boolean;
readonly isDemoData: boolean;
}[];
readonly form: {
readonly key: string;
readonly name: string;
readonly subtype: string;
readonly status: string;
readonly publishedAt: Date | null;
readonly isPublic: boolean;
readonly isEnabled: boolean;
readonly isDemoData: boolean;
readonly definition: unknown;
readonly targetType: string | null;
readonly targetEntityId: string | null;
readonly allowedOrigins: readonly string[];
readonly notifyEmails: readonly string[];
readonly config: unknown;
} | null;
readonly inbox: {
readonly portalId: string;
readonly portalUserId: string | null;
readonly projectId: string | null;
readonly kind: string;
readonly status: string;
readonly priority: number;
readonly sourceId: string | null;
readonly titleKey: string;
readonly metadata: unknown;
readonly bundledCount: number;
readonly ownerUserId: string | null;
readonly resolvedAt: Date | null;
readonly expiresAt: Date;
readonly isDemoData: boolean;
} | null;
};
export type CustomerPortalFixtureAssessment = {
readonly action: "noop" | "reconcile" | "blocked";
readonly reconcileIssues: readonly string[];
readonly blockingIssues: readonly string[];
readonly e2e: {
readonly portalBaseUrl: typeof CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN;
readonly tenantSlug: typeof CUSTOMER_PORTAL_UAT_TENANT_SLUG;
readonly customerEmail: typeof CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL;
readonly subcontractorEmail: typeof CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL;
readonly subcontractorExpectedProject: string | null;
readonly subcontractorForbiddenProject: string | null;
};
};
function findUser(snapshot: CustomerPortalFixtureSnapshot, email: string): FixtureUser | undefined {
return snapshot.users.find((user) => user.emailNormalized === email);
}
function projectById(snapshot: CustomerPortalFixtureSnapshot, id: string): FixtureProject | undefined {
return snapshot.projects.find((project) => project.id === id);
}
function isUatOwnedPortal(metadata: unknown): boolean {
return typeof metadata === "object" && metadata !== null && "uatFixture" in metadata && metadata.uatFixture === "VA-P26";
}
export function assessCustomerPortalFixture(
snapshot: CustomerPortalFixtureSnapshot,
expectedTenantId: string,
now: Date = new Date()
): CustomerPortalFixtureAssessment {
const reconcileIssues: string[] = [];
const blockingIssues: string[] = [];
const expectedProject = projectById(snapshot, CUSTOMER_PORTAL_UAT_PROJECT_ID);
const forbiddenProject = projectById(snapshot, CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID);
if (!snapshot.tenant) blockingIssues.push("target tenant is not visible under the operator RLS context");
else {
if (snapshot.tenant.id !== expectedTenantId || snapshot.tenant.slug !== CUSTOMER_PORTAL_UAT_TENANT_SLUG) {
blockingIssues.push("target tenant does not match the explicit demo-pro-crm binding");
}
if (!snapshot.tenant.active) blockingIssues.push("target tenant is inactive");
if (
snapshot.tenant.subscription?.planCode !== "business" ||
snapshot.tenant.subscription.status.toLowerCase() !== "active" ||
snapshot.tenant.subscription.frozenAt !== null
) {
blockingIssues.push("target tenant must have an active, non-frozen business subscription");
}
}
for (const [label, project] of [
["expected", expectedProject],
["forbidden", forbiddenProject],
] as const) {
if (!project || project.archivedAt || project.stage.archivedAt || !project.projekttyp) {
blockingIssues.push(`${label} deterministic UAT project is missing, archived, or incomplete`);
}
}
if (expectedProject && forbiddenProject && expectedProject.projektname === forbiddenProject.projektname) {
blockingIssues.push("expected and forbidden UAT projects must have distinct names");
}
if (!snapshot.portal) reconcileIssues.push("published portal missing");
else {
if (!isUatOwnedPortal(snapshot.portal.metadata)) blockingIssues.push("existing portal is not marked as the VA-P26 UAT fixture");
if (
snapshot.portal.subdomain !== CUSTOMER_PORTAL_UAT_TENANT_SLUG ||
snapshot.portal.title !== UAT_PORTAL_TITLE ||
!snapshot.portal.isPublished ||
snapshot.portal.authRequireEmailVerification ||
snapshot.portal.authRequireOrganization ||
!snapshot.portal.authRequireName
) {
reconcileIssues.push("portal publication, standard-host, title, or login contract differs");
}
}
const requiredProjectTypes = [...new Set([expectedProject?.projekttyp, forbiddenProject?.projekttyp].filter((value): value is string => Boolean(value)))];
if (!snapshot.configuration) reconcileIssues.push("portal configuration missing");
else {
if (!snapshot.configuration.isDemoData) blockingIssues.push("existing portal configuration is not UAT-owned demo data");
if (
snapshot.configuration.lifecycleMode !== "customer" ||
!isDeepStrictEqual([...snapshot.configuration.enabledProjectTypes].sort(), [...requiredProjectTypes].sort()) ||
!snapshot.configuration.statusEmailsEnabled ||
snapshot.configuration.welcomeMessage !== "Willkommen im HiveGrid Test-Kundenportal." ||
snapshot.configuration.supportEmail !== "support@saas-ctrl.com"
) {
reconcileIssues.push("portal configuration does not enable the deterministic project types");
}
if (snapshot.configuration.uploadMaxFiles < 2 || snapshot.configuration.uploadMaxFileSizeBytes < 1_024) {
reconcileIssues.push("portal upload configuration is insufficient for the P26b journey");
}
if (!snapshot.configuration.imprintUrl || !snapshot.configuration.privacyUrl) {
reconcileIssues.push("portal legal links are incomplete");
}
}
const expectedUsers = [
{ email: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL, kind: "customer" },
{ email: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL, kind: "subcontractor" },
] as const;
for (const expected of expectedUsers) {
const user = findUser(snapshot, expected.email);
if (!user) {
reconcileIssues.push(`${expected.kind} UAT identity missing`);
continue;
}
if (!user.isDemoData) blockingIssues.push(`${expected.kind} UAT identity is not UAT-owned demo data`);
const canonicalName = expected.kind === "customer" ? ["Karla", "Kundin"] : ["Sascha", "Subunternehmer"];
if (
user.firstName !== canonicalName[0] ||
user.lastName !== canonicalName[1] ||
user.kind !== expected.kind ||
user.status !== "active" ||
user.archivedAt !== null ||
user.emailVerifiedAt === null ||
!user.passwordMatches
) {
reconcileIssues.push(`${expected.kind} UAT identity differs from the login contract`);
}
}
if (snapshot.portal && expectedProject) {
const customer = findUser(snapshot, CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL);
const subcontractor = findUser(snapshot, CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL);
for (const [kind, user] of [
["customer", customer],
["subcontractor", subcontractor],
] as const) {
if (!user) continue;
const activeAccesses = snapshot.accesses.filter((access) => access.portalUserId === user.id && access.active && !access.revokedAt);
const expectedAccess = activeAccesses.find((access) => access.projectId === expectedProject.id);
if (!expectedAccess) reconcileIssues.push(`${kind} project access missing`);
else if (!expectedAccess.isDemoData) blockingIssues.push(`${kind} project access is not UAT-owned demo data`);
const extra = activeAccesses.filter((access) => access.projectId !== expectedProject.id);
if (extra.some((access) => !access.isDemoData)) blockingIssues.push(`${kind} has a non-demo extra project access`);
else if (extra.length > 0) reconcileIssues.push(`${kind} has extra active demo project access`);
if (kind === "subcontractor" && expectedAccess) {
const sub = expectedAccess.subcontractorAccess;
if (sub && !sub.isDemoData) blockingIssues.push("subcontractor scope record is not UAT-owned demo data");
else if (!sub || !sub.active || sub.revokedAt || !sub.canUpload) reconcileIssues.push("subcontractor scope record is missing or inactive");
}
}
}
const requiredStageIds = [expectedProject?.stageId, forbiddenProject?.stageId].filter((value): value is string => Boolean(value));
for (const stageId of requiredStageIds) {
const visibility = snapshot.stageVisibilities.find((candidate) => candidate.stageId === stageId);
if (visibility && !visibility.isDemoData) blockingIssues.push(`stage visibility ${stageId} is not UAT-owned demo data`);
else if (!visibility?.visible) reconcileIssues.push(`stage visibility ${stageId} is incomplete`);
}
if (!snapshot.form) reconcileIssues.push("project-specific portal complaint form missing");
else {
if (!snapshot.form.isDemoData) blockingIssues.push("existing UAT complaint form is not UAT-owned demo data");
if (
snapshot.form.subtype !== "portal_form" ||
snapshot.form.key !== UAT_FORM_KEY ||
snapshot.form.name !== UAT_FORM_NAME ||
snapshot.form.status !== "published" ||
snapshot.form.publishedAt === null ||
!snapshot.form.isPublic ||
!snapshot.form.isEnabled ||
!isDeepStrictEqual(snapshot.form.definition, customerPortalUatComplaintDefinition) ||
snapshot.form.targetType !== "project" ||
snapshot.form.targetEntityId !== CUSTOMER_PORTAL_UAT_PROJECT_ID ||
!isDeepStrictEqual(snapshot.form.allowedOrigins, [CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN]) ||
!isDeepStrictEqual(snapshot.form.notifyEmails, []) ||
!isDeepStrictEqual(snapshot.form.config, { honeypotEnabled: false })
) {
reconcileIssues.push("portal complaint form differs from the P26b contract");
}
}
if (!snapshot.inbox) reconcileIssues.push("open service-inbox UAT item missing");
else {
if (!snapshot.inbox.isDemoData) blockingIssues.push("existing UAT inbox item is not UAT-owned demo data");
const customer = findUser(snapshot, CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL);
if (
snapshot.inbox.portalId !== snapshot.portal?.id ||
snapshot.inbox.portalUserId !== customer?.id ||
snapshot.inbox.projectId !== expectedProject?.id ||
snapshot.inbox.kind !== "complaint" ||
snapshot.inbox.status !== "open" ||
snapshot.inbox.priority !== 100 ||
snapshot.inbox.sourceId !== UAT_INBOX_SOURCE_ID ||
snapshot.inbox.titleKey !== UAT_INBOX_TITLE_KEY ||
!isDeepStrictEqual(snapshot.inbox.metadata, { fixture: "VA-P26" }) ||
snapshot.inbox.bundledCount !== 1 ||
snapshot.inbox.ownerUserId !== null ||
snapshot.inbox.resolvedAt !== null ||
snapshot.inbox.expiresAt.getTime() <= now.getTime()
) {
reconcileIssues.push("service-inbox UAT item differs from the canonical project, customer, source, title, or lifecycle contract");
}
}
return {
action: blockingIssues.length > 0 ? "blocked" : reconcileIssues.length > 0 ? "reconcile" : "noop",
reconcileIssues,
blockingIssues,
e2e: {
portalBaseUrl: CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN,
tenantSlug: CUSTOMER_PORTAL_UAT_TENANT_SLUG,
customerEmail: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
subcontractorEmail: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
subcontractorExpectedProject: expectedProject?.projektname ?? null,
subcontractorForbiddenProject: forbiddenProject?.projektname ?? null,
},
};
}
export async function readCustomerPortalFixture(db: DbClient, command: CustomerPortalFixtureCommand): Promise<CustomerPortalFixtureSnapshot> {
const tenant = await db.tenant.findFirst({
where: { id: command.expectedTenantId, slug: CUSTOMER_PORTAL_UAT_TENANT_SLUG },
select: { id: true, slug: true, active: true, subscription: { select: { planCode: true, status: true, frozenAt: true } } },
});
const projects = await db.projekt.findMany({
where: { tenantId: command.expectedTenantId, id: { in: [CUSTOMER_PORTAL_UAT_PROJECT_ID, CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID] } },
select: { id: true, projektname: true, projekttyp: true, stageId: true, archivedAt: true, stage: { select: { name: true, archivedAt: true } } },
});
const portal = await db.portal.findUnique({
where: { tenantId: command.expectedTenantId },
select: {
id: true,
subdomain: true,
title: true,
isPublished: true,
authRequireEmailVerification: true,
authRequireOrganization: true,
authRequireName: true,
metadata: true,
},
});
if (!portal) {
const [form, inbox] = await Promise.all([
db.form.findUnique({ where: { tenantId_slug: { tenantId: command.expectedTenantId, slug: UAT_FORM_SLUG } }, select: fixtureFormSelect }),
db.portalServiceInboxItem.findUnique({
where: { tenantId_sourceKey: { tenantId: command.expectedTenantId, sourceKey: UAT_INBOX_SOURCE_KEY } },
select: fixtureInboxSelect,
}),
]);
return { tenant, projects, portal: null, configuration: null, users: [], accesses: [], stageVisibilities: [], form, inbox };
}
const [configuration, rawUsers, visibleStages, form, inbox] = await Promise.all([
db.portalConfiguration.findUnique({
where: { portalId_tenantId: { portalId: portal.id, tenantId: command.expectedTenantId } },
select: {
lifecycleMode: true,
enabledProjectTypes: true,
uploadMaxFiles: true,
uploadMaxFileSizeBytes: true,
statusEmailsEnabled: true,
welcomeMessage: true,
supportEmail: true,
imprintUrl: true,
privacyUrl: true,
isDemoData: true,
},
}),
db.portalUser.findMany({
where: {
tenantId: command.expectedTenantId,
portalId: portal.id,
emailNormalized: { in: [CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL, CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL] },
},
select: {
id: true,
emailNormalized: true,
passwordHash: true,
firstName: true,
lastName: true,
kind: true,
status: true,
archivedAt: true,
emailVerifiedAt: true,
isDemoData: true,
},
}),
db.portalStageVisibility.findMany({
where: {
tenantId: command.expectedTenantId,
portalId: portal.id,
stageId: { in: projects.map((project) => project.stageId) },
},
select: { stageId: true, visible: true, isDemoData: true },
}),
db.form.findUnique({ where: { tenantId_slug: { tenantId: command.expectedTenantId, slug: UAT_FORM_SLUG } }, select: fixtureFormSelect }),
db.portalServiceInboxItem.findUnique({
where: { tenantId_sourceKey: { tenantId: command.expectedTenantId, sourceKey: UAT_INBOX_SOURCE_KEY } },
select: fixtureInboxSelect,
}),
]);
const users: FixtureUser[] = await Promise.all(
rawUsers.map(async (user) => ({
...user,
kind: String(user.kind),
status: String(user.status),
passwordMatches: user.passwordHash ? await verifySupportedPassword(command.password, user.passwordHash) : false,
}))
);
const accesses =
users.length === 0
? []
: await db.portalProjectAccess.findMany({
where: { tenantId: command.expectedTenantId, portalId: portal.id, portalUserId: { in: users.map((user) => user.id) } },
select: {
id: true,
portalUserId: true,
projectId: true,
active: true,
revokedAt: true,
isDemoData: true,
subcontractorAccess: { select: { active: true, revokedAt: true, canUpload: true, isDemoData: true } },
},
});
return {
tenant,
projects,
portal,
configuration,
users,
accesses,
stageVisibilities: visibleStages,
form,
inbox,
};
}
const fixtureFormSelect = {
key: true,
name: true,
subtype: true,
status: true,
publishedAt: true,
isPublic: true,
isEnabled: true,
isDemoData: true,
definition: true,
targetType: true,
targetEntityId: true,
allowedOrigins: true,
notifyEmails: true,
config: true,
} as const;
const fixtureInboxSelect = {
portalId: true,
portalUserId: true,
projectId: true,
kind: true,
status: true,
priority: true,
sourceId: true,
titleKey: true,
metadata: true,
bundledCount: true,
ownerUserId: true,
resolvedAt: true,
expiresAt: true,
isDemoData: true,
} as const;
async function passwordHashForUser(snapshot: CustomerPortalFixtureSnapshot, email: string, password: string): Promise<string> {
const existing = findUser(snapshot, email);
return existing?.passwordMatches && existing.passwordHash ? existing.passwordHash : hashCurrentPassword(password);
}
async function lockCustomerPortalFixtureRows(db: DbClient, command: CustomerPortalFixtureCommand): Promise<void> {
const tenantLocks = await db.$queryRaw<Array<{ id: string }>>`
SELECT tenant."id"
FROM "Tenant" AS tenant
WHERE tenant."id" = ${command.expectedTenantId}
AND tenant."slug" = ${CUSTOMER_PORTAL_UAT_TENANT_SLUG}
FOR UPDATE
`;
if (tenantLocks.length !== 1) {
throw new CustomerPortalUatError("customer-portal UAT: target tenant changed after guarded preflight");
}
await db.$queryRaw`
SELECT project."id"
FROM "Projekt" AS project
WHERE project."tenantId" = ${command.expectedTenantId}
AND (project."id" = ${CUSTOMER_PORTAL_UAT_PROJECT_ID} OR project."id" = ${CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID})
FOR UPDATE
`;
await db.$queryRaw`
SELECT portal."id"
FROM "Portal" AS portal
WHERE portal."tenantId" = ${command.expectedTenantId}
FOR UPDATE
`;
await db.$queryRaw`
SELECT configuration."id"
FROM "PortalConfiguration" AS configuration
WHERE configuration."tenantId" = ${command.expectedTenantId}
FOR UPDATE
`;
await db.$queryRaw`
SELECT portal_user."id"
FROM "PortalUser" AS portal_user
WHERE portal_user."tenantId" = ${command.expectedTenantId}
AND (
portal_user."id" IN ('customer-portal-uat-customer', 'customer-portal-uat-subcontractor')
OR portal_user."emailNormalized" = ${CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL}
OR portal_user."emailNormalized" = ${CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL}
)
FOR UPDATE
`;
await db.$queryRaw`
SELECT project_access."id"
FROM "PortalProjectAccess" AS project_access
WHERE project_access."tenantId" = ${command.expectedTenantId}
AND project_access."portalUserId" IN (
SELECT portal_user."id"
FROM "PortalUser" AS portal_user
WHERE portal_user."tenantId" = ${command.expectedTenantId}
AND (
portal_user."id" IN ('customer-portal-uat-customer', 'customer-portal-uat-subcontractor')
OR portal_user."emailNormalized" = ${CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL}
OR portal_user."emailNormalized" = ${CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL}
)
)
FOR UPDATE
`;
await db.$queryRaw`
SELECT subcontractor_access."id"
FROM "PortalSubcontractorAccess" AS subcontractor_access
WHERE subcontractor_access."tenantId" = ${command.expectedTenantId}
AND subcontractor_access."portalUserId" IN (
SELECT portal_user."id"
FROM "PortalUser" AS portal_user
WHERE portal_user."tenantId" = ${command.expectedTenantId}
AND (
portal_user."id" IN ('customer-portal-uat-customer', 'customer-portal-uat-subcontractor')
OR portal_user."emailNormalized" = ${CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL}
OR portal_user."emailNormalized" = ${CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL}
)
)
FOR UPDATE
`;
await db.$queryRaw`
SELECT visibility."id"
FROM "PortalStageVisibility" AS visibility
WHERE visibility."tenantId" = ${command.expectedTenantId}
AND visibility."stageId" IN (
SELECT project."stageId"
FROM "Projekt" AS project
WHERE project."tenantId" = ${command.expectedTenantId}
AND (project."id" = ${CUSTOMER_PORTAL_UAT_PROJECT_ID} OR project."id" = ${CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID})
)
FOR UPDATE
`;
await db.$queryRaw`
SELECT form."id"
FROM "Form" AS form
WHERE form."tenantId" = ${command.expectedTenantId}
AND (form."id" = 'customer-portal-uat-complaint-form' OR form."slug" = ${UAT_FORM_SLUG} OR form."key" = ${UAT_FORM_KEY})
FOR UPDATE
`;
await db.$queryRaw`
SELECT inbox."id"
FROM "PortalServiceInboxItem" AS inbox
WHERE inbox."tenantId" = ${command.expectedTenantId}
AND (inbox."id" = 'customer-portal-uat-inbox-item' OR inbox."sourceKey" = ${UAT_INBOX_SOURCE_KEY})
FOR UPDATE
`;
}
export async function applyCustomerPortalFixture(db: DbClient, command: CustomerPortalFixtureCommand, snapshot: CustomerPortalFixtureSnapshot): Promise<void> {
const assessment = assessCustomerPortalFixture(snapshot, command.expectedTenantId);
if (assessment.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: fixture apply is blocked by non-UAT or mismatched staging state");
}
if (assessment.action === "noop") return;
const now = new Date();
const inboxExpiry = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1_000);
await db.$transaction(async (tx) => {
const transactionDb = tx as unknown as DbClient;
await lockCustomerPortalFixtureRows(transactionDb, command);
const lockedSnapshot = await readCustomerPortalFixture(transactionDb, command);
const lockedAssessment = assessCustomerPortalFixture(lockedSnapshot, command.expectedTenantId);
if (lockedAssessment.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: fixture ownership changed after guarded preflight");
}
if (lockedAssessment.action === "noop") return;
const expectedProject = projectById(lockedSnapshot, CUSTOMER_PORTAL_UAT_PROJECT_ID);
const forbiddenProject = projectById(lockedSnapshot, CUSTOMER_PORTAL_UAT_FORBIDDEN_PROJECT_ID);
if (!expectedProject?.projekttyp || !forbiddenProject?.projekttyp) {
throw new CustomerPortalUatError("customer-portal UAT: deterministic projects changed after guarded preflight");
}
const [customerPasswordHash, subcontractorPasswordHash] = await Promise.all([
passwordHashForUser(lockedSnapshot, CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL, command.password),
passwordHashForUser(lockedSnapshot, CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL, command.password),
]);
const projectTypes = [...new Set([expectedProject.projekttyp, forbiddenProject.projekttyp])];
const portal = await tx.portal.upsert({
where: { tenantId: command.expectedTenantId },
create: {
id: "customer-portal-uat-demo-pro-crm",
tenantId: command.expectedTenantId,
subdomain: CUSTOMER_PORTAL_UAT_TENANT_SLUG,
title: UAT_PORTAL_TITLE,
isPublished: true,
authRequireEmailVerification: false,
authRequireOrganization: false,
authRequireName: true,
metadata: { uatFixture: "VA-P26" },
},
update: {
subdomain: CUSTOMER_PORTAL_UAT_TENANT_SLUG,
title: UAT_PORTAL_TITLE,
isPublished: true,
authRequireEmailVerification: false,
authRequireOrganization: false,
authRequireName: true,
},
select: { id: true },
});
await tx.portalConfiguration.upsert({
where: { portalId_tenantId: { portalId: portal.id, tenantId: command.expectedTenantId } },
create: {
id: "customer-portal-uat-configuration",
tenantId: command.expectedTenantId,
portalId: portal.id,
lifecycleMode: "customer",
enabledProjectTypes: projectTypes,
uploadMaxFiles: 10,
uploadMaxFileSizeBytes: 52_428_800,
statusEmailsEnabled: true,
welcomeMessage: "Willkommen im HiveGrid Test-Kundenportal.",
supportEmail: "support@saas-ctrl.com",
imprintUrl: `${UAT_LEGAL_ORIGIN}/impressum`,
privacyUrl: `${UAT_LEGAL_ORIGIN}/datenschutz`,
isDemoData: true,
},
update: {
lifecycleMode: "customer",
enabledProjectTypes: projectTypes,
uploadMaxFiles: 10,
uploadMaxFileSizeBytes: 52_428_800,
statusEmailsEnabled: true,
welcomeMessage: "Willkommen im HiveGrid Test-Kundenportal.",
supportEmail: "support@saas-ctrl.com",
imprintUrl: `${UAT_LEGAL_ORIGIN}/impressum`,
privacyUrl: `${UAT_LEGAL_ORIGIN}/datenschutz`,
isDemoData: true,
},
});
const customer = await tx.portalUser.upsert({
where: { portalId_emailNormalized: { portalId: portal.id, emailNormalized: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL } },
create: {
id: "customer-portal-uat-customer",
tenantId: command.expectedTenantId,
portalId: portal.id,
email: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
emailNormalized: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
passwordHash: customerPasswordHash,
firstName: "Karla",
lastName: "Kundin",
kind: "customer",
status: "active",
locale: "de",
emailVerifiedAt: UAT_VERIFIED_AT,
isDemoData: true,
},
update: {
email: CUSTOMER_PORTAL_UAT_CUSTOMER_EMAIL,
passwordHash: customerPasswordHash,
firstName: "Karla",
lastName: "Kundin",
kind: "customer",
status: "active",
locale: "de",
emailVerifiedAt: UAT_VERIFIED_AT,
archivedAt: null,
isDemoData: true,
},
select: { id: true },
});
const subcontractor = await tx.portalUser.upsert({
where: { portalId_emailNormalized: { portalId: portal.id, emailNormalized: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL } },
create: {
id: "customer-portal-uat-subcontractor",
tenantId: command.expectedTenantId,
portalId: portal.id,
email: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
emailNormalized: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
passwordHash: subcontractorPasswordHash,
firstName: "Sascha",
lastName: "Subunternehmer",
kind: "subcontractor",
status: "active",
locale: "de",
emailVerifiedAt: UAT_VERIFIED_AT,
isDemoData: true,
},
update: {
email: CUSTOMER_PORTAL_UAT_SUBCONTRACTOR_EMAIL,
passwordHash: subcontractorPasswordHash,
firstName: "Sascha",
lastName: "Subunternehmer",
kind: "subcontractor",
status: "active",
locale: "de",
emailVerifiedAt: UAT_VERIFIED_AT,
archivedAt: null,
isDemoData: true,
},
select: { id: true },
});
await tx.portalProjectAccess.updateMany({
where: {
tenantId: command.expectedTenantId,
portalId: portal.id,
portalUserId: { in: [customer.id, subcontractor.id] },
projectId: { not: CUSTOMER_PORTAL_UAT_PROJECT_ID },
isDemoData: true,
active: true,
},
data: { active: false, revokedAt: now },
});
await tx.portalProjectAccess.upsert({
where: { portalId_portalUserId_projectId: { portalId: portal.id, portalUserId: customer.id, projectId: expectedProject.id } },
create: {
id: "customer-portal-uat-customer-access",
tenantId: command.expectedTenantId,
portalId: portal.id,
portalUserId: customer.id,
projectId: expectedProject.id,
active: true,
statusEmailsEnabled: true,
isDemoData: true,
},
update: { active: true, revokedAt: null, statusEmailsEnabled: true, isDemoData: true },
select: { id: true },
});
const subcontractorAccess = await tx.portalProjectAccess.upsert({
where: {
portalId_portalUserId_projectId: { portalId: portal.id, portalUserId: subcontractor.id, projectId: expectedProject.id },
},
create: {
id: "customer-portal-uat-subcontractor-access",
tenantId: command.expectedTenantId,
portalId: portal.id,
portalUserId: subcontractor.id,
projectId: expectedProject.id,
active: true,
statusEmailsEnabled: false,
isDemoData: true,
},
update: { active: true, revokedAt: null, statusEmailsEnabled: false, isDemoData: true },
select: { id: true },
});
await tx.portalSubcontractorAccess.upsert({
where: {
portalId_portalUserId_projectId: { portalId: portal.id, portalUserId: subcontractor.id, projectId: expectedProject.id },
},
create: {
id: "customer-portal-uat-subcontractor-scope",
tenantId: command.expectedTenantId,
portalId: portal.id,
portalUserId: subcontractor.id,
projectId: expectedProject.id,
projectAccessId: subcontractorAccess.id,
companyName: "HiveGrid UAT Subunternehmer",
roleLabel: "Montagepartner",
visibleStageIds: [expectedProject.stageId],
visibleDocumentTypes: [],
canSeeOtherSubcontractors: false,
canUpload: true,
active: true,
isDemoData: true,
},
update: {
projectAccessId: subcontractorAccess.id,
companyName: "HiveGrid UAT Subunternehmer",
roleLabel: "Montagepartner",
visibleStageIds: [expectedProject.stageId],
visibleDocumentTypes: [],
canSeeOtherSubcontractors: false,
canUpload: true,
active: true,
revokedAt: null,
isDemoData: true,
},
});
for (const project of [expectedProject, forbiddenProject]) {
await tx.portalStageVisibility.upsert({
where: { portalId_stageId: { portalId: portal.id, stageId: project.stageId } },
create: {
tenantId: command.expectedTenantId,
portalId: portal.id,
stageId: project.stageId,
visible: true,
customerLabel: project.stage.name,
isDemoData: true,
},
update: { visible: true, customerLabel: project.stage.name, isDemoData: true },
});
}
await tx.form.upsert({
where: { tenantId_slug: { tenantId: command.expectedTenantId, slug: UAT_FORM_SLUG } },
create: {
id: "customer-portal-uat-complaint-form",
key: UAT_FORM_KEY,
tenantId: command.expectedTenantId,
slug: UAT_FORM_SLUG,
name: UAT_FORM_NAME,
subtype: "portal_form",
status: "published",
publishedAt: now,
isPublic: true,
isDemoData: true,
definition: customerPortalUatComplaintDefinition as unknown as Prisma.InputJsonValue,
targetType: "project",
targetEntityId: expectedProject.id,
allowedOrigins: [CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN],
notifyEmails: [],
config: { honeypotEnabled: false },
isEnabled: true,
},
update: {
key: UAT_FORM_KEY,
name: UAT_FORM_NAME,
subtype: "portal_form",
status: "published",
publishedAt: now,
isPublic: true,
isDemoData: true,
definition: customerPortalUatComplaintDefinition as unknown as Prisma.InputJsonValue,
targetType: "project",
targetEntityId: expectedProject.id,
allowedOrigins: [CUSTOMER_PORTAL_UAT_STANDARD_ORIGIN],
notifyEmails: [],
config: { honeypotEnabled: false },
isEnabled: true,
},
});
await tx.portalServiceInboxItem.upsert({
where: { tenantId_sourceKey: { tenantId: command.expectedTenantId, sourceKey: UAT_INBOX_SOURCE_KEY } },
create: {
id: "customer-portal-uat-inbox-item",
tenantId: command.expectedTenantId,
portalId: portal.id,
portalUserId: customer.id,
projectId: expectedProject.id,
kind: "complaint",
status: "open",
priority: 100,
sourceKey: UAT_INBOX_SOURCE_KEY,
sourceId: UAT_INBOX_SOURCE_ID,
titleKey: UAT_INBOX_TITLE_KEY,
metadata: { fixture: "VA-P26" },
occurredAt: now,
lastOccurredAt: now,
bundledCount: 1,
expiresAt: inboxExpiry,
isDemoData: true,
},
update: {
portalId: portal.id,
portalUserId: customer.id,
projectId: expectedProject.id,
kind: "complaint",
status: "open",
priority: 100,
sourceId: UAT_INBOX_SOURCE_ID,
titleKey: UAT_INBOX_TITLE_KEY,
metadata: { fixture: "VA-P26" },
occurredAt: now,
lastOccurredAt: now,
bundledCount: 1,
expiresAt: inboxExpiry,
ownerUserId: null,
resolvedAt: null,
isDemoData: true,
},
});
await publishAuditEventViaOutbox(tx, {
tenantId: command.expectedTenantId,
actorId: command.operatorUserId,
actorType: "operator",
action: "customer_portal.uat_fixture.provisioned",
targetType: "Portal",
targetId: portal.id,
sourceModule: "customer-portal-uat",
outcome: "success",
dataSensitivity: "internal",
regulatoryScope: ["none"],
metadata: { tenantSlug: CUSTOMER_PORTAL_UAT_TENANT_SLUG, projectCount: 2, portalUserCount: 2 },
});
});
}
@@ -0,0 +1,637 @@
#!/usr/bin/env python3
"""Short-lived loopback adapter for VA-P26a delivered-mail UAT evidence."""
from __future__ import annotations
import hashlib
import imaplib
import json
import re
import ssl
import sys
import threading
from dataclasses import dataclass
from datetime import datetime, timedelta, timezone
from email import policy
from email.message import Message
from email.parser import BytesParser
from email.utils import getaddresses, parsedate_to_datetime
from html.parser import HTMLParser
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from typing import Mapping, Sequence
from urllib.parse import quote, urlsplit
UTC = timezone.utc
LOOPBACK_HOST = "127.0.0.1"
DEFAULT_PORT = 4010
DEFAULT_IMAP_PORT = 993
DEFAULT_MAILBOX = "INBOX"
DEFAULT_PRODUCT_NAME = "Demo Pro CRM Kundenportal"
MAX_REQUEST_BYTES = 8 * 1024
MAX_MESSAGE_BYTES = 1024 * 1024
MAX_CANDIDATE_MESSAGES = 50
MAX_MAILBOX_ADDRESS_BYTES = 254
MAX_LOCAL_PART_BYTES = 64
MAX_DOMAIN_BYTES = 253
DELIVERY_TOLERANCE = timedelta(seconds=5)
MAX_BOUNDARY_AGE = timedelta(minutes=30)
MAX_CLOCK_SKEW = timedelta(seconds=30)
SETUP_TOKEN_PATTERN = re.compile(r"^[A-Za-z0-9_-]{43}$")
CORRELATION_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{0,95}$")
TENANT_SLUG_PATTERN = re.compile(r"^[a-z0-9][a-z0-9-]{0,62}$")
HOST_PATTERN = re.compile(r"^[A-Za-z0-9.-]{1,253}$")
LOCAL_PART_PATTERN = re.compile(r"^[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*+/=?^_`{|}~-]+)*$")
DOMAIN_LABEL_PATTERN = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$")
INTERNAL_DATE_PATTERN = re.compile(rb'INTERNALDATE "([^"]+)"')
MESSAGE_SIZE_PATTERN = re.compile(rb"RFC822\.SIZE (\d+)")
URL_PATTERN = re.compile(r"""https?://[^\s<>"')\]}]+""")
RAW_HREF_PATTERN = re.compile(r'''\shref\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))''', re.IGNORECASE)
SOURCE_PREFIXES = {
"portal_admin_invite": "p26a-admin-",
"portal_contact_invite": "p26a-contact-",
"portal_project_invite": "p26a-project-",
}
class ContractError(ValueError):
"""The local HTTP request does not match the bounded UAT contract."""
class ConfigurationError(ValueError):
"""The operator-only adapter configuration is incomplete or unsafe."""
class MailboxUnavailable(RuntimeError):
"""The mailbox could not be read without exposing provider details."""
class AnchorHrefParser(HTMLParser):
"""Collects literal anchor hrefs without resolving or fetching them."""
def __init__(self) -> None:
super().__init__(convert_charrefs=False)
self.hrefs: list[str] = []
def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
if tag.lower() != "a":
return
hrefs = [value for name, value in attrs if name.lower() == "href" and value is not None]
raw_hrefs = [next(value for value in match.groups() if value is not None) for match in RAW_HREF_PATTERN.finditer(self.get_starttag_text() or "")]
if len(hrefs) == 1 and raw_hrefs == hrefs:
self.hrefs.append(hrefs[0])
@dataclass(frozen=True)
class AdapterConfig:
imap_host: str
imap_port: int
mailbox: str
mailbox_email: str
mailbox_password: str
portal_origin: str
custom_portal_origin: str | None
tenant_slug: str
expected_subjects: frozenset[str]
listen_port: int
@dataclass(frozen=True)
class MailQuery:
correlation_key: str
recipient: str
source: str
purpose: str
delivered_after: datetime
@dataclass(frozen=True)
class DeliveredMail:
delivered_at: datetime
setup_url: str
def load_config(env: Mapping[str, str]) -> AdapterConfig:
imap_host = require_env(env, "PORTAL_SETUP_MAIL_IMAP_HOST").strip()
if not HOST_PATTERN.fullmatch(imap_host) or ".." in imap_host or imap_host.startswith((".", "-")):
raise ConfigurationError("PORTAL_SETUP_MAIL_IMAP_HOST is invalid.")
imap_port = parse_port(env.get("PORTAL_SETUP_MAIL_IMAP_PORT", str(DEFAULT_IMAP_PORT)), "PORTAL_SETUP_MAIL_IMAP_PORT")
listen_port = parse_port(env.get("PORTAL_SETUP_MAIL_ADAPTER_PORT", str(DEFAULT_PORT)), "PORTAL_SETUP_MAIL_ADAPTER_PORT")
mailbox = env.get("PORTAL_SETUP_MAIL_IMAP_FOLDER", DEFAULT_MAILBOX).strip()
if not mailbox or len(mailbox) > 128 or any(character in mailbox for character in "\r\n\0"):
raise ConfigurationError("PORTAL_SETUP_MAIL_IMAP_FOLDER is invalid.")
portal_origin = normalize_portal_origin(require_env(env, "E2E_PORTAL_BASE_URL"), "E2E_PORTAL_BASE_URL")
custom_portal_origin_raw = env.get("E2E_PORTAL_CUSTOM_DOMAIN_BASE_URL", "").strip()
custom_portal_origin = (
normalize_portal_origin(custom_portal_origin_raw, "E2E_PORTAL_CUSTOM_DOMAIN_BASE_URL")
if custom_portal_origin_raw
else None
)
tenant_slug = require_env(env, "E2E_PORTAL_TENANT_SLUG").strip()
if not TENANT_SLUG_PATTERN.fullmatch(tenant_slug):
raise ConfigurationError("E2E_PORTAL_TENANT_SLUG is invalid.")
product_name = env.get("PORTAL_SETUP_MAIL_EXPECTED_PRODUCT_NAME", DEFAULT_PRODUCT_NAME).strip()
if not product_name or len(product_name) > 120 or any(character in product_name for character in "\r\n\0"):
raise ConfigurationError("PORTAL_SETUP_MAIL_EXPECTED_PRODUCT_NAME is invalid.")
mailbox_email = require_env(env, "MAILBOX_EMAIL")
parse_mailbox_base(mailbox_email)
return AdapterConfig(
imap_host=imap_host,
imap_port=imap_port,
mailbox=mailbox,
mailbox_email=mailbox_email,
mailbox_password=require_env(env, "MAILBOX_APP_PASSWORD"),
portal_origin=portal_origin,
custom_portal_origin=custom_portal_origin,
tenant_slug=tenant_slug,
expected_subjects=frozenset(
{
f"Richte deinen Zugang zu {product_name} ein",
f"Set up your access to {product_name}",
}
),
listen_port=listen_port,
)
def parse_mail_query(payload: object, mailbox_email: str, now: datetime | None = None) -> MailQuery:
if not isinstance(payload, dict) or set(payload) != {"correlationKey", "recipient", "source", "purpose", "deliveredAfter"}:
raise ContractError("The setup-mail request shape is invalid.")
correlation_key = require_contract_string(payload, "correlationKey")
recipient = require_contract_string(payload, "recipient").lower()
source = require_contract_string(payload, "source")
purpose = require_contract_string(payload, "purpose")
delivered_after_raw = require_contract_string(payload, "deliveredAfter")
expected_prefix = SOURCE_PREFIXES.get(source)
if not expected_prefix or not CORRELATION_PATTERN.fullmatch(correlation_key) or not correlation_key.startswith(expected_prefix):
raise ContractError("The invitation correlation contract is invalid.")
expected_recipient = invitation_recipient(mailbox_email, correlation_key)
if recipient != expected_recipient:
raise ContractError("The invitation recipient contract is invalid.")
if purpose != "setup":
raise ContractError("The invitation purpose is invalid.")
delivered_after = parse_utc_timestamp(delivered_after_raw)
current_time = (now or datetime.now(UTC)).astimezone(UTC)
if delivered_after < current_time - MAX_BOUNDARY_AGE or delivered_after > current_time + MAX_CLOCK_SKEW:
raise ContractError("The delivery boundary is outside the allowed UAT window.")
return MailQuery(
correlation_key=correlation_key,
recipient=recipient,
source=source,
purpose=purpose,
delivered_after=delivered_after,
)
def find_delivered_mail(config: AdapterConfig, query: MailQuery) -> DeliveredMail | None:
client: imaplib.IMAP4_SSL | None = None
try:
client = imaplib.IMAP4_SSL(
config.imap_host,
config.imap_port,
ssl_context=ssl.create_default_context(),
timeout=5,
)
client.login(config.mailbox_email, config.mailbox_password)
status, _ = client.select(config.mailbox, readonly=True)
if status != "OK":
raise MailboxUnavailable("Mailbox selection failed.")
since = (query.delivered_after - DELIVERY_TOLERANCE).strftime("%d-%b-%Y")
status, search_data = client.uid("search", None, "SINCE", since)
if status != "OK" or not search_data:
raise MailboxUnavailable("Mailbox search failed.")
uids = search_data[0].split()[-MAX_CANDIDATE_MESSAGES:]
matches: list[DeliveredMail] = []
for uid in reversed(uids):
status, fetch_data = client.uid(
"fetch",
uid,
f"(INTERNALDATE RFC822.SIZE BODY.PEEK[]<0.{MAX_MESSAGE_BYTES + 1}>)",
)
if status != "OK":
continue
metadata, raw_message = extract_fetch_result(fetch_data)
if metadata is None or raw_message is None:
continue
message_size = parse_message_size(metadata)
delivered_at = parse_internal_date(metadata)
if message_size is None or message_size > MAX_MESSAGE_BYTES or len(raw_message) > MAX_MESSAGE_BYTES or delivered_at is None:
continue
match = match_delivered_message(config, query, raw_message, delivered_at)
if match:
matches.append(match)
return max(matches, key=lambda match: match.delivered_at) if matches else None
except MailboxUnavailable:
raise
except (imaplib.IMAP4.error, OSError, ssl.SSLError, ValueError):
raise MailboxUnavailable("Mailbox lookup failed.") from None
finally:
if client is not None:
try:
client.logout()
except (imaplib.IMAP4.error, OSError, ssl.SSLError):
pass
def match_delivered_message(
config: AdapterConfig,
query: MailQuery,
raw_message: bytes,
delivered_at: datetime,
now: datetime | None = None,
) -> DeliveredMail | None:
normalized_delivery = delivered_at.astimezone(UTC)
if normalized_delivery + DELIVERY_TOLERANCE < query.delivered_after:
return None
if normalized_delivery > (now or datetime.now(UTC)).astimezone(UTC) + timedelta(minutes=5):
return None
try:
message = BytesParser(policy=policy.default).parsebytes(raw_message)
except (TypeError, ValueError):
return None
if query.recipient not in message_recipients(message):
return None
if str(message.get("Subject", "")).strip() not in config.expected_subjects:
return None
plain_parts = plain_text_parts(message)
html_bodies = html_parts(message)
if not plain_parts or not html_bodies:
return None
plain_setup_urls = {
url
for text in plain_parts
for candidate in URL_PATTERN.findall(text)
if (
url := normalize_setup_url(
candidate,
config.portal_origin,
config.tenant_slug,
config.custom_portal_origin,
)
)
is not None
}
html_setup_urls = {
url
for html_body in html_bodies
for candidate in anchor_hrefs(html_body)
if (
url := normalize_setup_url(
candidate,
config.portal_origin,
config.tenant_slug,
config.custom_portal_origin,
)
)
is not None
}
if len(plain_setup_urls) != 1 or html_setup_urls != plain_setup_urls:
return None
return DeliveredMail(delivered_at=normalized_delivery, setup_url=next(iter(plain_setup_urls)))
def make_handler(config: AdapterConfig):
consumed: set[str] = set()
consumed_lock = threading.Lock()
class SetupMailHandler(BaseHTTPRequestHandler):
server_version = "HiveGridPortalSetupMailAdapter"
sys_version = ""
def do_POST(self) -> None: # noqa: N802 - BaseHTTPRequestHandler API
if urlsplit(self.path).path != "/setup-mail" or urlsplit(self.path).query:
self.send_empty(404)
return
if "Authorization" in self.headers:
self.send_empty(401)
return
if self.headers.get("Transfer-Encoding"):
self.send_empty(400)
return
raw_length = self.headers.get("Content-Length")
if not raw_length:
self.send_empty(411)
return
try:
content_length = int(raw_length)
except ValueError:
self.send_empty(400)
return
if content_length < 2 or content_length > MAX_REQUEST_BYTES:
self.send_empty(413)
return
if self.headers.get_content_type() != "application/json":
self.send_empty(415)
return
try:
payload = json.loads(self.rfile.read(content_length))
query = parse_mail_query(payload, config.mailbox_email)
except (ContractError, UnicodeDecodeError, json.JSONDecodeError):
self.send_empty(400)
return
identity = query_identity(query)
with consumed_lock:
if identity in consumed:
self.send_empty(410)
return
try:
delivery = find_delivered_mail(config, query)
except MailboxUnavailable:
self.send_empty(503)
return
if delivery is None:
self.send_empty(202)
return
with consumed_lock:
if identity in consumed:
self.send_empty(410)
return
consumed.add(identity)
self.send_json(
200,
{
"correlationKey": query.correlation_key,
"recipient": query.recipient,
"source": query.source,
"purpose": query.purpose,
"deliveredAt": format_utc_timestamp(delivery.delivered_at),
"setupUrl": delivery.setup_url,
},
)
def do_GET(self) -> None: # noqa: N802 - BaseHTTPRequestHandler API
self.send_empty(405)
def do_HEAD(self) -> None: # noqa: N802 - BaseHTTPRequestHandler API
self.send_empty(405)
def send_empty(self, status: int) -> None:
self.send_response(status)
self.send_header("Cache-Control", "no-store")
self.send_header("Content-Length", "0")
self.send_header("X-Content-Type-Options", "nosniff")
self.end_headers()
def send_json(self, status: int, payload: Mapping[str, str]) -> None:
body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
self.send_response(status)
self.send_header("Cache-Control", "no-store")
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.send_header("X-Content-Type-Options", "nosniff")
self.end_headers()
self.wfile.write(body)
def log_message(self, _format: str, *args: object) -> None:
# The default HTTP access log includes request paths and client data.
# This local proof adapter intentionally emits no per-request logs.
del args
return SetupMailHandler
def serve(config: AdapterConfig) -> None:
class AdapterServer(ThreadingHTTPServer):
daemon_threads = True
def handle_error(self, _request: object, _client_address: object) -> None:
# socketserver otherwise prints tracebacks and client data. This
# single-purpose adapter remains silent even on disconnects.
return
server = AdapterServer((LOOPBACK_HOST, config.listen_port), make_handler(config))
try:
server.serve_forever(poll_interval=0.25)
finally:
server.server_close()
def message_recipients(message: Message) -> frozenset[str]:
header_values: list[str] = []
for header in ("To", "Delivered-To", "X-Original-To", "Envelope-To"):
header_values.extend(str(value) for value in message.get_all(header, []))
return frozenset(address.strip().lower() for _, address in getaddresses(header_values) if address.strip())
def plain_text_parts(message: Message) -> Sequence[str]:
parts = message.walk() if message.is_multipart() else (message,)
texts: list[str] = []
for part in parts:
if part.get_content_type() != "text/plain" or part.get_content_disposition() == "attachment":
continue
try:
content = part.get_content()
except (LookupError, TypeError, UnicodeDecodeError, ValueError):
continue
if isinstance(content, str):
texts.append(content)
return texts
def html_parts(message: Message) -> Sequence[str]:
parts = message.walk() if message.is_multipart() else (message,)
bodies: list[str] = []
for part in parts:
if part.get_content_type() != "text/html" or part.get_content_disposition() == "attachment":
continue
try:
content = part.get_content()
except (LookupError, TypeError, UnicodeDecodeError, ValueError):
continue
if isinstance(content, str):
bodies.append(content)
return bodies
def anchor_hrefs(html_body: str) -> Sequence[str]:
parser = AnchorHrefParser()
try:
parser.feed(html_body)
parser.close()
except (AssertionError, ValueError):
return ()
return parser.hrefs
def normalize_setup_url(
candidate: str,
expected_origin: str,
tenant_slug: str,
expected_custom_origin: str | None = None,
) -> str | None:
trimmed = candidate.rstrip(".,;:!?)]}")
try:
parsed = urlsplit(trimmed)
except ValueError:
return None
expected = urlsplit(expected_origin)
if (
parsed.username
or parsed.password
or parsed.query
or parsed.fragment
):
return None
candidate_origin = f"{parsed.scheme}://{parsed.netloc}"
if candidate_origin == f"{expected.scheme}://{expected.netloc}":
expected_prefix = f"/{quote(tenant_slug, safe='')}/setup/"
elif expected_custom_origin and candidate_origin == expected_custom_origin:
expected_prefix = "/setup/"
else:
return None
if not parsed.path.startswith(expected_prefix):
return None
token = parsed.path[len(expected_prefix) :]
if not SETUP_TOKEN_PATTERN.fullmatch(token):
return None
return trimmed
def extract_fetch_result(fetch_data: Sequence[object]) -> tuple[bytes | None, bytes | None]:
for item in fetch_data:
if isinstance(item, tuple) and len(item) >= 2 and isinstance(item[0], bytes) and isinstance(item[1], bytes):
return item[0], item[1]
return None, None
def parse_message_size(metadata: bytes) -> int | None:
match = MESSAGE_SIZE_PATTERN.search(metadata)
return int(match.group(1)) if match else None
def parse_internal_date(metadata: bytes) -> datetime | None:
match = INTERNAL_DATE_PATTERN.search(metadata)
if not match:
return None
try:
parsed = parsedate_to_datetime(match.group(1).decode("ascii"))
except (UnicodeDecodeError, TypeError, ValueError):
return None
return parsed.astimezone(UTC) if parsed.tzinfo else None
def query_identity(query: MailQuery) -> str:
encoded = "\0".join([query.correlation_key, query.recipient, query.source, query.purpose]).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def parse_utc_timestamp(value: str) -> datetime:
if not value.endswith("Z"):
raise ContractError("deliveredAfter must be an ISO-8601 UTC timestamp.")
try:
parsed = datetime.fromisoformat(f"{value[:-1]}+00:00")
except ValueError:
raise ContractError("deliveredAfter must be an ISO-8601 UTC timestamp.") from None
if parsed.tzinfo is None:
raise ContractError("deliveredAfter must be an ISO-8601 UTC timestamp.")
return parsed.astimezone(UTC)
def format_utc_timestamp(value: datetime) -> str:
return value.astimezone(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
def normalize_portal_origin(value: str, input_name: str) -> str:
try:
parsed = urlsplit(value.strip())
except ValueError:
raise ConfigurationError(f"{input_name} is invalid.") from None
if parsed.scheme != "https" or not parsed.netloc or parsed.username or parsed.password or parsed.path not in ("", "/") or parsed.query or parsed.fragment:
raise ConfigurationError(f"{input_name} must be an exact HTTPS root origin.")
return f"{parsed.scheme}://{parsed.netloc}"
def parse_mailbox_base(value: str) -> tuple[str, str]:
if value != value.strip() or any(character in value for character in "\r\n\0"):
raise ConfigurationError("MAILBOX_EMAIL is invalid.")
try:
encoded = value.encode("ascii")
except UnicodeEncodeError:
raise ConfigurationError("MAILBOX_EMAIL is invalid.") from None
if len(encoded) > MAX_MAILBOX_ADDRESS_BYTES or value.count("@") != 1:
raise ConfigurationError("MAILBOX_EMAIL is invalid.")
local_part, domain = value.rsplit("@", 1)
if "+" in local_part or not LOCAL_PART_PATTERN.fullmatch(local_part) or len(local_part.encode("ascii")) > MAX_LOCAL_PART_BYTES:
raise ConfigurationError("MAILBOX_EMAIL is invalid.")
if len(domain.encode("ascii")) > MAX_DOMAIN_BYTES:
raise ConfigurationError("MAILBOX_EMAIL is invalid.")
labels = domain.split(".")
if len(labels) < 2 or any(len(label.encode("ascii")) > 63 or not DOMAIN_LABEL_PATTERN.fullmatch(label) for label in labels):
raise ConfigurationError("MAILBOX_EMAIL is invalid.")
return local_part.lower(), domain.lower()
def invitation_recipient(mailbox_email: str, correlation_key: str) -> str:
local_part, domain = parse_mailbox_base(mailbox_email)
derived_local_part = f"{local_part}+{correlation_key}"
recipient = f"{derived_local_part}@{domain}"
if len(derived_local_part.encode("ascii")) > MAX_LOCAL_PART_BYTES or len(recipient.encode("ascii")) > MAX_MAILBOX_ADDRESS_BYTES:
raise ContractError("The invitation recipient contract is invalid.")
return recipient
def require_env(env: Mapping[str, str], key: str) -> str:
value = env.get(key)
if value is None or not value.strip():
raise ConfigurationError(f"{key} is required.")
return value
def require_contract_string(payload: Mapping[str, object], key: str) -> str:
value = payload.get(key)
if not isinstance(value, str) or not value or value.strip() != value or len(value) > 256 or any(character in value for character in "\r\n\0"):
raise ContractError(f"{key} is invalid.")
return value
def parse_port(value: str, key: str) -> int:
try:
parsed = int(value)
except ValueError:
raise ConfigurationError(f"{key} is invalid.") from None
if parsed < 1 or parsed > 65535:
raise ConfigurationError(f"{key} is invalid.")
return parsed
def main() -> int:
import os
try:
config = load_config(os.environ)
serve(config)
return 0
except ConfigurationError as error:
sys.stderr.write(f"{error}\n")
return 2
except KeyboardInterrupt:
return 0
except OSError:
sys.stderr.write("Portal setup mail adapter could not bind its loopback listener.\n")
return 1
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,367 @@
from __future__ import annotations
import json
import unittest
from dataclasses import replace
from datetime import datetime, timedelta, timezone
from email.message import EmailMessage
from http.client import HTTPConnection
from http.server import ThreadingHTTPServer
from threading import Thread
from unittest.mock import patch
from urllib.parse import quote
from portal_setup_mail_adapter import (
AdapterConfig,
ConfigurationError,
ContractError,
DeliveredMail,
load_config,
make_handler,
match_delivered_message,
normalize_setup_url,
parse_mail_query,
)
UTC = timezone.utc
NOW = datetime(2026, 7, 19, 12, 0, tzinfo=UTC)
TOKEN = "s" * 43
MAILBOX_EMAIL = "fixture@example.test"
def config() -> AdapterConfig:
return AdapterConfig(
imap_host="imap.example.test",
imap_port=993,
mailbox="INBOX",
mailbox_email=MAILBOX_EMAIL,
mailbox_password="not-used-by-unit-tests",
portal_origin="https://staging-portal.hivegrid.de",
custom_portal_origin=None,
tenant_slug="demo-pro-crm",
expected_subjects=frozenset(
{
"Richte deinen Zugang zu Demo Pro CRM Kundenportal ein",
"Set up your access to Demo Pro CRM Kundenportal",
}
),
listen_port=4010,
)
def payload(entrypoint: str = "contact") -> dict[str, str]:
source = f"portal_{entrypoint}_invite"
key = f"p26a-{entrypoint}-20260719t120000z-123"
return {
"correlationKey": key,
"recipient": f"fixture+{key}@example.test",
"source": source,
"purpose": "setup",
"deliveredAfter": NOW.isoformat(timespec="milliseconds").replace("+00:00", "Z"),
}
def message(
recipient: str,
url: str,
subject: str = "Richte deinen Zugang zu Demo Pro CRM Kundenportal ein",
html_url: str | None = None,
plain_suffix: str = "",
) -> bytes:
mail = EmailMessage()
mail["To"] = recipient
mail["From"] = "HiveGrid <noreply@hivegrid.de>"
mail["Subject"] = subject
mail.set_content(f"Zugang einrichten ({url}){plain_suffix}")
mail.add_alternative(f'<p><a href="{html_url or url}">Zugang einrichten</a></p>', subtype="html")
return mail.as_bytes()
class PortalSetupMailAdapterTest(unittest.TestCase):
def test_parses_a_fresh_source_bound_synthetic_recipient(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
self.assertEqual(query.source, "portal_contact_invite")
self.assertEqual(query.correlation_key, "p26a-contact-20260719t120000z-123")
def test_rejects_source_prefix_and_recipient_mismatches(self) -> None:
wrong_source = payload()
wrong_source["source"] = "portal_admin_invite"
with self.assertRaises(ContractError):
parse_mail_query(wrong_source, MAILBOX_EMAIL, now=NOW)
wrong_recipient = payload()
wrong_recipient["recipient"] = "fixture+other@example.test"
with self.assertRaises(ContractError):
parse_mail_query(wrong_recipient, MAILBOX_EMAIL, now=NOW)
wrong_domain = payload()
wrong_domain["recipient"] = f"fixture+{wrong_domain['correlationKey']}@elsewhere.test"
with self.assertRaises(ContractError):
parse_mail_query(wrong_domain, MAILBOX_EMAIL, now=NOW)
def test_matches_exact_recipient_subject_freshness_and_standard_setup_url(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
setup_url = f"https://staging-portal.hivegrid.de/demo-pro-crm/setup/{TOKEN}"
delivery = match_delivered_message(config(), query, message(query.recipient, setup_url), NOW + timedelta(seconds=2), now=NOW)
self.assertIsNotNone(delivery)
self.assertEqual(delivery.setup_url if delivery else None, setup_url)
def test_matches_only_an_explicitly_configured_custom_origin_root_setup_url(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
custom_origin = "https://portal.customer.example.test"
setup_url = f"{custom_origin}/setup/{TOKEN}"
custom_config = replace(config(), custom_portal_origin=custom_origin)
delivery = match_delivered_message(custom_config, query, message(query.recipient, setup_url), NOW, now=NOW)
self.assertIsNotNone(delivery)
self.assertEqual(delivery.setup_url if delivery else None, setup_url)
self.assertIsNone(match_delivered_message(config(), query, message(query.recipient, setup_url), NOW, now=NOW))
self.assertIsNone(
match_delivered_message(
custom_config,
query,
message(query.recipient, f"{custom_origin}/demo-pro-crm/setup/{TOKEN}"),
NOW,
now=NOW,
)
)
def test_matches_exact_plain_cta_when_receiving_mta_joins_the_following_paragraph(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
custom_origin = "https://portal.customer.example.test"
setup_url = f"{custom_origin}/setup/{TOKEN}"
custom_config = replace(config(), custom_portal_origin=custom_origin)
delivery = match_delivered_message(
custom_config,
query,
message(
query.recipient,
setup_url,
plain_suffix="Dieser Link ist sieben Tage gültig.",
),
NOW,
now=NOW,
)
self.assertIsNotNone(delivery)
self.assertEqual(delivery.setup_url if delivery else None, setup_url)
def test_joined_plain_cta_still_rejects_query_path_and_token_mismatches(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
custom_origin = "https://portal.customer.example.test"
setup_url = f"{custom_origin}/setup/{TOKEN}"
custom_config = replace(config(), custom_portal_origin=custom_origin)
for plain_url in (
f"{setup_url}?next=1",
f"{setup_url}#fragment",
f"{setup_url}/extra",
f"{custom_origin}/setup/{'x' * 43}",
):
with self.subTest(plain_url=plain_url):
self.assertIsNone(
match_delivered_message(
custom_config,
query,
message(
query.recipient,
plain_url,
html_url=setup_url,
plain_suffix="Dieser Link ist sieben Tage gültig.",
),
NOW,
now=NOW,
)
)
def test_rejects_stale_wrong_subject_and_nonstandard_setup_links(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
setup_url = f"https://staging-portal.hivegrid.de/demo-pro-crm/setup/{TOKEN}"
self.assertIsNone(match_delivered_message(config(), query, message(query.recipient, setup_url), NOW - timedelta(seconds=6), now=NOW))
self.assertIsNone(match_delivered_message(config(), query, message(query.recipient, setup_url, "Unrelated mail"), NOW, now=NOW))
self.assertIsNone(
match_delivered_message(
config(),
query,
message(query.recipient, f"https://evil.example.test/demo-pro-crm/setup/{TOKEN}"),
NOW,
now=NOW,
)
)
def test_setup_url_contract_rejects_queries_fragments_and_invalid_tokens(self) -> None:
origin = "https://staging-portal.hivegrid.de"
base = f"{origin}/demo-pro-crm/setup/{TOKEN}"
self.assertEqual(normalize_setup_url(base, origin, "demo-pro-crm"), base)
self.assertIsNone(normalize_setup_url(f"{base}?next=1", origin, "demo-pro-crm"))
self.assertIsNone(normalize_setup_url(f"{base}#fragment", origin, "demo-pro-crm"))
self.assertIsNone(normalize_setup_url(f"{origin}/demo-pro-crm/setup/short", origin, "demo-pro-crm"))
def test_tracking_wrappers_remain_fail_closed(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
setup_url = f"https://staging-portal.hivegrid.de/demo-pro-crm/setup/{TOKEN}"
tracking_urls = (
f"https://tracking.example.test/redirect/{TOKEN}",
f"https://tracking.example.test/redirect?target={quote(setup_url, safe='')}",
)
for tracking_url in tracking_urls:
with self.subTest(tracking_url=tracking_url):
self.assertIsNone(normalize_setup_url(tracking_url, config().portal_origin, config().tenant_slug))
self.assertIsNone(match_delivered_message(config(), query, message(query.recipient, tracking_url), NOW, now=NOW))
def test_rejects_plain_direct_setup_with_tracking_wrapped_html_cta(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
setup_url = f"https://staging-portal.hivegrid.de/demo-pro-crm/setup/{TOKEN}"
tracking_url = f"https://tracking.example.test/redirect/{TOKEN}"
self.assertIsNone(
match_delivered_message(
config(),
query,
message(query.recipient, setup_url, html_url=tracking_url),
NOW,
now=NOW,
)
)
def test_rejects_html_cta_that_requires_character_reference_decoding(self) -> None:
query = parse_mail_query(payload(), MAILBOX_EMAIL, now=NOW)
setup_url = f"https://staging-portal.hivegrid.de/demo-pro-crm/setup/{TOKEN}"
encoded_html_url = f"{setup_url[:-1]}&#x73;"
self.assertIsNone(
match_delivered_message(
config(),
query,
message(query.recipient, setup_url, html_url=encoded_html_url),
NOW,
now=NOW,
)
)
def test_mailbox_base_and_derived_recipient_fail_closed_on_rfc_limits(self) -> None:
base_env = {
"PORTAL_SETUP_MAIL_IMAP_HOST": "imap.example.test",
"MAILBOX_EMAIL": MAILBOX_EMAIL,
"MAILBOX_APP_PASSWORD": "not-used-by-unit-tests",
"E2E_PORTAL_BASE_URL": "https://staging-portal.hivegrid.de",
"E2E_PORTAL_TENANT_SLUG": "demo-pro-crm",
}
for invalid in (
".fixture@example.test",
"fixture@example..test",
"fixture@-example.test",
"fixture+existing@example.test",
"fixture@localhost",
f"{'a' * 65}@example.test",
"fixture@exämple.test",
):
with self.subTest(invalid=invalid), self.assertRaises(ConfigurationError):
load_config({**base_env, "MAILBOX_EMAIL": invalid})
too_long = payload()
with self.assertRaises(ContractError):
parse_mail_query(too_long, f"{'a' * 40}@example.test", now=NOW)
def test_custom_portal_origin_config_is_optional_and_exact(self) -> None:
base_env = {
"PORTAL_SETUP_MAIL_IMAP_HOST": "imap.example.test",
"MAILBOX_EMAIL": MAILBOX_EMAIL,
"MAILBOX_APP_PASSWORD": "not-used-by-unit-tests",
"E2E_PORTAL_BASE_URL": "https://staging-portal.hivegrid.de",
"E2E_PORTAL_TENANT_SLUG": "demo-pro-crm",
}
self.assertIsNone(load_config(base_env).custom_portal_origin)
self.assertEqual(
load_config({**base_env, "E2E_PORTAL_CUSTOM_DOMAIN_BASE_URL": "https://portal.customer.example.test"}).custom_portal_origin,
"https://portal.customer.example.test",
)
for invalid in (
"http://portal.customer.example.test",
"https://portal.customer.example.test/path",
"https://portal.customer.example.test?next=1",
"https://portal.customer.example.test#fragment",
"https://user:password@portal.customer.example.test",
):
with self.subTest(invalid=invalid), self.assertRaises(ConfigurationError):
load_config({**base_env, "E2E_PORTAL_CUSTOM_DOMAIN_BASE_URL": invalid})
def test_http_contract_consumes_a_correlation_once_across_delivery_boundaries(self) -> None:
server, thread = self.start_server()
self.addCleanup(self.stop_server, server, thread)
first = payload()
first["deliveredAfter"] = datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
second = {
**first,
"deliveredAfter": (datetime.now(UTC) + timedelta(milliseconds=1))
.isoformat(timespec="milliseconds")
.replace("+00:00", "Z"),
}
setup_url = f"https://staging-portal.hivegrid.de/demo-pro-crm/setup/{TOKEN}"
with patch(
"portal_setup_mail_adapter.find_delivered_mail",
return_value=DeliveredMail(delivered_at=datetime.now(UTC), setup_url=setup_url),
) as lookup:
first_status, _ = self.request(server, first)
second_status, _ = self.request(server, second)
self.assertEqual(first_status, 200)
self.assertEqual(second_status, 410)
lookup.assert_called_once()
def test_http_contract_rejects_present_empty_or_nonempty_authorization(self) -> None:
server, thread = self.start_server()
self.addCleanup(self.stop_server, server, thread)
current = payload()
current["deliveredAfter"] = datetime.now(UTC).isoformat(timespec="milliseconds").replace("+00:00", "Z")
with patch("portal_setup_mail_adapter.find_delivered_mail") as lookup:
blank_status, _ = self.request(server, current, authorization="")
bearer_status, _ = self.request(server, current, authorization="Bearer forbidden")
self.assertEqual(blank_status, 401)
self.assertEqual(bearer_status, 401)
lookup.assert_not_called()
@staticmethod
def start_server() -> tuple[ThreadingHTTPServer, Thread]:
server = ThreadingHTTPServer(("127.0.0.1", 0), make_handler(config()))
thread = Thread(target=server.serve_forever, kwargs={"poll_interval": 0.01}, daemon=True)
thread.start()
return server, thread
@staticmethod
def stop_server(server: ThreadingHTTPServer, thread: Thread) -> None:
server.shutdown()
server.server_close()
thread.join(timeout=1)
@staticmethod
def request(server: ThreadingHTTPServer, body: dict[str, str], authorization: str | None = None) -> tuple[int, bytes]:
encoded = json.dumps(body).encode("utf-8")
connection = HTTPConnection("127.0.0.1", server.server_port, timeout=2)
connection.putrequest("POST", "/setup-mail")
connection.putheader("Content-Type", "application/json")
connection.putheader("Content-Length", str(len(encoded)))
if authorization is not None:
connection.putheader("Authorization", authorization)
connection.endheaders(encoded)
response = connection.getresponse()
response_body = response.read()
connection.close()
return response.status, response_body
if __name__ == "__main__":
unittest.main()
@@ -0,0 +1,284 @@
// @vitest-environment node
import { createHash } from "node:crypto";
import { readFileSync } from "node:fs";
import { publishAuditEventViaOutbox } from "@hivegrid/db/audit-events.server";
import type { DbClient } from "@hivegrid/db/client.server";
import { describe, expect, it, vi } from "vitest";
import { CUSTOMER_PORTAL_UAT_PROJECT_ID, CUSTOMER_PORTAL_UAT_TENANT_SLUG } from "./contracts";
import {
applyProjectInvitationContact,
assessProjectInvitationContact,
parseProjectInvitationContactInput,
projectInvitationContactIds,
type ProjectInvitationContactCommand,
type ProjectInvitationContactSnapshot,
} from "./project-invitation-contact";
vi.mock("@hivegrid/db/audit-events.server", () => ({ publishAuditEventViaOutbox: vi.fn(async () => undefined) }));
const tenantId = "tenant-demo-pro";
const correlationKey = "p26a-project-20260720t120000z-42";
const mailboxEmail = "fixture@example.test";
const email = `fixture+${correlationKey}@example.test`;
function command(mode: ProjectInvitationContactCommand["mode"] = "apply"): ProjectInvitationContactCommand {
return {
target: "fixture",
mode,
databaseUrl: "postgresql://hivegrid_app:redacted@127.0.0.1:6432/hivegrid_staging",
expectedDatabaseHost: "127.0.0.1",
expectedDatabasePort: "6432",
expectedDatabaseName: "hivegrid_staging",
operatorUserId: "operator-user-id",
auditChainSecret: "redacted-audit-chain-secret-at-least-32-bytes",
expectedTenantId: tenantId,
password: "redacted-strong-fixture-password",
correlationKey,
email,
};
}
function healthySnapshot(): ProjectInvitationContactSnapshot {
const ids = projectInvitationContactIds(tenantId, correlationKey);
const suffix = ids.kontaktId.slice(-12).toUpperCase();
return {
tenant: { id: tenantId, slug: CUSTOMER_PORTAL_UAT_TENANT_SLUG, active: true },
project: {
id: CUSTOMER_PORTAL_UAT_PROJECT_ID,
tenantId,
projekttyp: "sales",
archivedAt: null,
pipeline: { id: "pipeline-sales", tenantId, archivedAt: null },
stage: { id: "stage-open", tenantId, pipelineId: "pipeline-sales", archivedAt: null },
},
portal: { id: "portal-demo-pro", tenantId, isPublished: true },
configuration: { portalId: "portal-demo-pro", tenantId, enabledProjectTypes: ["sales"] },
stageVisibility: { portalId: "portal-demo-pro", tenantId, stageId: "stage-open", visible: true },
ownerMembership: {
tenantId,
userId: "customer-portal-uat-tenant-admin",
joined: 1,
status: 2,
user: {
id: "customer-portal-uat-tenant-admin",
active: true,
pendingDeletion: false,
pseudonymized: false,
},
},
contacts: [
{
id: ids.kontaktId,
tenantId,
createdByUserId: "customer-portal-uat-tenant-admin",
kontaktTyp: "privatperson",
kontaktStatus: "kontakt",
vorname: "Portal",
nachname: `Project-${suffix}`,
primaerEmail: email,
zustaendigerUserId: "customer-portal-uat-tenant-admin",
isDemoData: true,
archivedAt: null,
},
],
emails: [{ id: ids.kontaktEmailId, tenantId, kontaktId: ids.kontaktId, email, primaer: true }],
projectContacts: [
{
id: ids.projektKontaktId,
tenantId,
projektId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
kontaktId: ids.kontaktId,
rolle: "ansprechpartner",
primaer: false,
},
],
};
}
describe("VA-P26a project invitation contact fixture", () => {
it("binds the existing invitation inputs to the dedicated project namespace", () => {
expect(
parseProjectInvitationContactInput({
E2E_PORTAL_INVITATION_ENTRYPOINT: "project",
E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY: correlationKey,
E2E_PORTAL_INVITATION_EMAIL: email,
MAILBOX_EMAIL: mailboxEmail,
})
).toEqual({ correlationKey, email });
expect(() =>
parseProjectInvitationContactInput({
E2E_PORTAL_INVITATION_ENTRYPOINT: "contact",
E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY: correlationKey,
E2E_PORTAL_INVITATION_EMAIL: email,
MAILBOX_EMAIL: mailboxEmail,
})
).toThrow("requires the project entrypoint");
expect(() =>
parseProjectInvitationContactInput({
E2E_PORTAL_INVITATION_ENTRYPOINT: "project",
E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY: "p26a-project-UPPERCASE",
E2E_PORTAL_INVITATION_EMAIL: "fixture+p26a-project-uppercase@example.test",
MAILBOX_EMAIL: mailboxEmail,
})
).toThrow("outside the dedicated P26a project namespace");
for (const invalidCorrelationKey of [
"p26a-project-with.dot",
"p26a-project-with_underscore",
"p26a-project-with:colon",
`p26a-project-${"a".repeat(84)}`,
]) {
expect(() =>
parseProjectInvitationContactInput({
E2E_PORTAL_INVITATION_ENTRYPOINT: "project",
E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY: invalidCorrelationKey,
E2E_PORTAL_INVITATION_EMAIL: `fixture+${invalidCorrelationKey}@example.test`,
MAILBOX_EMAIL: mailboxEmail,
})
).toThrow("outside the dedicated P26a project namespace");
}
expect(() =>
parseProjectInvitationContactInput({
E2E_PORTAL_INVITATION_ENTRYPOINT: "project",
E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY: correlationKey,
E2E_PORTAL_INVITATION_EMAIL: "fixture+different@example.test",
MAILBOX_EMAIL: mailboxEmail,
})
).toThrow("does not match its fixture key");
});
it("rejects invalid authenticated mailbox bases without exposing them", () => {
for (const invalidMailboxEmail of ["fixture+existing@example.test", "fixture@localhost", ".fixture@example.test", "fixture@-example.test"]) {
expect(() =>
parseProjectInvitationContactInput({
E2E_PORTAL_INVITATION_ENTRYPOINT: "project",
E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY: correlationKey,
E2E_PORTAL_INVITATION_EMAIL: email,
MAILBOX_EMAIL: invalidMailboxEmail,
})
).toThrow("MAILBOX_EMAIL is invalid");
}
});
it("derives all row ids from the tenant, project, and correlation key", () => {
const digest = createHash("sha256").update(`${tenantId}:${CUSTOMER_PORTAL_UAT_PROJECT_ID}:${correlationKey}`).digest("hex");
expect(projectInvitationContactIds(tenantId, correlationKey)).toEqual({
kontaktId: `customer-portal-uat-project-kontakt-${digest}`,
kontaktEmailId: `customer-portal-uat-project-email-${digest}`,
projektKontaktId: `customer-portal-uat-project-link-${digest}`,
});
});
it("accepts only the complete UAT-owned rows and emits a redacted handoff", () => {
const assessment = assessProjectInvitationContact(healthySnapshot(), command("verify"));
expect(assessment).toMatchObject({ action: "noop", reconcileIssues: [], blockingIssues: [] });
expect(assessment.handoff).toEqual({
projectPath: `/${CUSTOMER_PORTAL_UAT_TENANT_SLUG}/projects/${CUSTOMER_PORTAL_UAT_PROJECT_ID}`,
projectContactRowId: projectInvitationContactIds(tenantId, correlationKey).projektKontaktId,
});
const handoffJson = JSON.stringify(assessment.handoff);
expect(handoffJson).not.toContain(email);
expect(handoffJson).not.toContain(correlationKey);
expect(handoffJson).not.toContain("Project-");
});
it("reconciles missing rows but blocks recipient and ownership collisions", () => {
const healthy = healthySnapshot();
expect(assessProjectInvitationContact({ ...healthy, contacts: [], emails: [], projectContacts: [] }, command()).action).toBe("reconcile");
const hiddenProject = assessProjectInvitationContact({ ...healthy, stageVisibility: { ...healthy.stageVisibility!, visible: false } }, command());
expect(hiddenProject.action).toBe("blocked");
expect(hiddenProject.blockingIssues).toContain("deterministic UAT project is not visible through the published target portal");
const foreignContact = {
...healthy.contacts[0]!,
id: "foreign-contact",
createdByUserId: "another-user",
isDemoData: false,
};
const collision = assessProjectInvitationContact({ ...healthy, contacts: [...healthy.contacts, foreignContact] }, command());
expect(collision.action).toBe("blocked");
expect(collision.blockingIssues).toContain("invitation recipient collides with another CRM contact");
expect(collision.handoff).toBeNull();
const foreignOwner = assessProjectInvitationContact({ ...healthy, contacts: [{ ...healthy.contacts[0]!, createdByUserId: "another-user" }] }, command());
expect(foreignOwner.action).toBe("blocked");
expect(foreignOwner.blockingIssues).toContain("deterministic CRM contact id is not owned by the VA-P26a fixture");
});
it("locks and revalidates before typed writes and appends a redacted audit outbox event", async () => {
const missingSnapshot = { ...healthySnapshot(), contacts: [], emails: [], projectContacts: [] };
const ids = projectInvitationContactIds(tenantId, correlationKey);
const queryRaw = vi.fn().mockResolvedValue([]);
queryRaw.mockResolvedValueOnce([{ id: tenantId }]);
const kontaktUpsert = vi.fn(async () => ({ id: ids.kontaktId }));
const emailUpsert = vi.fn(async () => ({ id: ids.kontaktEmailId }));
const projectContactUpsert = vi.fn(async () => ({ id: ids.projektKontaktId }));
const tx = {
$queryRaw: queryRaw,
tenant: { findFirst: vi.fn(async () => missingSnapshot.tenant) },
projekt: { findFirst: vi.fn(async () => missingSnapshot.project) },
portal: { findFirst: vi.fn(async () => missingSnapshot.portal) },
portalConfiguration: { findFirst: vi.fn(async () => missingSnapshot.configuration) },
portalStageVisibility: { findFirst: vi.fn(async () => missingSnapshot.stageVisibility) },
tenantUser: { findFirst: vi.fn(async () => missingSnapshot.ownerMembership) },
kontakt: { findMany: vi.fn(async () => []), upsert: kontaktUpsert },
kontaktEmail: { findMany: vi.fn(async () => []), upsert: emailUpsert },
projektKontakt: { findMany: vi.fn(async () => []), upsert: projectContactUpsert },
};
const db = {
$transaction: vi.fn(async (operation: (client: typeof tx) => Promise<void>) => operation(tx)),
} as unknown as DbClient;
await applyProjectInvitationContact(db, command(), missingSnapshot);
expect(queryRaw).toHaveBeenCalledTimes(12);
expect(kontaktUpsert).toHaveBeenCalledWith(
expect.objectContaining({
where: { id: ids.kontaktId },
create: expect.objectContaining({
kontaktTyp: "privatperson",
primaerEmail: email,
zustaendigerUserId: "customer-portal-uat-tenant-admin",
isDemoData: true,
}),
})
);
expect(emailUpsert).toHaveBeenCalledWith(expect.objectContaining({ create: expect.objectContaining({ kontaktId: ids.kontaktId, email, primaer: true }) }));
expect(projectContactUpsert).toHaveBeenCalledWith(
expect.objectContaining({
create: expect.objectContaining({
projektId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
kontaktId: ids.kontaktId,
rolle: "ansprechpartner",
primaer: false,
}),
})
);
expect(publishAuditEventViaOutbox).toHaveBeenCalledTimes(1);
const auditInput = vi.mocked(publishAuditEventViaOutbox).mock.calls[0]?.[1];
expect(auditInput).toMatchObject({
action: "customer_portal.uat_project_invitation_contact.provisioned",
targetType: "ProjektKontakt",
targetId: ids.projektKontaktId,
});
const auditJson = JSON.stringify(auditInput);
expect(auditJson).not.toContain(email);
expect(auditJson).not.toContain(correlationKey);
});
it("keeps plan/apply/verify output limited to mode, completion, and handoff", () => {
const coreSource = readFileSync(new URL("./project-invitation-contact.ts", import.meta.url), "utf8");
const cliSource = readFileSync(new URL("./provision-project-invitation-contact.ts", import.meta.url), "utf8");
expect(coreSource.match(/FOR UPDATE/gu)?.length).toBeGreaterThanOrEqual(10);
expect(coreSource.match(/lower\(btrim\(/gu)?.length).toBeGreaterThanOrEqual(4);
expect(coreSource).toContain("const lockedSnapshot = await readProjectInvitationContact(transactionDb, command)");
expect(coreSource).toContain("satisfies Prisma.KontaktUncheckedCreateInput");
expect(coreSource).toContain("publishAuditEventViaOutbox(tx");
expect(cliSource).toContain("readonly handoff: ProjectInvitationContactHandoff | null");
expect(cliSource).not.toContain("readonly assessment:");
expect(cliSource).not.toContain("command.email");
expect(cliSource).not.toContain("command.correlationKey");
});
});
@@ -0,0 +1,584 @@
import { createHash } from "node:crypto";
import { publishAuditEventViaOutbox } from "@hivegrid/db/audit-events.server";
import type { DbClient } from "@hivegrid/db/client.server";
import type { Prisma } from "@hivegrid/db/prisma-browser";
import {
CUSTOMER_PORTAL_UAT_PROJECT_ID,
CUSTOMER_PORTAL_UAT_TENANT_SLUG,
CustomerPortalUatError,
type CustomerPortalFixtureCommand,
type CustomerPortalUatEnvironment,
} from "./contracts";
const UAT_ADMIN_USER_ID = "customer-portal-uat-tenant-admin";
const UAT_PROJECT_KEY_PATTERN = /^p26a-project-[a-z0-9-]{1,83}$/u;
const MAILBOX_LOCAL_PART_PATTERN = /^[A-Za-z0-9!#$%&'*\/=?^_`{|}~-]+(?:\.[A-Za-z0-9!#$%&'*\/=?^_`{|}~-]+)*$/u;
const MAILBOX_DOMAIN_LABEL_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?$/u;
const MAX_MAILBOX_ADDRESS_BYTES = 254;
const MAX_MAILBOX_LOCAL_PART_BYTES = 64;
const MAX_MAILBOX_DOMAIN_BYTES = 253;
export type ProjectInvitationContactInput = {
readonly correlationKey: string;
readonly email: string;
};
export type ProjectInvitationContactCommand = CustomerPortalFixtureCommand & ProjectInvitationContactInput;
export type ProjectInvitationContactIds = {
readonly kontaktId: string;
readonly kontaktEmailId: string;
readonly projektKontaktId: string;
};
export type ProjectInvitationContactSnapshot = {
readonly tenant: { readonly id: string; readonly slug: string; readonly active: boolean } | null;
readonly project: {
readonly id: string;
readonly tenantId: string;
readonly projekttyp: string | null;
readonly archivedAt: Date | null;
readonly pipeline: { readonly id: string; readonly tenantId: string; readonly archivedAt: Date | null };
readonly stage: {
readonly id: string;
readonly tenantId: string;
readonly pipelineId: string;
readonly archivedAt: Date | null;
};
} | null;
readonly portal: { readonly id: string; readonly tenantId: string; readonly isPublished: boolean } | null;
readonly configuration: {
readonly portalId: string;
readonly tenantId: string;
readonly enabledProjectTypes: readonly string[];
} | null;
readonly stageVisibility: {
readonly portalId: string;
readonly tenantId: string;
readonly stageId: string;
readonly visible: boolean;
} | null;
readonly ownerMembership: {
readonly tenantId: string;
readonly userId: string;
readonly joined: number;
readonly status: number;
readonly user: {
readonly id: string;
readonly active: boolean;
readonly pendingDeletion: boolean;
readonly pseudonymized: boolean;
};
} | null;
readonly contacts: readonly {
readonly id: string;
readonly tenantId: string;
readonly createdByUserId: string;
readonly kontaktTyp: string;
readonly kontaktStatus: string;
readonly vorname: string | null;
readonly nachname: string | null;
readonly primaerEmail: string | null;
readonly zustaendigerUserId: string | null;
readonly isDemoData: boolean;
readonly archivedAt: Date | null;
}[];
readonly emails: readonly {
readonly id: string;
readonly tenantId: string;
readonly kontaktId: string;
readonly email: string;
readonly primaer: boolean;
}[];
readonly projectContacts: readonly {
readonly id: string;
readonly tenantId: string;
readonly projektId: string;
readonly kontaktId: string;
readonly rolle: string;
readonly primaer: boolean;
}[];
};
export type ProjectInvitationContactHandoff = {
readonly projectPath: string;
readonly projectContactRowId: string;
};
export type ProjectInvitationContactAssessment = {
readonly action: "noop" | "reconcile" | "blocked";
readonly reconcileIssues: readonly string[];
readonly blockingIssues: readonly string[];
readonly handoff: ProjectInvitationContactHandoff | null;
};
type CanonicalProjectInvitationContact = {
readonly ids: ProjectInvitationContactIds;
readonly firstName: "Portal";
readonly lastName: string;
};
function requiredEnvironmentValue(env: CustomerPortalUatEnvironment, name: string): string {
const value = env[name]?.trim();
if (!value) throw new CustomerPortalUatError(`customer-portal UAT: ${name} is required for the project invitation fixture`);
return value;
}
function parseMailboxBase(env: CustomerPortalUatEnvironment): { readonly localPart: string; readonly domain: string } {
const raw = env.MAILBOX_EMAIL;
if (!raw || raw !== raw.trim() || Buffer.byteLength(raw, "utf8") > MAX_MAILBOX_ADDRESS_BYTES || Buffer.byteLength(raw, "utf8") !== raw.length) {
throw new CustomerPortalUatError("customer-portal UAT: MAILBOX_EMAIL is invalid for the project invitation fixture");
}
const parts = raw.split("@");
if (parts.length !== 2) {
throw new CustomerPortalUatError("customer-portal UAT: MAILBOX_EMAIL is invalid for the project invitation fixture");
}
const [localPart = "", domain = ""] = parts;
const labels = domain.split(".");
if (
localPart.includes("+") ||
!MAILBOX_LOCAL_PART_PATTERN.test(localPart) ||
Buffer.byteLength(localPart, "ascii") > MAX_MAILBOX_LOCAL_PART_BYTES ||
Buffer.byteLength(domain, "ascii") > MAX_MAILBOX_DOMAIN_BYTES ||
labels.length < 2 ||
labels.some((label) => Buffer.byteLength(label, "ascii") > 63 || !MAILBOX_DOMAIN_LABEL_PATTERN.test(label))
) {
throw new CustomerPortalUatError("customer-portal UAT: MAILBOX_EMAIL is invalid for the project invitation fixture");
}
return { localPart: localPart.toLocaleLowerCase("en-US"), domain: domain.toLocaleLowerCase("en-US") };
}
export function parseProjectInvitationContactInput(env: CustomerPortalUatEnvironment): ProjectInvitationContactInput {
if (requiredEnvironmentValue(env, "E2E_PORTAL_INVITATION_ENTRYPOINT") !== "project") {
throw new CustomerPortalUatError("customer-portal UAT: project invitation fixture requires the project entrypoint");
}
const correlationKey = requiredEnvironmentValue(env, "E2E_PORTAL_SETUP_MAIL_FIXTURE_KEY");
if (!UAT_PROJECT_KEY_PATTERN.test(correlationKey)) {
throw new CustomerPortalUatError("customer-portal UAT: project invitation fixture key is outside the dedicated P26a project namespace");
}
const mailbox = parseMailboxBase(env);
const derivedLocalPart = `${mailbox.localPart}+${correlationKey}`;
const expectedEmail = `${derivedLocalPart}@${mailbox.domain}`;
if (Buffer.byteLength(derivedLocalPart, "ascii") > MAX_MAILBOX_LOCAL_PART_BYTES || Buffer.byteLength(expectedEmail, "ascii") > MAX_MAILBOX_ADDRESS_BYTES) {
throw new CustomerPortalUatError("customer-portal UAT: project invitation recipient does not match its fixture key");
}
const rawEmail = requiredEnvironmentValue(env, "E2E_PORTAL_INVITATION_EMAIL");
if (rawEmail !== env.E2E_PORTAL_INVITATION_EMAIL) {
throw new CustomerPortalUatError("customer-portal UAT: project invitation recipient does not match its fixture key");
}
const email = rawEmail.toLocaleLowerCase("en-US");
if (email !== expectedEmail) {
throw new CustomerPortalUatError("customer-portal UAT: project invitation recipient does not match its fixture key");
}
return { correlationKey, email };
}
export function projectInvitationContactIds(tenantId: string, correlationKey: string): ProjectInvitationContactIds {
const digest = createHash("sha256").update(`${tenantId}:${CUSTOMER_PORTAL_UAT_PROJECT_ID}:${correlationKey}`).digest("hex");
return {
kontaktId: `customer-portal-uat-project-kontakt-${digest}`,
kontaktEmailId: `customer-portal-uat-project-email-${digest}`,
projektKontaktId: `customer-portal-uat-project-link-${digest}`,
};
}
function canonicalContact(command: ProjectInvitationContactCommand): CanonicalProjectInvitationContact {
const ids = projectInvitationContactIds(command.expectedTenantId, command.correlationKey);
const suffix = ids.kontaktId.slice(-12).toUpperCase();
return { ids, firstName: "Portal", lastName: `Project-${suffix}` };
}
function sameEmail(left: string | null, right: string): boolean {
return left?.trim().toLocaleLowerCase("en-US") === right;
}
export function assessProjectInvitationContact(
snapshot: ProjectInvitationContactSnapshot,
command: ProjectInvitationContactCommand
): ProjectInvitationContactAssessment {
const canonical = canonicalContact(command);
const reconcileIssues: string[] = [];
const blockingIssues: string[] = [];
if (
!snapshot.tenant ||
snapshot.tenant.id !== command.expectedTenantId ||
snapshot.tenant.slug !== CUSTOMER_PORTAL_UAT_TENANT_SLUG ||
!snapshot.tenant.active
) {
blockingIssues.push("target tenant is missing, inactive, or outside the explicit demo-pro-crm binding");
}
if (
!snapshot.project ||
snapshot.project.id !== CUSTOMER_PORTAL_UAT_PROJECT_ID ||
snapshot.project.tenantId !== command.expectedTenantId ||
snapshot.project.archivedAt !== null ||
!snapshot.project.projekttyp ||
snapshot.project.pipeline.tenantId !== command.expectedTenantId ||
snapshot.project.pipeline.archivedAt !== null ||
snapshot.project.stage.tenantId !== command.expectedTenantId ||
snapshot.project.stage.pipelineId !== snapshot.project.pipeline.id ||
snapshot.project.stage.archivedAt !== null
) {
blockingIssues.push("deterministic UAT project, stage, or pipeline is missing, archived, incomplete, or outside the target tenant");
}
if (
!snapshot.portal ||
snapshot.portal.tenantId !== command.expectedTenantId ||
!snapshot.portal.isPublished ||
!snapshot.configuration ||
snapshot.configuration.tenantId !== command.expectedTenantId ||
snapshot.configuration.portalId !== snapshot.portal.id ||
!snapshot.project?.projekttyp ||
!snapshot.configuration.enabledProjectTypes.includes(snapshot.project.projekttyp) ||
!snapshot.stageVisibility ||
snapshot.stageVisibility.tenantId !== command.expectedTenantId ||
snapshot.stageVisibility.portalId !== snapshot.portal.id ||
snapshot.stageVisibility.stageId !== snapshot.project.stage.id ||
!snapshot.stageVisibility.visible
) {
blockingIssues.push("deterministic UAT project is not visible through the published target portal");
}
if (
!snapshot.ownerMembership ||
snapshot.ownerMembership.tenantId !== command.expectedTenantId ||
snapshot.ownerMembership.userId !== UAT_ADMIN_USER_ID ||
snapshot.ownerMembership.joined !== 1 ||
snapshot.ownerMembership.status !== 2 ||
snapshot.ownerMembership.user.id !== UAT_ADMIN_USER_ID ||
!snapshot.ownerMembership.user.active ||
snapshot.ownerMembership.user.pendingDeletion ||
snapshot.ownerMembership.user.pseudonymized
) {
blockingIssues.push("dedicated UAT tenant admin is not an active target-tenant member");
}
const contact = snapshot.contacts.find((candidate) => candidate.id === canonical.ids.kontaktId);
const contactCollisions = snapshot.contacts.filter((candidate) => candidate.id !== canonical.ids.kontaktId);
if (contactCollisions.length > 0) blockingIssues.push("invitation recipient collides with another CRM contact");
if (contact && (!contact.isDemoData || contact.tenantId !== command.expectedTenantId || contact.createdByUserId !== UAT_ADMIN_USER_ID)) {
blockingIssues.push("deterministic CRM contact id is not owned by the VA-P26a fixture");
} else if (
!contact ||
contact.kontaktTyp !== "privatperson" ||
contact.kontaktStatus !== "kontakt" ||
contact.vorname !== canonical.firstName ||
contact.nachname !== canonical.lastName ||
!sameEmail(contact.primaerEmail, command.email) ||
contact.zustaendigerUserId !== UAT_ADMIN_USER_ID ||
contact.archivedAt !== null
) {
reconcileIssues.push("deterministic UAT CRM contact is missing or drifted");
}
const email = snapshot.emails.find((candidate) => candidate.id === canonical.ids.kontaktEmailId);
const emailCollisions = snapshot.emails.filter((candidate) => candidate.id !== canonical.ids.kontaktEmailId);
if (emailCollisions.length > 0) blockingIssues.push("invitation recipient collides with another CRM email row");
if (email && (email.tenantId !== command.expectedTenantId || email.kontaktId !== canonical.ids.kontaktId)) {
blockingIssues.push("deterministic CRM email id belongs to another contact");
} else if (!email || !sameEmail(email.email, command.email) || !email.primaer) {
reconcileIssues.push("deterministic primary CRM email is missing or drifted");
}
const projectContact = snapshot.projectContacts.find((candidate) => candidate.id === canonical.ids.projektKontaktId);
const projectContactCollisions = snapshot.projectContacts.filter((candidate) => candidate.id !== canonical.ids.projektKontaktId);
if (projectContactCollisions.length > 0) blockingIssues.push("project already has another matching contact assignment");
if (
projectContact &&
(projectContact.tenantId !== command.expectedTenantId ||
projectContact.projektId !== CUSTOMER_PORTAL_UAT_PROJECT_ID ||
projectContact.kontaktId !== canonical.ids.kontaktId)
) {
blockingIssues.push("deterministic project-contact id belongs to another assignment");
} else if (!projectContact || projectContact.rolle !== "ansprechpartner" || projectContact.primaer) {
reconcileIssues.push("deterministic private project-contact assignment is missing or drifted");
}
const action = blockingIssues.length > 0 ? "blocked" : reconcileIssues.length > 0 ? "reconcile" : "noop";
return {
action,
reconcileIssues,
blockingIssues,
handoff:
action === "noop"
? {
projectPath: `/${CUSTOMER_PORTAL_UAT_TENANT_SLUG}/projects/${CUSTOMER_PORTAL_UAT_PROJECT_ID}`,
projectContactRowId: canonical.ids.projektKontaktId,
}
: null,
};
}
export async function readProjectInvitationContact(db: DbClient, command: ProjectInvitationContactCommand): Promise<ProjectInvitationContactSnapshot> {
const canonical = canonicalContact(command);
const tenant = await db.tenant.findFirst({
where: { id: command.expectedTenantId, slug: CUSTOMER_PORTAL_UAT_TENANT_SLUG },
select: { id: true, slug: true, active: true },
});
const project = await db.projekt.findFirst({
where: { id: CUSTOMER_PORTAL_UAT_PROJECT_ID, tenantId: command.expectedTenantId },
select: {
id: true,
tenantId: true,
projekttyp: true,
archivedAt: true,
pipeline: { select: { id: true, tenantId: true, archivedAt: true } },
stage: { select: { id: true, tenantId: true, pipelineId: true, archivedAt: true } },
},
});
const portal = await db.portal.findFirst({
where: { tenantId: command.expectedTenantId },
select: { id: true, tenantId: true, isPublished: true },
});
const configuration = await db.portalConfiguration.findFirst({
where: { tenantId: command.expectedTenantId },
select: { portalId: true, tenantId: true, enabledProjectTypes: true },
});
const stageVisibility = project
? await db.portalStageVisibility.findFirst({
where: { tenantId: command.expectedTenantId, stageId: project.stage.id },
select: { portalId: true, tenantId: true, stageId: true, visible: true },
})
: null;
const ownerMembership = await db.tenantUser.findFirst({
where: { tenantId: command.expectedTenantId, userId: UAT_ADMIN_USER_ID },
select: {
tenantId: true,
userId: true,
joined: true,
status: true,
user: { select: { id: true, active: true, pendingDeletion: true, pseudonymized: true } },
},
});
const contactMatches = await db.$queryRaw<Array<{ id: string }>>`
SELECT contact."id"
FROM "Kontakt" AS contact
WHERE contact."tenantId" = ${command.expectedTenantId}
AND (
contact."id" = ${canonical.ids.kontaktId}
OR lower(btrim(contact."primaerEmail")) = ${command.email}
)
`;
const contacts = await db.kontakt.findMany({
where: { tenantId: command.expectedTenantId, id: { in: contactMatches.map(({ id }) => id) } },
select: {
id: true,
tenantId: true,
createdByUserId: true,
kontaktTyp: true,
kontaktStatus: true,
vorname: true,
nachname: true,
primaerEmail: true,
zustaendigerUserId: true,
isDemoData: true,
archivedAt: true,
},
});
const emailMatches = await db.$queryRaw<Array<{ id: string }>>`
SELECT email."id"
FROM "KontaktEmail" AS email
WHERE email."tenantId" = ${command.expectedTenantId}
AND (
email."id" = ${canonical.ids.kontaktEmailId}
OR email."kontaktId" = ${canonical.ids.kontaktId}
OR lower(btrim(email."email")) = ${command.email}
)
`;
const emails = await db.kontaktEmail.findMany({
where: { tenantId: command.expectedTenantId, id: { in: emailMatches.map(({ id }) => id) } },
select: { id: true, tenantId: true, kontaktId: true, email: true, primaer: true },
});
const projectContacts = await db.projektKontakt.findMany({
where: {
tenantId: command.expectedTenantId,
OR: [{ id: canonical.ids.projektKontaktId }, { projektId: CUSTOMER_PORTAL_UAT_PROJECT_ID, kontaktId: canonical.ids.kontaktId }],
},
select: { id: true, tenantId: true, projektId: true, kontaktId: true, rolle: true, primaer: true },
});
return { tenant, project, portal, configuration, stageVisibility, ownerMembership, contacts, emails, projectContacts };
}
async function lockProjectInvitationContactRows(db: DbClient, command: ProjectInvitationContactCommand): Promise<void> {
const canonical = canonicalContact(command);
const tenantLocks = await db.$queryRaw<Array<{ id: string }>>`
SELECT tenant."id"
FROM "Tenant" AS tenant
WHERE tenant."id" = ${command.expectedTenantId}
AND tenant."slug" = ${CUSTOMER_PORTAL_UAT_TENANT_SLUG}
FOR UPDATE
`;
if (tenantLocks.length !== 1) {
throw new CustomerPortalUatError("customer-portal UAT: target tenant changed after guarded project-contact preflight");
}
await db.$queryRaw`
SELECT project."id"
FROM "Projekt" AS project
WHERE project."id" = ${CUSTOMER_PORTAL_UAT_PROJECT_ID}
AND project."tenantId" = ${command.expectedTenantId}
FOR UPDATE
`;
await db.$queryRaw`
SELECT portal."id"
FROM "Portal" AS portal
WHERE portal."tenantId" = ${command.expectedTenantId}
FOR UPDATE
`;
await db.$queryRaw`
SELECT configuration."id"
FROM "PortalConfiguration" AS configuration
WHERE configuration."tenantId" = ${command.expectedTenantId}
FOR UPDATE
`;
await db.$queryRaw`
SELECT visibility."id"
FROM "PortalStageVisibility" AS visibility
JOIN "Projekt" AS project
ON project."tenantId" = visibility."tenantId"
AND project."stageId" = visibility."stageId"
WHERE project."id" = ${CUSTOMER_PORTAL_UAT_PROJECT_ID}
AND project."tenantId" = ${command.expectedTenantId}
FOR UPDATE OF visibility
`;
await db.$queryRaw`
SELECT uat_user."id"
FROM "User" AS uat_user
WHERE uat_user."id" = ${UAT_ADMIN_USER_ID}
FOR UPDATE
`;
await db.$queryRaw`
SELECT membership."id"
FROM "TenantUser" AS membership
WHERE membership."tenantId" = ${command.expectedTenantId}
AND membership."userId" = ${UAT_ADMIN_USER_ID}
FOR UPDATE
`;
await db.$queryRaw`
SELECT contact."id"
FROM "Kontakt" AS contact
WHERE contact."tenantId" = ${command.expectedTenantId}
AND (
contact."id" = ${canonical.ids.kontaktId}
OR lower(btrim(contact."primaerEmail")) = ${command.email}
)
FOR UPDATE
`;
await db.$queryRaw`
SELECT email."id"
FROM "KontaktEmail" AS email
WHERE email."tenantId" = ${command.expectedTenantId}
AND (
email."id" = ${canonical.ids.kontaktEmailId}
OR email."kontaktId" = ${canonical.ids.kontaktId}
OR lower(btrim(email."email")) = ${command.email}
)
FOR UPDATE
`;
await db.$queryRaw`
SELECT project_contact."id"
FROM "ProjektKontakt" AS project_contact
WHERE project_contact."tenantId" = ${command.expectedTenantId}
AND (
project_contact."id" = ${canonical.ids.projektKontaktId}
OR (
project_contact."projektId" = ${CUSTOMER_PORTAL_UAT_PROJECT_ID}
AND project_contact."kontaktId" = ${canonical.ids.kontaktId}
)
)
FOR UPDATE
`;
}
export async function applyProjectInvitationContact(
db: DbClient,
command: ProjectInvitationContactCommand,
snapshot: ProjectInvitationContactSnapshot
): Promise<void> {
const assessment = assessProjectInvitationContact(snapshot, command);
if (assessment.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: project invitation contact apply is blocked by unsafe or non-UAT state");
}
if (assessment.action === "noop") return;
await db.$transaction(async (tx) => {
const transactionDb = tx as unknown as DbClient;
await lockProjectInvitationContactRows(transactionDb, command);
const lockedSnapshot = await readProjectInvitationContact(transactionDb, command);
const lockedAssessment = assessProjectInvitationContact(lockedSnapshot, command);
if (lockedAssessment.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: project invitation contact ownership changed after guarded preflight");
}
if (lockedAssessment.action === "noop") return;
const canonical = canonicalContact(command);
const contactCreate = {
id: canonical.ids.kontaktId,
tenantId: command.expectedTenantId,
createdByUserId: UAT_ADMIN_USER_ID,
kontaktTyp: "privatperson",
kontaktStatus: "kontakt",
vorname: canonical.firstName,
nachname: canonical.lastName,
primaerEmail: command.email,
zustaendigerUserId: UAT_ADMIN_USER_ID,
isDemoData: true,
} satisfies Prisma.KontaktUncheckedCreateInput;
const contactUpdate = {
kontaktTyp: "privatperson",
kontaktStatus: "kontakt",
vorname: canonical.firstName,
nachname: canonical.lastName,
orgName: null,
orgMerkmal: null,
primaerEmail: command.email,
zustaendigerUserId: UAT_ADMIN_USER_ID,
isDemoData: true,
archivedAt: null,
} satisfies Prisma.KontaktUncheckedUpdateInput;
await tx.kontakt.upsert({ where: { id: canonical.ids.kontaktId }, create: contactCreate, update: contactUpdate });
const emailCreate = {
id: canonical.ids.kontaktEmailId,
tenantId: command.expectedTenantId,
kontaktId: canonical.ids.kontaktId,
email: command.email,
primaer: true,
} satisfies Prisma.KontaktEmailUncheckedCreateInput;
const emailUpdate = { email: command.email, primaer: true } satisfies Prisma.KontaktEmailUncheckedUpdateInput;
await tx.kontaktEmail.upsert({ where: { id: canonical.ids.kontaktEmailId }, create: emailCreate, update: emailUpdate });
const projectContactCreate = {
id: canonical.ids.projektKontaktId,
tenantId: command.expectedTenantId,
projektId: CUSTOMER_PORTAL_UAT_PROJECT_ID,
kontaktId: canonical.ids.kontaktId,
rolle: "ansprechpartner",
primaer: false,
} satisfies Prisma.ProjektKontaktUncheckedCreateInput;
const projectContactUpdate = {
rolle: "ansprechpartner",
primaer: false,
} satisfies Prisma.ProjektKontaktUncheckedUpdateInput;
await tx.projektKontakt.upsert({
where: { id: canonical.ids.projektKontaktId },
create: projectContactCreate,
update: projectContactUpdate,
});
await publishAuditEventViaOutbox(tx, {
tenantId: command.expectedTenantId,
actorId: command.operatorUserId,
actorType: "operator",
action: "customer_portal.uat_project_invitation_contact.provisioned",
targetType: "ProjektKontakt",
targetId: canonical.ids.projektKontaktId,
sourceModule: "customer-portal-uat",
outcome: "success",
dataSensitivity: "internal",
regulatoryScope: ["none"],
metadata: { tenantSlug: CUSTOMER_PORTAL_UAT_TENANT_SLUG, projectId: CUSTOMER_PORTAL_UAT_PROJECT_ID },
});
});
}
@@ -0,0 +1,67 @@
// @vitest-environment node
import { describe, expect, it } from "vitest";
import type { CustomerPortalCatalogPlan } from "./catalog";
import { assessCatalogAuditRecovery, type CatalogAuditRecoveryRow } from "./provision-catalog";
function plan(providerAction: "create" | "update" | "noop" = "noop"): CustomerPortalCatalogPlan {
return {
provider: [
{ resource: "plan", code: "customer_portal_monthly", action: providerAction, driftFields: [] },
{ resource: "add_on", code: "customer_portal_domain_setup", action: "noop", driftFields: [] },
],
database: { action: "noop", reconcileIssues: [], blockingIssues: [] },
};
}
function row(index: number, action: CatalogAuditRecoveryRow["action"], targetId: string | null): CatalogAuditRecoveryRow {
return { id: String(index).padStart(3, "0"), action, targetId, createdAt: new Date(1_700_000_000_000 + index) };
}
describe("customer-portal catalog audit recovery", () => {
it("reconciles a canonical provider resource after a committed POST timed out or its created audit failed", () => {
const recovery = assessCatalogAuditRecovery(
[
row(1, "customer_portal.catalog.provider_requested", "customer_portal_monthly"),
row(2, "customer_portal.catalog.provider_failed", "customer_portal_monthly"),
],
plan()
);
expect(recovery.providerCodesNeedingReconciliation).toEqual(["customer_portal_monthly"]);
});
it("does not mark an unresolved request as reconciled while the provider resource is still missing", () => {
const recovery = assessCatalogAuditRecovery([row(1, "customer_portal.catalog.provider_requested", "customer_portal_monthly")], plan("create"));
expect(recovery.providerCodesNeedingReconciliation).toEqual([]);
});
it("repairs a missing final provisioned audit after provider or database success", () => {
const providerRecovery = assessCatalogAuditRecovery([row(1, "customer_portal.catalog.provider_created", "customer_portal_monthly")], plan());
expect(providerRecovery).toMatchObject({
providerCodesNeedingReconciliation: [],
providerCodesNeedingProvisionedAudit: ["customer_portal_monthly"],
needsProvisionedAudit: true,
});
const databaseRecovery = assessCatalogAuditRecovery([row(1, "customer_portal.catalog.database_reconciled", null)], plan());
expect(databaseRecovery).toMatchObject({ databaseNeedsProvisionedAudit: true, needsProvisionedAudit: true });
});
it("is quiescent once a later canonical provisioned audit closes the recovery window", () => {
const recovery = assessCatalogAuditRecovery(
[
row(1, "customer_portal.catalog.provider_requested", "customer_portal_monthly"),
row(2, "customer_portal.catalog.provider_reconciled", "customer_portal_monthly"),
row(3, "customer_portal.catalog.database_reconciled", null),
row(4, "customer_portal.catalog.provisioned", null),
],
plan()
);
expect(recovery).toEqual({
providerCodesNeedingReconciliation: [],
providerCodesNeedingProvisionedAudit: [],
databaseNeedsProvisionedAudit: false,
needsProvisionedAudit: false,
});
});
});
@@ -0,0 +1,238 @@
import { pathToFileURL } from "node:url";
import { createAuditEvent, type AuditEventWriterClient } from "@hivegrid/db/audit-events.server";
import { seedStandardEntitlements, type EntitlementsSeedClient } from "@hivegrid/db/entitlements-seed.server";
import {
assessDatabaseCatalog,
buildCustomerPortalCatalogPlan,
customerPortalCatalogPlanIsBlocked,
customerPortalCatalogPlanIsComplete,
LagoCatalogClient,
readDatabaseCatalog,
reconcileBasePlanPortalFeatures,
type CustomerPortalCatalogPlan,
} from "./catalog";
import { CustomerPortalUatError, parseCustomerPortalUatCommand, safeCustomerPortalUatError, type CustomerPortalCatalogCommand } from "./contracts";
import { withCustomerPortalOperatorDatabase } from "./database";
type CatalogExecutionResult = {
readonly mode: CustomerPortalCatalogCommand["mode"];
readonly complete: boolean;
readonly plan: CustomerPortalCatalogPlan;
};
const providerAuditActions = [
"customer_portal.catalog.provider_requested",
"customer_portal.catalog.provider_created",
"customer_portal.catalog.provider_failed",
"customer_portal.catalog.provider_reconciled",
] as const;
const catalogAuditActions = [...providerAuditActions, "customer_portal.catalog.database_reconciled", "customer_portal.catalog.provisioned"] as const;
export type CatalogAuditRecoveryRow = {
readonly id: string;
readonly action: (typeof catalogAuditActions)[number];
readonly targetId: string | null;
readonly createdAt: Date;
};
export type CatalogAuditRecovery = {
readonly providerCodesNeedingReconciliation: readonly string[];
readonly providerCodesNeedingProvisionedAudit: readonly string[];
readonly databaseNeedsProvisionedAudit: boolean;
readonly needsProvisionedAudit: boolean;
};
export function assessCatalogAuditRecovery(rows: readonly CatalogAuditRecoveryRow[], plan: CustomerPortalCatalogPlan): CatalogAuditRecovery {
const ordered = [...rows].sort((left, right) => left.createdAt.getTime() - right.createdAt.getTime() || left.id.localeCompare(right.id));
const lastIndex = (predicate: (row: CatalogAuditRecoveryRow) => boolean): number => {
for (let index = ordered.length - 1; index >= 0; index -= 1) {
if (predicate(ordered[index]!)) return index;
}
return -1;
};
const lastProvisioned = lastIndex((row) => row.action === "customer_portal.catalog.provisioned");
const providerCodesNeedingReconciliation: string[] = [];
const providerCodesNeedingProvisionedAudit: string[] = [];
for (const action of plan.provider) {
const requested = lastIndex((row) => row.targetId === action.code && row.action === "customer_portal.catalog.provider_requested");
const completed = lastIndex(
(row) =>
row.targetId === action.code &&
(row.action === "customer_portal.catalog.provider_created" || row.action === "customer_portal.catalog.provider_reconciled")
);
if (action.action === "noop" && requested > completed) providerCodesNeedingReconciliation.push(action.code);
if (completed > lastProvisioned) providerCodesNeedingProvisionedAudit.push(action.code);
}
const lastDatabaseReconciled = lastIndex((row) => row.action === "customer_portal.catalog.database_reconciled");
const databaseNeedsProvisionedAudit = lastDatabaseReconciled > lastProvisioned;
return {
providerCodesNeedingReconciliation,
providerCodesNeedingProvisionedAudit,
databaseNeedsProvisionedAudit,
needsProvisionedAudit: providerCodesNeedingProvisionedAudit.length > 0 || databaseNeedsProvisionedAudit,
};
}
function writeResult(result: CatalogExecutionResult): void {
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}
async function executeCatalogCommand(command: CustomerPortalCatalogCommand): Promise<CatalogExecutionResult> {
const lago = new LagoCatalogClient({ apiUrl: command.lagoApiUrl, apiKey: command.lagoApiKey });
return withCustomerPortalOperatorDatabase(command, async (db) => {
const inspect = async () => buildCustomerPortalCatalogPlan(await lago.readCatalog(), await readDatabaseCatalog(db));
const initialPlan = await inspect();
const priorAuditRows = await db.auditEvent.findMany({
where: {
tenantId: null,
sourceModule: "customer-portal-uat",
action: { in: [...catalogAuditActions] },
},
select: { id: true, action: true, targetId: true, createdAt: true },
orderBy: [{ createdAt: "asc" }, { id: "asc" }],
});
const recovery = assessCatalogAuditRecovery(priorAuditRows as CatalogAuditRecoveryRow[], initialPlan);
const auditComplete = recovery.providerCodesNeedingReconciliation.length === 0 && !recovery.needsProvisionedAudit;
if (command.mode === "plan") {
return { mode: command.mode, complete: customerPortalCatalogPlanIsComplete(initialPlan) && auditComplete, plan: initialPlan };
}
if (command.mode === "verify") {
if (!customerPortalCatalogPlanIsComplete(initialPlan) || !auditComplete) {
throw new CustomerPortalUatError("customer-portal UAT: catalog verification found missing, drifted, or incompletely audited state");
}
return { mode: command.mode, complete: true, plan: initialPlan };
}
if (customerPortalCatalogPlanIsBlocked(initialPlan)) {
throw new CustomerPortalUatError("customer-portal UAT: catalog apply is blocked by existing drift; no mutation was attempted");
}
let mutated = false;
const providerResourcesAudited = new Set<string>();
for (const action of initialPlan.provider) {
const audit = async (phase: "requested" | "created" | "failed" | "reconciled", outcome: "success" | "failure") =>
createAuditEvent(
{
tenantId: null,
actorId: command.operatorUserId,
actorType: "operator",
action: `customer_portal.catalog.provider_${phase}`,
targetType: action.resource === "plan" ? "LagoPlan" : "LagoAddOn",
targetId: action.code,
sourceModule: "customer-portal-uat",
outcome,
dataSensitivity: "internal",
regulatoryScope: ["none"],
metadata: { resource: action.resource },
},
db as unknown as AuditEventWriterClient
);
if (action.action === "noop" && recovery.providerCodesNeedingReconciliation.includes(action.code)) {
await audit("reconciled", "success");
providerResourcesAudited.add(action.code);
mutated = true;
continue;
}
if (action.action !== "create" && action.action !== "update") continue;
await audit("requested", "success");
try {
if (action.resource === "plan") {
if (action.action === "create") await lago.createPlan();
else await lago.updatePlan();
} else if (action.action === "create") {
await lago.createAddOn();
} else {
await lago.updateAddOn();
}
} catch (error) {
await audit("failed", "failure");
throw error;
}
await audit(action.action === "create" ? "created" : "reconciled", "success");
providerResourcesAudited.add(action.code);
mutated = true;
}
if (initialPlan.database.action === "reconcile") {
await db.$transaction(async (tx) => {
await seedStandardEntitlements({
client: tx as unknown as EntitlementsSeedClient,
plans: [],
includeCustomerPortalCommercialProducts: true,
});
const basePlanFeaturesCreated = await reconcileBasePlanPortalFeatures(tx as unknown as Parameters<typeof reconcileBasePlanPortalFeatures>[0]);
const databaseAssessment = assessDatabaseCatalog(await readDatabaseCatalog(tx as unknown as Parameters<typeof readDatabaseCatalog>[0]));
if (databaseAssessment.blockingIssues.length > 0 || databaseAssessment.reconcileIssues.length > 0) {
const residualIssues = [...databaseAssessment.blockingIssues, ...databaseAssessment.reconcileIssues].join(", ");
throw new CustomerPortalUatError(`customer-portal UAT: database catalog did not converge inside the audited transaction: ${residualIssues}`);
}
// The app-role outbox intentionally rejects global events. This is an
// operator-only, low-volume mutation, so persist its platform audit
// directly through the canonical hash-chain writer inside the same
// transaction instead of weakening the tenant-scoped outbox policy.
await createAuditEvent(
{
tenantId: null,
actorId: command.operatorUserId,
actorType: "operator",
action: "customer_portal.catalog.database_reconciled",
targetType: "CustomerPortalCatalog",
sourceModule: "customer-portal-uat",
outcome: "success",
dataSensitivity: "internal",
regulatoryScope: ["none"],
metadata: {
productCodes: initialPlan.database.reconcileIssues.map((issue) => issue.split(":", 1)[0] ?? "unknown"),
basePlanFeaturesCreated,
},
},
tx as unknown as AuditEventWriterClient
);
});
mutated = true;
}
const finalPlan = await inspect();
if (!customerPortalCatalogPlanIsComplete(finalPlan)) {
throw new CustomerPortalUatError("customer-portal UAT: catalog did not converge to the canonical contract");
}
if (mutated || recovery.needsProvisionedAudit) {
for (const code of recovery.providerCodesNeedingProvisionedAudit) providerResourcesAudited.add(code);
await createAuditEvent(
{
tenantId: null,
actorId: command.operatorUserId,
actorType: "operator",
action: "customer_portal.catalog.provisioned",
targetType: "CustomerPortalCatalog",
sourceModule: "customer-portal-uat",
outcome: "success",
dataSensitivity: "internal",
regulatoryScope: ["none"],
metadata: {
providerResources: [...providerResourcesAudited].sort(),
databaseReconciled: initialPlan.database.action === "reconcile" || recovery.databaseNeedsProvisionedAudit,
},
},
db as unknown as AuditEventWriterClient
);
}
return { mode: command.mode, complete: true, plan: finalPlan };
});
}
export async function main(argv: readonly string[] = process.argv.slice(2), env: NodeJS.ProcessEnv = process.env): Promise<void> {
const command = parseCustomerPortalUatCommand("catalog", argv, env);
if (command.target !== "catalog") throw new CustomerPortalUatError("customer-portal UAT: invalid catalog command");
writeResult(await executeCatalogCommand(command));
}
const directEntry = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
if (directEntry) {
void main().catch((error) => {
process.stderr.write(`${safeCustomerPortalUatError(error)}\n`);
process.exitCode = 1;
});
}
@@ -0,0 +1,65 @@
import { pathToFileURL } from "node:url";
import { CustomerPortalUatError, parseCustomerPortalUatCommand, safeCustomerPortalUatError, type CustomerPortalCommercialFixtureCommand } from "./contracts";
import {
applyCustomerPortalCommercialFixture,
assessCustomerPortalCommercialFixture,
readCustomerPortalCommercialFixture,
type CustomerPortalCommercialFixtureAssessment,
} from "./commercial-fixture";
import { withCustomerPortalOperatorDatabase } from "./database";
type CommercialFixtureExecutionResult = {
readonly mode: CustomerPortalCommercialFixtureCommand["mode"];
readonly complete: boolean;
readonly assessment: CustomerPortalCommercialFixtureAssessment;
};
function writeResult(result: CommercialFixtureExecutionResult): void {
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}
async function executeCommercialFixtureCommand(command: CustomerPortalCommercialFixtureCommand): Promise<CommercialFixtureExecutionResult> {
return withCustomerPortalOperatorDatabase(command, async (db) => {
const inspect = async () => assessCustomerPortalCommercialFixture(await readCustomerPortalCommercialFixture(db, command));
const initial = await inspect();
if (command.mode === "plan") {
return { mode: command.mode, complete: initial.action === "noop", assessment: initial };
}
if (command.mode === "verify") {
if (initial.action !== "noop") {
throw new CustomerPortalUatError("customer-portal UAT: commercial fixture verification found missing, drifted, or unsafe state");
}
return { mode: command.mode, complete: true, assessment: initial };
}
if (initial.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: commercial fixture apply is blocked by non-UAT or mismatched staging state");
}
const snapshot = await readCustomerPortalCommercialFixture(db, command);
const preApply = assessCustomerPortalCommercialFixture(snapshot);
if (preApply.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: commercial fixture state changed during preflight");
}
await applyCustomerPortalCommercialFixture(db, command, snapshot);
const final = await inspect();
if (final.action !== "noop") {
throw new CustomerPortalUatError("customer-portal UAT: commercial fixture did not converge to the canonical contract");
}
return { mode: command.mode, complete: true, assessment: final };
});
}
export async function main(argv: readonly string[] = process.argv.slice(2), env: NodeJS.ProcessEnv = process.env): Promise<void> {
const command = parseCustomerPortalUatCommand("commercial-fixture", argv, env);
if (command.target !== "commercial-fixture") throw new CustomerPortalUatError("customer-portal UAT: invalid commercial fixture command");
writeResult(await executeCommercialFixtureCommand(command));
}
const directEntry = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
if (directEntry) {
void main().catch((error) => {
process.stderr.write(`${safeCustomerPortalUatError(error)}\n`);
process.exitCode = 1;
});
}
@@ -0,0 +1,63 @@
import { pathToFileURL } from "node:url";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
import { CustomerPortalUatError, parseCustomerPortalUatCommand, safeCustomerPortalUatError, type CustomerPortalFixtureCommand } from "./contracts";
import { withCustomerPortalOperatorDatabase } from "./database";
import { applyCustomerPortalFixture, assessCustomerPortalFixture, readCustomerPortalFixture, type CustomerPortalFixtureAssessment } from "./fixture";
type FixtureExecutionResult = {
readonly mode: CustomerPortalFixtureCommand["mode"];
readonly complete: boolean;
readonly assessment: CustomerPortalFixtureAssessment;
};
function writeResult(result: FixtureExecutionResult): void {
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}
async function executeFixtureCommand(command: CustomerPortalFixtureCommand): Promise<FixtureExecutionResult> {
return withCustomerPortalOperatorDatabase(command, (db) =>
runWithRlsContext({ tenantId: command.expectedTenantId }, async () => {
const inspect = async () => {
const snapshot = await readCustomerPortalFixture(db, command);
return { snapshot, assessment: assessCustomerPortalFixture(snapshot, command.expectedTenantId) };
};
const initial = await inspect();
if (command.mode === "plan") {
return { mode: command.mode, complete: initial.assessment.action === "noop", assessment: initial.assessment };
}
if (command.mode === "verify") {
if (initial.assessment.action !== "noop") {
throw new CustomerPortalUatError("customer-portal UAT: fixture verification found missing, drifted, or unsafe state");
}
return { mode: command.mode, complete: true, assessment: initial.assessment };
}
if (initial.assessment.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: fixture apply is blocked by non-UAT or mismatched staging state");
}
await applyCustomerPortalFixture(db, command, initial.snapshot);
const final = await inspect();
if (final.assessment.action !== "noop") {
throw new CustomerPortalUatError("customer-portal UAT: fixture did not converge to the canonical contract");
}
return { mode: command.mode, complete: true, assessment: final.assessment };
})
);
}
export async function main(argv: readonly string[] = process.argv.slice(2), env: NodeJS.ProcessEnv = process.env): Promise<void> {
const command = parseCustomerPortalUatCommand("fixture", argv, env);
if (command.target !== "fixture") throw new CustomerPortalUatError("customer-portal UAT: invalid fixture command");
writeResult(await executeFixtureCommand(command));
}
const directEntry = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
if (directEntry) {
void main().catch((error) => {
process.stderr.write(`${safeCustomerPortalUatError(error)}\n`);
process.exitCode = 1;
});
}
@@ -0,0 +1,77 @@
import { pathToFileURL } from "node:url";
import { runWithRlsContext } from "@hivegrid/db/rls-context.server";
import {
CustomerPortalUatError,
parseCustomerPortalUatCommand,
safeCustomerPortalUatError,
type CustomerPortalFixtureCommand,
} from "./contracts";
import { withCustomerPortalOperatorDatabase } from "./database";
import {
applyProjectInvitationContact,
assessProjectInvitationContact,
parseProjectInvitationContactInput,
readProjectInvitationContact,
type ProjectInvitationContactCommand,
type ProjectInvitationContactHandoff,
} from "./project-invitation-contact";
export type ProjectInvitationContactExecutionResult = {
readonly mode: CustomerPortalFixtureCommand["mode"];
readonly complete: boolean;
readonly handoff: ProjectInvitationContactHandoff | null;
};
function writeResult(result: ProjectInvitationContactExecutionResult): void {
process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
}
async function executeProjectInvitationContactCommand(
command: ProjectInvitationContactCommand
): Promise<ProjectInvitationContactExecutionResult> {
return withCustomerPortalOperatorDatabase(command, (db) =>
runWithRlsContext({ tenantId: command.expectedTenantId }, async () => {
const inspect = async () => {
const snapshot = await readProjectInvitationContact(db, command);
return { snapshot, assessment: assessProjectInvitationContact(snapshot, command) };
};
const initial = await inspect();
if (command.mode === "plan") {
return { mode: command.mode, complete: initial.assessment.action === "noop", handoff: initial.assessment.handoff };
}
if (command.mode === "verify") {
if (initial.assessment.action !== "noop" || !initial.assessment.handoff) {
throw new CustomerPortalUatError("customer-portal UAT: project invitation contact verification found missing, drifted, or unsafe state");
}
return { mode: command.mode, complete: true, handoff: initial.assessment.handoff };
}
if (initial.assessment.action === "blocked") {
throw new CustomerPortalUatError("customer-portal UAT: project invitation contact apply is blocked by unsafe or non-UAT state");
}
await applyProjectInvitationContact(db, command, initial.snapshot);
const final = await inspect();
if (final.assessment.action !== "noop" || !final.assessment.handoff) {
throw new CustomerPortalUatError("customer-portal UAT: project invitation contact did not converge to the canonical contract");
}
return { mode: command.mode, complete: true, handoff: final.assessment.handoff };
})
);
}
export async function main(argv: readonly string[] = process.argv.slice(2), env: NodeJS.ProcessEnv = process.env): Promise<void> {
const baseCommand = parseCustomerPortalUatCommand("fixture", argv, env);
if (baseCommand.target !== "fixture") throw new CustomerPortalUatError("customer-portal UAT: invalid project invitation fixture command");
const command: ProjectInvitationContactCommand = { ...baseCommand, ...parseProjectInvitationContactInput(env) };
writeResult(await executeProjectInvitationContactCommand(command));
}
const directEntry = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
if (directEntry) {
void main().catch((error) => {
process.stderr.write(`${safeCustomerPortalUatError(error)}\n`);
process.exitCode = 1;
});
}
@@ -0,0 +1,345 @@
import type { EmployeeRole, ProjectType, SeedAddress } from "./types";
export const REFERENCE_DATE = "2026-07-13T08:00:00.000Z";
export const LOCATIONS: readonly Omit<SeedAddress, "strasse" | "hausnummer" | "land">[] = [
{ plz: "60311", ort: "Frankfurt am Main" },
{ plz: "60314", ort: "Frankfurt am Main" },
{ plz: "60433", ort: "Frankfurt am Main" },
{ plz: "60528", ort: "Frankfurt am Main" },
{ plz: "63065", ort: "Offenbach am Main" },
{ plz: "63071", ort: "Offenbach am Main" },
{ plz: "61118", ort: "Bad Vilbel" },
{ plz: "63477", ort: "Maintal" },
{ plz: "63263", ort: "Neu-Isenburg" },
{ plz: "65760", ort: "Eschborn" },
{ plz: "65719", ort: "Hofheim am Taunus" },
{ plz: "63450", ort: "Hanau" },
{ plz: "65428", ort: "Rüsselsheim am Main" },
{ plz: "61348", ort: "Bad Homburg vor der Höhe" },
{ plz: "64283", ort: "Darmstadt" },
{ plz: "65185", ort: "Wiesbaden" },
] as const;
export const STREET_PREFIXES = [
"Mainblick",
"Taunusblick",
"Mühlenrain",
"Apfelgarten",
"Kastanienhain",
"Quellenfeld",
"Rosenhöhe",
"Mainsonnenhang",
"Mainerlenbruch",
"Wiesenbogen",
"Falkengrund",
"Kupferwiese",
"Lindenrain",
"Auenblick",
"Taunusschieferhang",
"Mainkirschgarten",
"Buchenfeld",
"Morgenhöhe",
"Weidenbogen",
"Kranichgrund",
] as const;
export const STREET_SUFFIXES = ["straße", "weg", "ring", "allee", "pfad", "bogen"] as const;
export const FEMALE_FIRST_NAMES = [
"Anna",
"Sabine",
"Julia",
"Katharina",
"Laura",
"Nadine",
"Petra",
"Claudia",
"Miriam",
"Tanja",
"Leonie",
"Melanie",
"Stefanie",
"Jasmin",
"Saskia",
"Carolin",
"Bianca",
"Vanessa",
"Heike",
"Nicole",
] as const;
export const MALE_FIRST_NAMES = [
"Thomas",
"Michael",
"Andreas",
"Stefan",
"Markus",
"Daniel",
"Christian",
"Sebastian",
"Martin",
"Alexander",
"Tobias",
"Matthias",
"Jan",
"Florian",
"Patrick",
"Mehmet",
"Murat",
"Dennis",
"Sven",
"Oliver",
] as const;
export const LAST_NAMES = [
"Schneider",
"Fischer",
"Weber",
"Meyer",
"Wagner",
"Becker",
"Hoffmann",
"Schäfer",
"Koch",
"Bauer",
"Richter",
"Klein",
"Wolf",
"Schröder",
"Neumann",
"Schwarz",
"Zimmermann",
"Braun",
"Krüger",
"Hartmann",
"Lange",
"Werner",
"Schmitz",
"Krause",
"Meier",
"Lehmann",
"Schmid",
"Schulz",
"Maier",
"Köhler",
] as const;
// These names belong to the globally persisted rheinmain-shk-v1 employee IDs.
// Keep this mapping immutable when roles, seats, departments, or crews change.
export const EMPLOYEE_IDENTITIES_V1 = [
{ firstName: "Anna", lastName: "Schneider" },
{ firstName: "Michael", lastName: "Schäfer" },
{ firstName: "Julia", lastName: "Neumann" },
{ firstName: "Stefan", lastName: "Werner" },
{ firstName: "Laura", lastName: "Maier" },
{ firstName: "Daniel", lastName: "Becker" },
{ firstName: "Petra", lastName: "Wolf" },
{ firstName: "Sebastian", lastName: "Hartmann" },
{ firstName: "Miriam", lastName: "Schmid" },
{ firstName: "Alexander", lastName: "Meyer" },
{ firstName: "Leonie", lastName: "Richter" },
{ firstName: "Matthias", lastName: "Braun" },
{ firstName: "Stefanie", lastName: "Meier" },
{ firstName: "Florian", lastName: "Fischer" },
{ firstName: "Saskia", lastName: "Koch" },
{ firstName: "Mehmet", lastName: "Schwarz" },
{ firstName: "Bianca", lastName: "Schmitz" },
{ firstName: "Dennis", lastName: "Köhler" },
{ firstName: "Heike", lastName: "Hoffmann" },
{ firstName: "Oliver", lastName: "Schröder" },
{ firstName: "Miriam", lastName: "Wagner" },
{ firstName: "Markus", lastName: "Schwarz" },
{ firstName: "Daniel", lastName: "Schmid" },
{ firstName: "Christian", lastName: "Schäfer" },
{ firstName: "Sebastian", lastName: "Krüger" },
{ firstName: "Jasmin", lastName: "Köhler" },
{ firstName: "Alexander", lastName: "Richter" },
{ firstName: "Tobias", lastName: "Werner" },
{ firstName: "Matthias", lastName: "Weber" },
{ firstName: "Jan", lastName: "Schröder" },
{ firstName: "Heike", lastName: "Meier" },
{ firstName: "Patrick", lastName: "Becker" },
{ firstName: "Mehmet", lastName: "Zimmermann" },
{ firstName: "Murat", lastName: "Schulz" },
{ firstName: "Dennis", lastName: "Koch" },
{ firstName: "Katharina", lastName: "Hartmann" },
{ firstName: "Oliver", lastName: "Schneider" },
{ firstName: "Thomas", lastName: "Klein" },
{ firstName: "Michael", lastName: "Schmitz" },
{ firstName: "Andreas", lastName: "Meyer" },
{ firstName: "Miriam", lastName: "Neumann" },
{ firstName: "Markus", lastName: "Lehmann" },
{ firstName: "Daniel", lastName: "Hoffmann" },
{ firstName: "Christian", lastName: "Braun" },
{ firstName: "Sebastian", lastName: "Maier" },
{ firstName: "Jasmin", lastName: "Bauer" },
{ firstName: "Alexander", lastName: "Lange" },
{ firstName: "Tobias", lastName: "Fischer" },
{ firstName: "Matthias", lastName: "Wolf" },
{ firstName: "Jan", lastName: "Krause" },
] as const;
export const OFFICE_ROLE_COUNTS: ReadonlyArray<{ role: EmployeeRole; count: number; jobTitle: string }> = [
{ role: "Geschäftsführer", count: 1, jobTitle: "Geschäftsführer" },
{ role: "Vertriebsleiter", count: 1, jobTitle: "Leiter Vertrieb" },
{ role: "Vertriebler", count: 3, jobTitle: "Fachberater SHK" },
{ role: "Büro/Backoffice", count: 4, jobTitle: "Kaufmännische Sachbearbeitung" },
{ role: "Marketing", count: 1, jobTitle: "Marketing und Kommunikation" },
{ role: "Projektleiter/Bauleiter", count: 7, jobTitle: "Projektleiter SHK" },
] as const;
export const ORGANIZATION_SECTORS = [
"Hausverwaltung",
"Wohnungswirtschaft",
"Gastronomie",
"Hotellerie",
"Einzelhandel",
"Büro und Beratung",
"Bauunternehmen",
"Architekturbüro",
"Partnerhandwerk",
"Pflegeeinrichtung",
"Bildungsträger",
"Kommunale Einrichtung",
"Industrie",
"Logistik",
"Großhandel",
] as const;
export const ORGANIZATION_ROOTS = [
"Mainbogen",
"Taunusblick",
"Rheinwarte",
"Stadtgarten",
"Quellenhof",
"Uferwerk",
"Auenland",
"Hofgarten",
"Brückenfeld",
"Sonnenhof",
"Mainquartier",
"Wiesenwerk",
"Römerblick",
"Kronenhof",
"Mühlenwerk",
"Bergquell",
"Westhafen",
] as const;
export const PROJECT_TYPE_COUNTS: Readonly<Record<ProjectType, number>> = {
reparatur_notdienst: 150,
wartung_pruefung: 118,
heizungstausch: 86,
heizungsoptimierung: 43,
badsanierung: 64,
sanitaer_rohrarbeiten: 38,
objekt_neubau: 22,
lueftung_klima: 16,
};
export const PROJECT_TYPE_DETAILS: Readonly<
Record<
ProjectType,
{
label: string;
descriptions: readonly string[];
minValue: number;
maxValue: number;
durationDays: [number, number];
}
>
> = {
reparatur_notdienst: {
label: "Reparatur und Störungsdienst",
descriptions: [
"Heizungsstörung diagnostizieren und beheben",
"Rohrleck lokalisieren und instand setzen",
"Warmwasserversorgung kurzfristig wiederherstellen",
],
minValue: 250,
maxValue: 4500,
durationDays: [1, 4],
},
wartung_pruefung: {
label: "Wartung und Prüfung",
descriptions: [
"Jahreswartung mit Messprotokoll durchführen",
"Anlage reinigen, prüfen und hydraulisch nachstellen",
"Wartungstermin inklusive Verschleißteilprüfung ausführen",
],
minValue: 250,
maxValue: 2500,
durationDays: [1, 3],
},
heizungstausch: {
label: "Heizungstausch",
descriptions: [
"Bestandsanlage demontieren und Wärmepumpe installieren",
"Wärmeerzeuger samt Speicher und Regelung erneuern",
"Heizzentrale modernisieren und Anlage einregulieren",
],
minValue: 12000,
maxValue: 45000,
durationDays: [4, 14],
},
heizungsoptimierung: {
label: "Heizungsoptimierung",
descriptions: [
"Hydraulischen Abgleich und Pumpentausch durchführen",
"Regelung optimieren und Heizkreise einregulieren",
"Verbrauchsanalyse mit Optimierungsmaßnahmen umsetzen",
],
minValue: 1500,
maxValue: 8000,
durationDays: [2, 6],
},
badsanierung: {
label: "Badsanierung",
descriptions: [
"Bad vollständig entkernen und barrierearm neu ausbauen",
"Sanitärobjekte und Leitungsführung modernisieren",
"Teilbad mit Dusche, Armaturen und Vorwand erneuern",
],
minValue: 4000,
maxValue: 45850,
durationDays: [5, 24],
},
sanitaer_rohrarbeiten: {
label: "Sanitär- und Rohrarbeiten",
descriptions: [
"Trinkwasserleitungen abschnittsweise erneuern",
"Fallstrang sanieren und Anschlussleitungen anpassen",
"Sanitärinstallation für Nutzungseinheit herstellen",
],
minValue: 1200,
maxValue: 28000,
durationDays: [2, 18],
},
objekt_neubau: {
label: "Objekt- und Neubauinstallation",
descriptions: [
"SHK-Gewerke für Mehrfamilienhaus koordinieren und ausführen",
"Heizungs- und Sanitärinstallation im Gewerbeobjekt herstellen",
"Technikzentrale und Steigstränge für Neubau errichten",
],
minValue: 50000,
maxValue: 250000,
durationDays: [30, 150],
},
lueftung_klima: {
label: "Lüftung und Klima",
descriptions: [
"Kontrollierte Wohnraumlüftung planen und montieren",
"Klimageräte für Gewerbefläche installieren",
"Lüftungsanlage reinigen und Volumenströme einregulieren",
],
minValue: 3500,
maxValue: 55000,
durationDays: [3, 30],
},
};
export const SALES_STAGE_COUNTS = { neu: 47, qualifiziert: 59, angebot: 73, gewonnen: 112, verloren: 28 } as const;
export const ORDER_STAGE_COUNTS = { planung: 31, montage: 67, abnahme: 39, abgeschlossen: 69, storniert: 12 } as const;
export const LEAD_OUTCOME_COUNTS = { spam: 15, disqualified: 33, offer_lost: 29, converted: 116 } as const;
@@ -0,0 +1,226 @@
import { describe, expect, test, vi } from "vitest";
import { DEMO_PRO_TENANT_SLUG, parseSeedCommand } from "./cli";
const stagingEnv = {
SEED_DEMO_PRO_ALLOWED: "true",
SEED_DEMO_PRO_EXPECTED_DATABASE: "hivegrid_staging",
SEED_DEMO_PRO_EXPECTED_DATABASE_HOST: "postgres-staging:5432",
SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET: "hivegrid-staging-media",
SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT: "https://staging-storage.example.test",
SEED_DEMO_PRO_EXPECTED_TENANT_ID: "tenant_staging_demo_pro",
SEED_DEMO_PRO_OUTBOUND_SANDBOX: "true",
SEED_DEMO_PRO_WORKERS_DRAINED: "true",
SEED_DEMO_USER_PASSWORD: "R7!qL2#vN9@xP4$kT8&m",
SENTRY_ENVIRONMENT: "staging",
};
describe("demo-pro seed CLI", () => {
test("defaults to an environment-free dry run", () => {
expect(parseSeedCommand([], {})).toEqual({
mode: "dry-run",
tenantSlug: DEMO_PRO_TENANT_SLUG,
});
expect(parseSeedCommand(["--dry-run"], {})).toEqual({
mode: "dry-run",
tenantSlug: DEMO_PRO_TENANT_SLUG,
});
});
test("accepts only the demo-pro-crm tenant", () => {
expect(parseSeedCommand(["--tenant=demo-pro-crm"], {})).toEqual({
mode: "dry-run",
tenantSlug: DEMO_PRO_TENANT_SLUG,
});
expect(() => parseSeedCommand(["--tenant=another-tenant"], {})).toThrow("target tenant must be demo-pro-crm");
});
test("rejects unknown, duplicate and conflicting arguments", () => {
expect(() => parseSeedCommand(["apply"], {})).toThrow("unknown argument");
expect(() => parseSeedCommand(["--apply", "--cleanup"], stagingEnv)).toThrow("exactly one mode");
expect(() => parseSeedCommand(["--tenant=demo-pro-crm", "--tenant=demo-pro-crm"], {})).toThrow("--tenant may only be provided once");
expect(() => parseSeedCommand(["--apply", "--confirm=demo-pro-crm", "--confirm=demo-pro-crm"], stagingEnv)).toThrow("--confirm may only be provided once");
});
test("requires an exact tenant confirmation for apply", () => {
expect(() => parseSeedCommand(["--apply"], stagingEnv)).toThrow("--confirm=demo-pro-crm");
expect(() => parseSeedCommand(["--apply", "--confirm=another-tenant"], stagingEnv)).toThrow("--confirm=demo-pro-crm");
});
test("requires explicit authorization for apply and cleanup", () => {
expect(() =>
parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
SENTRY_ENVIRONMENT: "staging",
})
).toThrow("explicit staging seed authorization");
expect(() =>
parseSeedCommand(["--cleanup", "--confirm=demo-pro-crm"], {
SENTRY_ENVIRONMENT: "staging",
})
).toThrow("explicit staging seed authorization");
});
test("requires drained workers and a staging-only outbound sink", () => {
expect(() =>
parseSeedCommand(["--cleanup", "--confirm=demo-pro-crm"], {
...stagingEnv,
SEED_DEMO_PRO_WORKERS_DRAINED: "false",
})
).toThrow("drained workers");
expect(() =>
parseSeedCommand(["--cleanup", "--confirm=demo-pro-crm"], {
...stagingEnv,
SEED_DEMO_PRO_OUTBOUND_SANDBOX: "false",
})
).toThrow("outbound staging sandbox");
});
test("allows apply only on staging and resolves the configured staging password", () => {
expect(parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], stagingEnv)).toEqual({
mode: "apply",
tenantSlug: DEMO_PRO_TENANT_SLUG,
userPassword: "R7!qL2#vN9@xP4$kT8&m",
expectedTenantId: "tenant_staging_demo_pro",
expectedDatabaseName: "hivegrid_staging",
expectedDatabaseHost: "postgres-staging:5432",
expectedStorageBucket: "hivegrid-staging-media",
expectedStorageEndpoint: "https://staging-storage.example.test",
});
});
test("requires the password to be supplied as a staging secret", () => {
expect(() =>
parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
SEED_DEMO_PRO_ALLOWED: "true",
SEED_DEMO_PRO_EXPECTED_DATABASE: "hivegrid_staging",
SEED_DEMO_PRO_EXPECTED_DATABASE_HOST: "postgres-staging:5432",
SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET: "hivegrid-staging-media",
SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT: "https://staging-storage.example.test",
SEED_DEMO_PRO_EXPECTED_TENANT_ID: "tenant_staging_demo_pro",
SEED_DEMO_PRO_OUTBOUND_SANDBOX: "true",
SEED_DEMO_PRO_WORKERS_DRAINED: "true",
SENTRY_ENVIRONMENT: "staging",
})
).toThrow("demo-user password secret");
});
test("requires mutation to be bound to the exact staging tenant and database", () => {
expect(() =>
parseSeedCommand(["--cleanup", "--confirm=demo-pro-crm"], {
SEED_DEMO_PRO_ALLOWED: "true",
SEED_DEMO_PRO_OUTBOUND_SANDBOX: "true",
SEED_DEMO_PRO_WORKERS_DRAINED: "true",
SENTRY_ENVIRONMENT: "staging",
})
).toThrow("tenant, database, and storage binding");
});
test.each(["passwort", "password", "HiveGrid-Demo-Password", "short-but-varied!9A"])("rejects a weak shared staging password (%s)", (password) => {
expect(() =>
parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
...stagingEnv,
SEED_DEMO_USER_PASSWORD: password,
})
).toThrow("strong random secret");
});
test("allows the explicitly requested shared password only behind the dedicated staging guard", () => {
expect(
parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
...stagingEnv,
SEED_DEMO_PRO_ALLOW_SHARED_STAGING_PASSWORD: "true",
SEED_DEMO_USER_PASSWORD: "password",
}),
).toMatchObject({ mode: "apply", userPassword: "password" });
expect(() =>
parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
...stagingEnv,
SEED_DEMO_PRO_ALLOW_SHARED_STAGING_PASSWORD: "true",
SEED_DEMO_USER_PASSWORD: "passwort",
}),
).toThrow("strong random secret");
});
test("keeps a configured password opaque and does not log it", () => {
const consoleSpies = [
vi.spyOn(console, "log").mockImplementation(() => undefined),
vi.spyOn(console, "info").mockImplementation(() => undefined),
vi.spyOn(console, "warn").mockImplementation(() => undefined),
vi.spyOn(console, "error").mockImplementation(() => undefined),
];
const password = " R7!qL2#vN9@xP4$kT8&m ";
const command = parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
...stagingEnv,
SEED_DEMO_USER_PASSWORD: password,
});
expect(command).toEqual({
mode: "apply",
tenantSlug: DEMO_PRO_TENANT_SLUG,
userPassword: password,
expectedTenantId: "tenant_staging_demo_pro",
expectedDatabaseName: "hivegrid_staging",
expectedDatabaseHost: "postgres-staging:5432",
expectedStorageBucket: "hivegrid-staging-media",
expectedStorageEndpoint: "https://staging-storage.example.test",
});
for (const spy of consoleSpies) expect(spy).not.toHaveBeenCalled();
vi.restoreAllMocks();
});
test("does not echo values from rejected arguments", () => {
const accidentalSecret = "Never expose this value";
expect(() => parseSeedCommand([`--password=${accidentalSecret}`], {})).toThrowError(
expect.not.objectContaining({ message: expect.stringContaining(accidentalSecret) })
);
});
test.each([undefined, "", "production", "development", "test", "STAGING", "staging-preview"])(
"rejects verify outside the exact staging environment (%s)",
(environment) => {
expect(() =>
parseSeedCommand(["--verify"], {
SENTRY_ENVIRONMENT: environment,
})
).toThrow("restricted to the staging environment");
}
);
test("allows read-only verification on staging without mutation authorization", () => {
expect(parseSeedCommand(["--verify"], { SENTRY_ENVIRONMENT: "staging" })).toEqual({
mode: "verify",
tenantSlug: DEMO_PRO_TENANT_SLUG,
});
});
test("allows cleanup only with every destructive-operation guard", () => {
expect(parseSeedCommand(["--cleanup", "--confirm=demo-pro-crm"], stagingEnv)).toEqual({
mode: "cleanup",
tenantSlug: DEMO_PRO_TENANT_SLUG,
expectedTenantId: "tenant_staging_demo_pro",
expectedDatabaseName: "hivegrid_staging",
expectedDatabaseHost: "postgres-staging:5432",
expectedStorageBucket: "hivegrid-staging-media",
expectedStorageEndpoint: "https://staging-storage.example.test",
});
});
test("does not treat NODE_ENV=production as production when the deployment is explicitly staging", () => {
expect(
parseSeedCommand(["--apply", "--confirm=demo-pro-crm"], {
...stagingEnv,
NODE_ENV: "production",
})
).toMatchObject({ mode: "apply", tenantSlug: DEMO_PRO_TENANT_SLUG });
});
test("does not accept confirmation for non-mutating modes", () => {
expect(() => parseSeedCommand(["--confirm=demo-pro-crm"], {})).toThrow("--confirm is only valid for apply and cleanup");
expect(() => parseSeedCommand(["--verify", "--confirm=demo-pro-crm"], { SENTRY_ENVIRONMENT: "staging" })).toThrow(
"--confirm is only valid for apply and cleanup"
);
});
});
@@ -0,0 +1,173 @@
export const DEMO_PRO_TENANT_SLUG = "demo-pro-crm" as const;
export type SeedMode = "dry-run" | "apply" | "verify" | "cleanup";
type NonApplySeedCommand = {
mode: "dry-run" | "verify";
tenantSlug: typeof DEMO_PRO_TENANT_SLUG;
};
type CleanupSeedCommand = {
mode: "cleanup";
tenantSlug: typeof DEMO_PRO_TENANT_SLUG;
expectedTenantId: string;
expectedDatabaseName: string;
expectedDatabaseHost: string;
expectedStorageBucket: string;
expectedStorageEndpoint: string;
};
type ApplySeedCommand = {
mode: "apply";
tenantSlug: typeof DEMO_PRO_TENANT_SLUG;
userPassword: string;
expectedTenantId: string;
expectedDatabaseName: string;
expectedDatabaseHost: string;
expectedStorageBucket: string;
expectedStorageEndpoint: string;
};
export type SeedCommand = NonApplySeedCommand | CleanupSeedCommand | ApplySeedCommand;
type SeedEnvironment = Readonly<Record<string, string | undefined>>;
const modeArguments = new Map<string, SeedMode>([
["--dry-run", "dry-run"],
["--apply", "apply"],
["--verify", "verify"],
["--cleanup", "cleanup"],
]);
function parseSingleValueArgument(argv: readonly string[], name: string): string | undefined {
const prefix = `${name}=`;
const values = argv.filter((argument) => argument.startsWith(prefix)).map((argument) => argument.slice(prefix.length));
if (values.length > 1) {
throw new Error(`demo-pro seed: ${name} may only be provided once`);
}
return values[0];
}
function parseMode(argv: readonly string[]): SeedMode {
const modes = argv.flatMap((argument) => {
const mode = modeArguments.get(argument);
return mode ? [mode] : [];
});
if (modes.length > 1) {
throw new Error("demo-pro seed: provide exactly one mode");
}
return modes[0] ?? "dry-run";
}
function assertKnownArguments(argv: readonly string[]): void {
for (const argument of argv) {
if (modeArguments.has(argument) || argument.startsWith("--confirm=") || argument.startsWith("--tenant=")) {
continue;
}
throw new Error("demo-pro seed: unknown argument");
}
}
function assertTargetTenant(argv: readonly string[]): void {
const tenantSlug = parseSingleValueArgument(argv, "--tenant");
if (tenantSlug !== undefined && tenantSlug !== DEMO_PRO_TENANT_SLUG) {
throw new Error(`demo-pro seed: target tenant must be ${DEMO_PRO_TENANT_SLUG}`);
}
}
function assertStagingEnvironment(env: SeedEnvironment): void {
if (env.SENTRY_ENVIRONMENT?.trim() !== "staging") {
throw new Error("demo-pro seed: this mode is restricted to the staging environment");
}
}
function assertMutationAllowed(argv: readonly string[], env: SeedEnvironment): void {
const confirmation = parseSingleValueArgument(argv, "--confirm");
if (confirmation !== DEMO_PRO_TENANT_SLUG) {
throw new Error(`demo-pro seed: this mode requires --confirm=${DEMO_PRO_TENANT_SLUG}`);
}
if (env.SEED_DEMO_PRO_ALLOWED?.trim() !== "true") {
throw new Error("demo-pro seed: this mode requires explicit staging seed authorization");
}
if (env.SEED_DEMO_PRO_WORKERS_DRAINED?.trim() !== "true" || env.SEED_DEMO_PRO_OUTBOUND_SANDBOX?.trim() !== "true") {
throw new Error("demo-pro seed: mutation requires drained workers and an outbound staging sandbox");
}
}
/**
* Parses process arguments passed after the script path and enforces the staging-only seed boundary.
* The function has no side effects and never includes environment values in errors or output.
*/
export function parseSeedCommand(argv: readonly string[], env: SeedEnvironment): SeedCommand {
assertKnownArguments(argv);
const mode = parseMode(argv);
assertTargetTenant(argv);
const confirmation = parseSingleValueArgument(argv, "--confirm");
if ((mode === "dry-run" || mode === "verify") && confirmation !== undefined) {
throw new Error("demo-pro seed: --confirm is only valid for apply and cleanup");
}
if (mode === "dry-run") {
return { mode, tenantSlug: DEMO_PRO_TENANT_SLUG };
}
assertStagingEnvironment(env);
if (mode === "verify") {
return { mode, tenantSlug: DEMO_PRO_TENANT_SLUG };
}
assertMutationAllowed(argv, env);
const expectedTenantId = env.SEED_DEMO_PRO_EXPECTED_TENANT_ID?.trim();
const expectedDatabaseName = env.SEED_DEMO_PRO_EXPECTED_DATABASE?.trim();
const expectedDatabaseHost = env.SEED_DEMO_PRO_EXPECTED_DATABASE_HOST?.trim();
const expectedStorageBucket = env.SEED_DEMO_PRO_EXPECTED_STORAGE_BUCKET?.trim();
const expectedStorageEndpoint = env.SEED_DEMO_PRO_EXPECTED_STORAGE_ENDPOINT?.trim();
if (!expectedTenantId || !expectedDatabaseName || !expectedDatabaseHost || !expectedStorageBucket || !expectedStorageEndpoint) {
throw new Error("demo-pro seed: mutation requires the staging tenant, database, and storage binding secrets");
}
if (mode === "cleanup") {
return {
mode,
tenantSlug: DEMO_PRO_TENANT_SLUG,
expectedTenantId,
expectedDatabaseName,
expectedDatabaseHost,
expectedStorageBucket,
expectedStorageEndpoint,
};
}
const userPassword = env.SEED_DEMO_USER_PASSWORD;
if (!userPassword || userPassword.trim().length === 0) {
throw new Error("demo-pro seed: apply requires the staging demo-user password secret");
}
const explicitlyAllowedSharedStagingPassword =
userPassword === "password" && env.SEED_DEMO_PRO_ALLOW_SHARED_STAGING_PASSWORD?.trim() === "true";
if (
!explicitlyAllowedSharedStagingPassword &&
(userPassword.length < 20 || new Set(userPassword).size < 10 || /^(?:passw(?:or)?t|password|demo|hivegrid)/iu.test(userPassword))
) {
throw new Error("demo-pro seed: the staging demo-user password must be a strong random secret of at least 20 characters");
}
return {
mode,
tenantSlug: DEMO_PRO_TENANT_SLUG,
userPassword,
expectedTenantId,
expectedDatabaseName,
expectedDatabaseHost,
expectedStorageBucket,
expectedStorageEndpoint,
};
}
@@ -0,0 +1,195 @@
import { createHash } from "node:crypto";
import { describe, expect, it, vi } from "vitest";
import {
buildSeedFileObjectMetadata,
buildSeedPdfBytes,
deleteDemoProSeedFileObjects,
deleteDemoProTenantFileObjects,
seedFileStorageKey,
seedFileStoragePrefix,
uploadDemoProSeedFileObjects,
verifyDemoProSeedFileObjects,
} from "./file-objects";
const descriptor = {
id: "rheinmain-shk-v1-file-0001",
displayName: "Aufmaß_HG-2026-0042.pdf",
notes: "Projektunterlage zur Wärmepumpenmodernisierung; dem Projekt HG-2026-0042 zugeordnet.",
};
describe("demo-pro seed file objects", () => {
it("builds a deterministic PDF with valid xref offsets and exact metadata", () => {
const bytes = buildSeedPdfBytes(descriptor);
const second = buildSeedPdfBytes(descriptor);
const pdf = new TextDecoder().decode(bytes);
expect(second).toEqual(bytes);
expect(pdf.startsWith("%PDF-1.4\n")).toBe(true);
expect(pdf.endsWith("%%EOF\n")).toBe(true);
const startXref = Number(pdf.match(/startxref\n(\d+)\n%%EOF/u)?.[1]);
expect(pdf.slice(startXref).startsWith("xref\n")).toBe(true);
const xrefEntries = [...pdf.matchAll(/^(\d{10}) 00000 n $/gmu)].map((match) => Number(match[1]));
expect(xrefEntries).toHaveLength(5);
for (const [index, offset] of xrefEntries.entries()) {
expect(pdf.slice(offset).startsWith(`${index + 1} 0 obj\n`)).toBe(true);
}
const metadata = buildSeedFileObjectMetadata(descriptor);
expect(metadata.mimeType).toBe("application/pdf");
expect(metadata.sizeBytes).toBe(bytes.byteLength);
expect(metadata.checksumSha256).toBe(createHash("sha256").update(bytes).digest("hex"));
});
it("uses the mandatory tenant-prefixed Files storage path", () => {
expect(seedFileStorageKey("tenant-staging", descriptor.id)).toBe(`tenants/tenant-staging/files/${descriptor.id}/original`);
expect(seedFileStoragePrefix("tenant-staging")).toBe("tenants/tenant-staging/files/");
expect(() => seedFileStorageKey("tenant/foreign", descriptor.id)).toThrow(/Invalid storage path segment/u);
});
it("uploads all PDFs with bounded concurrency and fails on metadata drift", async () => {
const files = Array.from({ length: 9 }, (_, index) =>
buildSeedFileObjectMetadata({ ...descriptor, id: `${descriptor.id}-${index}`, displayName: `Dokument-${index}.pdf` })
);
let active = 0;
let maxActive = 0;
const putObject = vi.fn(async ({ body }: { body: Uint8Array }) => {
active += 1;
maxActive = Math.max(maxActive, active);
expect(new TextDecoder().decode(body)).toMatch(/^%PDF-1\.4/u);
await Promise.resolve();
active -= 1;
});
await expect(uploadDemoProSeedFileObjects({ tenantId: "tenant-staging", files, concurrency: 3, bucket: "staging-files", putObject })).resolves.toEqual({
bucket: "staging-files",
uploaded: files.length,
});
expect(putObject).toHaveBeenCalledTimes(files.length);
expect(maxActive).toBeLessThanOrEqual(3);
expect(putObject.mock.calls[0]![0]).toMatchObject({
bucket: "staging-files",
key: `tenants/tenant-staging/files/${descriptor.id}-0/original`,
contentType: "application/pdf",
});
await expect(
uploadDemoProSeedFileObjects({
tenantId: "tenant-staging",
files: [{ ...files[0]!, sizeBytes: files[0]!.sizeBytes + 1 }],
bucket: "staging-files",
putObject,
})
).rejects.toThrow(/metadata drifted/u);
});
it("deletes every deterministic object and refuses cleanup without storage", async () => {
const files = [{ id: "file-1" }, { id: "file-2" }];
const deleteObject = vi.fn(async () => undefined);
await expect(
deleteDemoProSeedFileObjects({
tenantId: "tenant-staging",
files,
concurrency: 2,
bucket: "staging-files",
deleteObject,
storageConfigured: () => true,
})
).resolves.toEqual({ bucket: "staging-files", deleted: 2 });
expect(deleteObject).toHaveBeenCalledTimes(2);
await expect(
deleteDemoProSeedFileObjects({
tenantId: "tenant-staging",
files,
bucket: "staging-files",
deleteObject,
storageConfigured: () => false,
})
).rejects.toThrow(/storage provider is not configured/u);
});
it("downloads and verifies every uploaded object against its exact checksum", async () => {
const file = buildSeedFileObjectMetadata(descriptor);
const bytes = buildSeedPdfBytes(file);
let storedBytes = bytes;
const send = vi.fn(async (command: unknown) => {
if ((command as { constructor: { name: string } }).constructor.name === "ListObjectsV2Command") {
return { Contents: [{ Key: seedFileStorageKey("tenant-staging", file.id) }], IsTruncated: false };
}
return {
ContentLength: storedBytes.byteLength,
Body: { transformToByteArray: async () => storedBytes },
};
});
await expect(
verifyDemoProSeedFileObjects({
tenantId: "tenant-staging",
files: [file],
bucket: "staging-files",
client: { send },
})
).resolves.toEqual({ bucket: "staging-files", verified: 1 });
expect(send.mock.calls.map(([command]) => command.constructor.name)).toEqual(["ListObjectsV2Command", "GetObjectCommand"]);
const corrupted = new Uint8Array(bytes);
corrupted[20] = corrupted[20]! ^ 1;
storedBytes = corrupted;
await expect(
verifyDemoProSeedFileObjects({
tenantId: "tenant-staging",
files: [file],
bucket: "staging-files",
client: { send },
})
).rejects.toThrow(/metadata drifted/u);
});
it("fails verification when the managed prefix contains an extra object", async () => {
const file = buildSeedFileObjectMetadata(descriptor);
const send = vi.fn(async () => ({
Contents: [{ Key: seedFileStorageKey("tenant-staging", file.id) }, { Key: "tenants/tenant-staging/files/orphan/original" }],
IsTruncated: false,
}));
await expect(
verifyDemoProSeedFileObjects({
tenantId: "tenant-staging",
files: [file],
bucket: "staging-files",
client: { send },
})
).rejects.toThrow(/unexpected storage object/u);
});
it("removes every object below the managed tenant file prefix", async () => {
const send = vi
.fn()
.mockResolvedValueOnce({
Contents: [{ Key: "tenants/tenant-staging/files/file-1/original" }, { Key: "tenants/tenant-staging/files/orphan/thumb.webp" }],
IsTruncated: true,
})
.mockResolvedValueOnce({ Errors: [] })
.mockResolvedValueOnce({
Contents: [{ Key: "tenants/tenant-staging/files/file-3/original" }],
IsTruncated: false,
})
.mockResolvedValueOnce({ Errors: [] })
.mockResolvedValueOnce({ Contents: [], IsTruncated: false });
await expect(deleteDemoProTenantFileObjects({ tenantId: "tenant-staging", bucket: "staging-files", client: { send } })).resolves.toEqual({
bucket: "staging-files",
deleted: 3,
});
expect(send.mock.calls.map(([command]) => command.constructor.name)).toEqual([
"ListObjectsV2Command",
"DeleteObjectsCommand",
"ListObjectsV2Command",
"DeleteObjectsCommand",
"ListObjectsV2Command",
]);
});
});
@@ -0,0 +1,357 @@
import { createHash } from "node:crypto";
import { DeleteObjectsCommand, GetObjectCommand, ListObjectsV2Command, S3Client } from "@aws-sdk/client-s3";
import { loadRequiredWebConfig } from "@hivegrid/config";
import { buildFileStorageKeys } from "@hivegrid/storage";
import {
deleteFile,
hasStorageCredentials,
putBufferAsFile,
resolveStorageBinding,
resolveStorageBucket,
} from "../../apps/web/app/utils/integrations/storageService";
const DEFAULT_STORAGE_CONCURRENCY = 12;
const PDF_CONTENT_TYPE = "application/pdf";
const encoder = new TextEncoder();
export type SeedFileObjectDescriptor = {
id: string;
displayName: string;
notes: string;
};
export type SeedFileObjectMetadata = SeedFileObjectDescriptor & {
mimeType: string;
sizeBytes: number;
checksumSha256: string;
};
type PersistedSeedFileObject = SeedFileObjectDescriptor & {
mimeType: string;
sizeBytes: number;
checksumSha256: string;
};
type PutObject = (input: { bucket: string; key: string; body: Uint8Array; contentType?: string }) => Promise<unknown>;
type DeleteObject = (input: { bucket: string; key: string }) => Promise<unknown>;
type SeedS3Client = {
send(command: unknown): Promise<unknown>;
};
function printableAscii(value: string): string {
return value
.normalize("NFKD")
.replace(/[\u0300-\u036f]/gu, "")
.replace(/[^\x20-\x7E]/gu, "?")
.replace(/\s+/gu, " ")
.trim();
}
function escapePdfLiteral(value: string): string {
return printableAscii(value).replace(/([\\()])/gu, "\\$1");
}
function wrapText(value: string, maxLength = 72): string[] {
const words = printableAscii(value).split(" ").filter(Boolean);
const lines: string[] = [];
let line = "";
for (const word of words) {
if (line.length === 0) {
line = word;
continue;
}
if (line.length + word.length + 1 <= maxLength) {
line += ` ${word}`;
continue;
}
lines.push(line);
line = word;
}
if (line.length > 0) lines.push(line);
return lines.length > 0 ? lines : ["Projektunterlage"];
}
function byteLength(value: string): number {
return encoder.encode(value).byteLength;
}
/** Builds a deterministic, single-page PDF whose xref offsets match its exact bytes. */
export function buildSeedPdfBytes(file: SeedFileObjectDescriptor): Uint8Array {
const title = escapePdfLiteral(file.displayName);
const detailLines = wrapText(file.notes).slice(0, 6).map(escapePdfLiteral);
const content = [
"BT",
"/F1 18 Tf",
"72 770 Td",
`(${title}) Tj`,
"/F1 11 Tf",
...detailLines.flatMap((line) => ["0 -24 Td", `(${line}) Tj`]),
"0 -36 Td",
`(Dokument-ID: ${escapePdfLiteral(file.id)}) Tj`,
"ET",
"",
].join("\n");
const objects = [
"<< /Type /Catalog /Pages 2 0 R >>",
"<< /Type /Pages /Kids [3 0 R] /Count 1 >>",
"<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595 842] /Resources << /Font << /F1 4 0 R >> >> /Contents 5 0 R >>",
"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>",
`<< /Length ${byteLength(content)} >>\nstream\n${content}endstream`,
];
let pdf = "%PDF-1.4\n% HiveGrid generated staging document\n";
const offsets = [0];
for (const [index, object] of objects.entries()) {
offsets.push(byteLength(pdf));
pdf += `${index + 1} 0 obj\n${object}\nendobj\n`;
}
const xrefOffset = byteLength(pdf);
pdf += `xref\n0 ${objects.length + 1}\n`;
pdf += "0000000000 65535 f \n";
pdf += offsets
.slice(1)
.map((offset) => `${String(offset).padStart(10, "0")} 00000 n \n`)
.join("");
pdf += `trailer\n<< /Size ${objects.length + 1} /Root 1 0 R >>\nstartxref\n${xrefOffset}\n%%EOF\n`;
return encoder.encode(pdf);
}
export function buildSeedFileObjectMetadata(file: SeedFileObjectDescriptor): SeedFileObjectMetadata {
const bytes = buildSeedPdfBytes(file);
return {
...file,
mimeType: PDF_CONTENT_TYPE,
sizeBytes: bytes.byteLength,
checksumSha256: createHash("sha256").update(bytes).digest("hex"),
};
}
export function seedFileStorageKey(tenantId: string, fileId: string): string {
return buildFileStorageKeys(tenantId, fileId).original;
}
export function seedFileStoragePrefix(tenantId: string): string {
const probe = seedFileStorageKey(tenantId, "seed-prefix-probe");
return probe.slice(0, -"seed-prefix-probe/original".length);
}
function createSeedS3Client(): SeedS3Client {
const binding = resolveStorageBinding();
const { storage } = loadRequiredWebConfig();
if (binding.provider !== "s3" || !storage.endpoint || !storage.region || !storage.accessKeyId || !storage.secretAccessKey) {
throw new Error("demo-pro seed files: complete S3 staging storage configuration is required");
}
return new S3Client({
endpoint: storage.endpoint,
region: storage.region,
credentials: {
accessKeyId: storage.accessKeyId,
secretAccessKey: storage.secretAccessKey,
sessionToken: storage.sessionToken,
},
forcePathStyle: storage.forcePathStyle?.toLowerCase() === "true",
}) as unknown as SeedS3Client;
}
async function storageBodyBytes(body: unknown): Promise<Uint8Array> {
if (!body || typeof (body as { transformToByteArray?: unknown }).transformToByteArray !== "function") {
throw new Error("demo-pro seed files: storage object body is unreadable");
}
return (body as { transformToByteArray(): Promise<Uint8Array> }).transformToByteArray();
}
function assertConcurrency(concurrency: number): void {
if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 64) {
throw new Error("demo-pro seed files: concurrency must be an integer between 1 and 64");
}
}
async function forEachConcurrent<T>(items: readonly T[], concurrency: number, worker: (item: T) => Promise<void>): Promise<void> {
assertConcurrency(concurrency);
let nextIndex = 0;
let failed = false;
let failure: unknown;
const workers = Array.from({ length: Math.min(concurrency, items.length) }, async () => {
while (!failed && nextIndex < items.length) {
const index = nextIndex;
nextIndex += 1;
try {
await worker(items[index]!);
} catch (error) {
if (!failed) failure = error;
failed = true;
}
}
});
await Promise.all(workers);
if (failed) throw failure;
}
function assertMetadataMatches(file: PersistedSeedFileObject, bytes: Uint8Array): void {
const checksumSha256 = createHash("sha256").update(bytes).digest("hex");
if (file.mimeType !== PDF_CONTENT_TYPE || file.sizeBytes !== bytes.byteLength || file.checksumSha256 !== checksumSha256) {
throw new Error(`demo-pro seed files: generated PDF metadata drifted for ${file.id}`);
}
}
export async function uploadDemoProSeedFileObjects({
tenantId,
files,
concurrency = DEFAULT_STORAGE_CONCURRENCY,
bucket = resolveStorageBucket(),
putObject = putBufferAsFile,
}: {
tenantId: string;
files: readonly PersistedSeedFileObject[];
concurrency?: number;
bucket?: string;
putObject?: PutObject;
}): Promise<{ bucket: string; uploaded: number }> {
await forEachConcurrent(files, concurrency, async (file) => {
const bytes = buildSeedPdfBytes(file);
assertMetadataMatches(file, bytes);
await putObject({
bucket,
key: seedFileStorageKey(tenantId, file.id),
body: bytes,
contentType: PDF_CONTENT_TYPE,
});
});
return { bucket, uploaded: files.length };
}
export async function verifyDemoProSeedFileObjects({
tenantId,
files,
concurrency = DEFAULT_STORAGE_CONCURRENCY,
bucket = resolveStorageBucket(),
client = createSeedS3Client(),
}: {
tenantId: string;
files: readonly PersistedSeedFileObject[];
concurrency?: number;
bucket?: string;
client?: SeedS3Client;
}): Promise<{ bucket: string; verified: number }> {
const prefix = seedFileStoragePrefix(tenantId);
const expectedKeys = new Set(files.map((file) => seedFileStorageKey(tenantId, file.id)));
if (expectedKeys.size !== files.length) {
throw new Error("demo-pro seed files: expected storage keys are not unique");
}
const observedKeys = new Set<string>();
let continuationToken: string | undefined;
do {
const page = (await client.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix, ContinuationToken: continuationToken, MaxKeys: 1_000 }))) as {
Contents?: Array<{ Key?: string }>;
IsTruncated?: boolean;
NextContinuationToken?: string;
};
for (const object of page.Contents ?? []) {
if (!object.Key) throw new Error("demo-pro seed files: storage listing returned an object without a key");
if (!object.Key.startsWith(prefix)) {
throw new Error("demo-pro seed files: storage listing returned a key outside the tenant file prefix");
}
if (!expectedKeys.has(object.Key)) {
throw new Error(`demo-pro seed files: unexpected storage object ${object.Key}`);
}
if (observedKeys.has(object.Key)) {
throw new Error(`demo-pro seed files: storage listing returned duplicate object ${object.Key}`);
}
observedKeys.add(object.Key);
}
if (page.IsTruncated && !page.NextContinuationToken) {
throw new Error("demo-pro seed files: truncated storage listing has no continuation token");
}
continuationToken = page.IsTruncated ? page.NextContinuationToken : undefined;
} while (continuationToken);
for (const expectedKey of expectedKeys) {
if (!observedKeys.has(expectedKey)) throw new Error(`demo-pro seed files: missing storage object ${expectedKey}`);
}
await forEachConcurrent(files, concurrency, async (file) => {
const result = (await client.send(new GetObjectCommand({ Bucket: bucket, Key: seedFileStorageKey(tenantId, file.id) }))) as {
Body?: unknown;
ContentLength?: number;
};
const bytes = await storageBodyBytes(result.Body);
assertMetadataMatches(file, bytes);
if (result.ContentLength !== undefined && result.ContentLength !== bytes.byteLength) {
throw new Error(`demo-pro seed files: storage size drifted for ${file.id}`);
}
});
return { bucket, verified: files.length };
}
export async function deleteDemoProTenantFileObjects({
tenantId,
bucket = resolveStorageBucket(),
client = createSeedS3Client(),
}: {
tenantId: string;
bucket?: string;
client?: SeedS3Client;
}): Promise<{ bucket: string; deleted: number }> {
const prefix = seedFileStoragePrefix(tenantId);
let deleted = 0;
let previousFirstKey: string | undefined;
while (true) {
const page = (await client.send(new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix, MaxKeys: 1_000 }))) as {
Contents?: Array<{ Key?: string }>;
IsTruncated?: boolean;
NextContinuationToken?: string;
};
const pageKeys = (page.Contents ?? []).map(({ Key }) => {
if (!Key) throw new Error("demo-pro seed files: storage listing returned an object without a key");
return Key;
});
if (pageKeys.some((key) => !key.startsWith(prefix))) {
throw new Error("demo-pro seed files: storage listing returned a key outside the tenant file prefix");
}
if (pageKeys.length > 1_000 || new Set(pageKeys).size !== pageKeys.length) {
throw new Error("demo-pro seed files: storage listing returned an invalid cleanup page");
}
if (pageKeys.length === 0) {
if (page.IsTruncated) throw new Error("demo-pro seed files: truncated storage listing returned no objects");
break;
}
if (pageKeys[0] === previousFirstKey) {
throw new Error("demo-pro seed files: storage prefix cleanup made no progress");
}
previousFirstKey = pageKeys[0];
const result = (await client.send(
new DeleteObjectsCommand({
Bucket: bucket,
Delete: { Objects: pageKeys.map((Key) => ({ Key })), Quiet: true },
})
)) as { Errors?: unknown[] };
if ((result.Errors?.length ?? 0) > 0) throw new Error("demo-pro seed files: storage prefix cleanup failed");
deleted += pageKeys.length;
}
return { bucket, deleted };
}
export async function deleteDemoProSeedFileObjects({
tenantId,
files,
concurrency = DEFAULT_STORAGE_CONCURRENCY,
bucket = resolveStorageBucket(),
deleteObject = deleteFile,
storageConfigured = hasStorageCredentials,
}: {
tenantId: string;
files: readonly Pick<PersistedSeedFileObject, "id">[];
concurrency?: number;
bucket?: string;
deleteObject?: DeleteObject;
storageConfigured?: () => boolean;
}): Promise<{ bucket: string; deleted: number }> {
if (!storageConfigured()) throw new Error("demo-pro seed files: storage provider is not configured");
await forEachConcurrent(files, concurrency, async (file) => {
await deleteObject({ bucket, key: seedFileStorageKey(tenantId, file.id) });
});
return { bucket, deleted: files.length };
}
@@ -0,0 +1,170 @@
import { createHash } from "node:crypto";
import { describe, expect, it } from "vitest";
import { LEAD_OUTCOME_COUNTS, OFFICE_ROLE_COUNTS, PROJECT_TYPE_COUNTS } from "./catalog";
import { generateDemoProSeed, validateDemoProSeedGraph } from "./generator";
import { DEMO_PRO_SEED_NAMESPACE } from "./types";
function frequencies(values: readonly string[]): Record<string, number> {
return values.reduce<Record<string, number>>((result, value) => {
result[value] = (result[value] ?? 0) + 1;
return result;
}, {});
}
describe("demo-pro Rhein-Main seed generator", () => {
it("generates the exact employee structure with realistic odd staffing and crews", () => {
const graph = generateDemoProSeed();
const officeEmployees = graph.employees.filter((employee) => employee.seatCategory === "office");
const fieldEmployees = graph.employees.filter((employee) => employee.seatCategory === "field");
expect(graph.employees).toHaveLength(50);
expect(officeEmployees).toHaveLength(17);
expect(fieldEmployees).toHaveLength(33);
expect(frequencies(officeEmployees.map((employee) => employee.role))).toEqual(
Object.fromEntries(OFFICE_ROLE_COUNTS.map(({ role, count }) => [role, count]))
);
expect(graph.crews).toHaveLength(16);
expect(frequencies(graph.crews.map((crew) => String(crew.memberEmployeeIds.length)))).toEqual({ "2": 15, "3": 1 });
expect(new Set(graph.crews.flatMap((crew) => crew.memberEmployeeIds)).size).toBe(33);
expect(fieldEmployees.every((employee) => graph.crews.some((crew) => crew.id === employee.crewId && crew.memberEmployeeIds.includes(employee.id)))).toBe(
true
);
});
it("keeps every globally persisted v1 employee identity stable across staffing changes", () => {
const employees = generateDemoProSeed().employees;
const serializedIdentities = employees.map(({ id, firstName, lastName, email }) => [id, firstName, lastName, email].join("|")).join("\n");
expect(createHash("sha256").update(serializedIdentities).digest("hex")).toBe("507aaa29467a9b830d447552af41071aa0e1bd109257c9c41dead3e7eccb5877");
expect(employees.slice(16, 21).map(({ id, firstName, lastName, email, seatCategory }) => ({ id, firstName, lastName, email, seatCategory }))).toEqual([
{
id: "rheinmain-shk-v1-employee-0017",
firstName: "Bianca",
lastName: "Schmitz",
email: "bianca.schmitz.17@mitarbeiter.example.test",
seatCategory: "office",
},
{
id: "rheinmain-shk-v1-employee-0018",
firstName: "Dennis",
lastName: "Köhler",
email: "dennis.kohler.18@mitarbeiter.example.test",
seatCategory: "field",
},
{
id: "rheinmain-shk-v1-employee-0019",
firstName: "Heike",
lastName: "Hoffmann",
email: "heike.hoffmann.19@mitarbeiter.example.test",
seatCategory: "field",
},
{
id: "rheinmain-shk-v1-employee-0020",
firstName: "Oliver",
lastName: "Schröder",
email: "oliver.schroder.20@mitarbeiter.example.test",
seatCategory: "field",
},
{
id: "rheinmain-shk-v1-employee-0021",
firstName: "Miriam",
lastName: "Wagner",
email: "miriam.wagner.21@mitarbeiter.example.test",
seatCategory: "field",
},
]);
});
it("builds the full realistic contact and project volume", () => {
const graph = generateDemoProSeed();
expect(graph.organizations).toHaveLength(247);
expect(graph.persons).toHaveLength(536);
expect(graph.contactRelations).toHaveLength(421);
expect(graph.projects).toHaveLength(537);
expect(frequencies(graph.projects.map((project) => project.projectType))).toEqual(PROJECT_TYPE_COUNTS);
expect(new Set(graph.organizations.map((organization) => organization.branche)).size).toBeGreaterThanOrEqual(12);
expect(new Set(graph.persons.map((person) => `${person.firstName} ${person.lastName}`)).size).toBeGreaterThan(100);
expect(graph.projects.every((project) => project.description.length > 100 && project.contacts.length >= 3)).toBe(true);
expect(
graph.organizations.every((organization) => {
const locationToken = organization.address.ort.replace(" am Main", "").replace(" vor der Höhe", "");
return organization.orgName.includes(locationToken);
})
).toBe(true);
});
it("uses the requested exact lead outcomes and complete conversion links", () => {
const graph = generateDemoProSeed();
const converted = graph.leads.filter((lead) => lead.outcome === "converted");
expect(graph.leads).toHaveLength(193);
expect(frequencies(graph.leads.map((lead) => lead.outcome))).toEqual(LEAD_OUTCOME_COUNTS);
expect(converted).toHaveLength(116);
expect(converted.every((lead) => lead.linkedContactId && lead.convertedProjectId && lead.convertedAt)).toBe(true);
expect(graph.projects.filter((project) => project.convertedFromLeadId)).toHaveLength(116);
expect(
converted.every((lead) => {
const project = graph.projects.find(({ id }) => id === lead.convertedProjectId)!;
return new Date(lead.createdAt) < new Date(lead.convertedAt!) && new Date(lead.convertedAt!) <= new Date(project.createdAt);
})
).toBe(true);
expect(graph.leads.every((lead) => !lead.lostAt || new Date(lead.lostAt) <= new Date(graph.referenceDate))).toBe(true);
});
it("keeps every project lifecycle chronologically plausible", () => {
const graph = generateDemoProSeed();
const referenceDate = new Date(graph.referenceDate);
expect(graph.projects.every((project) => !project.startDate || new Date(project.createdAt) < new Date(project.startDate))).toBe(true);
expect(graph.projects.every((project) => new Date(project.createdAt) < new Date(project.deadline))).toBe(true);
expect(graph.projects.every((project) => !project.startDate || new Date(project.startDate) < new Date(project.deadline))).toBe(true);
expect(
graph.projects.every((project) => !project.wonAt || (new Date(project.createdAt) < new Date(project.wonAt) && new Date(project.wonAt) <= referenceDate))
).toBe(true);
expect(
graph.projects.every(
(project) => !project.lostAt || (new Date(project.createdAt) < new Date(project.lostAt) && new Date(project.lostAt) <= referenceDate)
)
).toBe(true);
});
it("keeps every external contact channel non-routable and every ID namespaced", () => {
const graph = generateDemoProSeed();
const ids = [
...graph.employees.map(({ id }) => id),
...graph.crews.map(({ id }) => id),
...graph.organizations.map(({ id }) => id),
...graph.persons.map(({ id }) => id),
...graph.contactRelations.map(({ id }) => id),
...graph.projects.map(({ id }) => id),
...graph.leads.map(({ id }) => id),
];
const emails = [
...graph.employees.map(({ email }) => email),
...graph.organizations.flatMap((organization) => [organization.email, ...organization.additionalEmails.map(({ value }) => value)]),
...graph.persons.flatMap((person) => [person.email, ...person.additionalEmails.map(({ value }) => value)]),
...graph.leads.map(({ email }) => email),
];
const phones = [
...graph.employees.map(({ phone }) => phone),
...graph.organizations.flatMap((organization) => [organization.phone, ...organization.additionalPhones.map(({ value }) => value)]),
...graph.persons.flatMap((person) => [person.phone, ...person.additionalPhones.map(({ value }) => value)]),
...graph.leads.map(({ phone }) => phone),
];
expect(ids.every((id) => id.startsWith(`${DEMO_PRO_SEED_NAMESPACE}-`))).toBe(true);
expect(new Set(ids).size).toBe(ids.length);
expect(emails.every((email) => email.endsWith(".example.test"))).toBe(true);
expect(phones.every((phone) => /^\+496990009\d{3}$/.test(phone))).toBe(true);
});
it("is byte-for-byte deterministic and passes its integrity validator", () => {
const first = generateDemoProSeed();
const second = generateDemoProSeed();
expect(second).toEqual(first);
expect(validateDemoProSeedGraph(first)).toEqual({ valid: true, errors: [] });
});
});
@@ -0,0 +1,628 @@
import {
EMPLOYEE_IDENTITIES_V1,
FEMALE_FIRST_NAMES,
LAST_NAMES,
LEAD_OUTCOME_COUNTS,
LOCATIONS,
MALE_FIRST_NAMES,
OFFICE_ROLE_COUNTS,
ORDER_STAGE_COUNTS,
ORGANIZATION_ROOTS,
ORGANIZATION_SECTORS,
PROJECT_TYPE_COUNTS,
PROJECT_TYPE_DETAILS,
REFERENCE_DATE,
SALES_STAGE_COUNTS,
STREET_PREFIXES,
STREET_SUFFIXES,
} from "./catalog";
import {
DEMO_PRO_SEED_NAMESPACE,
type DemoProSeedGraph,
type EmployeeRole,
type LeadOutcome,
type SeedAddress,
type SeedContactRelation,
type SeedCrew,
type SeedEmployee,
type SeedLead,
type SeedOrganization,
type SeedPerson,
type SeedProject,
type SeedValidationResult,
} from "./types";
const ID_PREFIX = `${DEMO_PRO_SEED_NAMESPACE}-`;
const OFFICE_EMPLOYEE_COUNT = 17;
const FIELD_EMPLOYEE_COUNT = 33;
const TWO_PERSON_CREW_COUNT = 15;
const CREW_COUNT = 16;
const ORGANIZATION_COUNT = 247;
const PERSON_COUNT = 536;
const BUSINESS_PERSON_COUNT = 421;
const PROJECT_COUNT = 537;
const LEAD_COUNT = 193;
function deterministicShuffle<T>(values: readonly T[], seed: number): T[] {
const result = [...values];
let state = seed >>> 0;
for (let index = result.length - 1; index > 0; index -= 1) {
state = (Math.imul(state, 1664525) + 1013904223) >>> 0;
const swapIndex = state % (index + 1);
[result[index], result[swapIndex]] = [result[swapIndex]!, result[index]!];
}
return result;
}
function seedId(kind: string, index: number): string {
return `${ID_PREFIX}${kind}-${String(index + 1).padStart(4, "0")}`;
}
function dramaPhone(index: number): string {
if (index < 0 || index > 999) {
throw new Error(`Drama-number index ${index} is outside the reserved 000-999 range.`);
}
return `+496990009${String(index).padStart(3, "0")}`;
}
function emailPart(value: string): string {
return value
.normalize("NFD")
.replace(/[\u0300-\u036f]/g, "")
.replace(/ß/g, "ss")
.toLowerCase()
.replace(/[^a-z0-9]+/g, ".")
.replace(/^\.|\.$/g, "");
}
function addDays(isoDate: string, days: number): string {
const date = new Date(isoDate);
date.setUTCDate(date.getUTCDate() + days);
return date.toISOString();
}
function earlierDate(first: string, second: string): string {
return new Date(first) <= new Date(second) ? first : second;
}
function laterDate(first: string, second: string): string {
return new Date(first) >= new Date(second) ? first : second;
}
function money(value: number): string {
return value.toFixed(2);
}
function makeAddress(index: number): SeedAddress {
const location = LOCATIONS[(index * 7) % LOCATIONS.length]!;
const prefix = STREET_PREFIXES[(index * 11) % STREET_PREFIXES.length]!;
const suffix = STREET_SUFFIXES[(index * 5) % STREET_SUFFIXES.length]!;
const baseNumber = 1 + ((index * 17) % 184);
const numberSuffix = index % 19 === 0 ? "a" : index % 31 === 0 ? "b" : "";
return {
strasse: `${prefix}${suffix}`,
hausnummer: `${baseNumber}${numberSuffix}`,
plz: location.plz,
ort: location.ort,
land: "DE",
};
}
function employeeGroups(role: EmployeeRole, crewName?: string): string[] {
const groupByRole: Record<EmployeeRole, string> = {
Geschäftsführer: "Geschäftsführung",
Vertriebsleiter: "Vertrieb",
Vertriebler: "Vertrieb",
"Büro/Backoffice": "Backoffice",
Marketing: "Marketing",
"Projektleiter/Bauleiter": "Projektleitung",
Monteur: "Montage",
};
return crewName ? [groupByRole[role], crewName] : [groupByRole[role]];
}
function generateEmployees(): { employees: SeedEmployee[]; crews: SeedCrew[] } {
const employees: SeedEmployee[] = [];
const officeRoles = OFFICE_ROLE_COUNTS.flatMap(({ role, count, jobTitle }) => Array.from({ length: count }, () => ({ role, jobTitle })));
officeRoles.forEach(({ role, jobTitle }, index) => {
const { firstName, lastName } = EMPLOYEE_IDENTITIES_V1[index]!;
employees.push({
id: seedId("employee", index),
firstName,
lastName,
email: `${emailPart(firstName)}.${emailPart(lastName)}.${String(index + 1).padStart(2, "0")}@mitarbeiter.example.test`,
phone: dramaPhone(index),
role,
jobTitle,
seatCategory: "office",
groupNames: employeeGroups(role),
crewId: null,
active: true,
locale: "de",
});
});
for (let fieldIndex = 0; fieldIndex < FIELD_EMPLOYEE_COUNT; fieldIndex += 1) {
const index = OFFICE_EMPLOYEE_COUNT + fieldIndex;
const { firstName, lastName } = EMPLOYEE_IDENTITIES_V1[index]!;
const crewIndex = Math.min(Math.floor(fieldIndex / 2), CREW_COUNT - 1);
const crewId = seedId("crew", crewIndex);
const crewName = `Montageteam ${String(crewIndex + 1).padStart(2, "0")}`;
employees.push({
id: seedId("employee", index),
firstName,
lastName,
email: `${emailPart(firstName)}.${emailPart(lastName)}.${String(index + 1).padStart(2, "0")}@mitarbeiter.example.test`,
phone: dramaPhone(index),
role: "Monteur",
jobTitle: fieldIndex % 6 === 0 ? "Kundendiensttechniker SHK" : fieldIndex % 4 === 0 ? "Anlagenmechaniker SHK, Obermonteur" : "Anlagenmechaniker SHK",
seatCategory: "field",
groupNames: employeeGroups("Monteur", crewName),
crewId,
active: true,
locale: "de",
});
}
const projectManagers = employees.filter((employee) => employee.role === "Projektleiter/Bauleiter");
const crews: SeedCrew[] = Array.from({ length: CREW_COUNT }, (_, index) => {
const crewId = seedId("crew", index);
return {
id: crewId,
name: `Montageteam ${String(index + 1).padStart(2, "0")}`,
memberEmployeeIds: employees.filter((employee) => employee.crewId === crewId).map(({ id }) => id),
projectManagerEmployeeId: projectManagers[index % projectManagers.length]!.id,
};
});
return { employees, crews };
}
function organizationLegalForm(index: number, sector: string): Pick<SeedOrganization, "orgMerkmal"> & { suffix: string } {
if (sector === "Kommunale Einrichtung") {
return { orgMerkmal: "oeffentliche_einrichtung", suffix: "Eigenbetrieb" };
}
if (index % 11 === 0) {
return { orgMerkmal: "kg", suffix: "GmbH & Co. KG" };
}
if (index % 7 === 0) {
return { orgMerkmal: "sonstige", suffix: "eG" };
}
return { orgMerkmal: "gmbh", suffix: "GmbH" };
}
function generateOrganizations(employees: readonly SeedEmployee[]): SeedOrganization[] {
const owners = employees.filter((employee) => employee.role === "Vertriebler" || employee.role === "Büro/Backoffice");
return Array.from({ length: ORGANIZATION_COUNT }, (_, index) => {
const sector = ORGANIZATION_SECTORS[(index * 7) % ORGANIZATION_SECTORS.length]!;
const root = ORGANIZATION_ROOTS[(index * 11) % ORGANIZATION_ROOTS.length]!;
const address = makeAddress(index);
const legalForm = organizationLegalForm(index, sector);
const locationToken = address.ort.replace(" am Main", "").replace(" vor der Höhe", "");
const orgName =
sector === "Kommunale Einrichtung" ? `${root} ${locationToken} ${legalForm.suffix}` : `${root} ${sector} ${locationToken} ${legalForm.suffix}`;
const emailToken = `betrieb-${String(index + 1).padStart(3, "0")}`;
return {
id: seedId("organization", index),
kontaktTyp: "organisation",
orgName,
orgMerkmal: legalForm.orgMerkmal,
branche: sector,
kontaktStatus: index % 5 === 0 ? "kontakt" : index % 3 === 0 ? "kunde" : "bestandskunde",
email: `kontakt@${emailToken}.example.test`,
phone: dramaPhone(50 + index),
additionalEmails: index % 4 === 0 ? [{ value: `rechnung@${emailToken}.example.test`, primaer: false, label: "rechnung" }] : [],
additionalPhones: index % 7 === 0 ? [{ value: dramaPhone(910 + Math.floor(index / 7)), primaer: false, label: "zentrale" }] : [],
address,
language: "de",
ownerEmployeeId: owners[index % owners.length]!.id,
tags: sector === "Hausverwaltung" || sector === "Wohnungswirtschaft" ? ["B2B", "Rahmenkunde"] : index % 4 === 0 ? ["B2B", "Wartungsvertrag"] : ["B2B"],
};
});
}
function generatePersons(employees: readonly SeedEmployee[], organizations: readonly SeedOrganization[]): SeedPerson[] {
const owners = employees.filter((employee) => employee.role === "Vertriebler" || employee.role === "Büro/Backoffice");
return Array.from({ length: PERSON_COUNT }, (_, index) => {
const female = index % 2 === 0;
const firstNames = female ? FEMALE_FIRST_NAMES : MALE_FIRST_NAMES;
const firstName = firstNames[(Math.floor(index / 2) * 7 + 3) % firstNames.length]!;
const lastName = LAST_NAMES[(index * 11 + 2) % LAST_NAMES.length]!;
const businessContact = index < BUSINESS_PERSON_COUNT;
const address = businessContact ? organizations[index % organizations.length]!.address : makeAddress(400 + index);
const emailToken = `${emailPart(firstName)}.${emailPart(lastName)}.${String(index + 1).padStart(3, "0")}`;
return {
id: seedId("person", index),
kontaktTyp: "privatperson",
firstName,
lastName,
salutation: female ? "Frau" : "Herr",
kontaktStatus: businessContact ? (index % 4 === 0 ? "kunde" : "kontakt") : index % 3 === 0 ? "bestandskunde" : "kunde",
email: `${emailToken}@kunden.example.test`,
phone: dramaPhone(297 + index),
additionalEmails: index % 11 === 0 ? [{ value: `${emailToken}@privat.example.test`, primaer: false, label: "privat" }] : [],
additionalPhones: [],
address,
language: "de",
ownerEmployeeId: owners[(index * 5) % owners.length]!.id,
tags: businessContact ? ["Ansprechpartner"] : index % 5 === 0 ? ["Privatkunde", "Wartung"] : ["Privatkunde"],
};
});
}
function generateContactRelations(): SeedContactRelation[] {
const jobContexts = ["Technische Leitung", "Kaufmännische Leitung", "Objektbetreuung", "Geschäftsführung", "Haustechnik", "Einkauf"] as const;
return Array.from({ length: BUSINESS_PERSON_COUNT }, (_, index) => ({
id: seedId("contact-relation", index),
organizationId: seedId("organization", index % ORGANIZATION_COUNT),
personId: seedId("person", index),
role: index < ORGANIZATION_COUNT ? "hauptkontakt" : index % 4 === 0 ? "sekundaerkontakt" : "mitarbeiter",
context: jobContexts[(index * 5) % jobContexts.length]!,
}));
}
function expandCounts<T extends string>(counts: Readonly<Record<T, number>>): T[] {
return Object.entries(counts).flatMap(([value, count]) => Array.from({ length: count as number }, () => value as T));
}
function projectContactName(projectContacts: SeedProject["contacts"], organizations: readonly SeedOrganization[], persons: readonly SeedPerson[]): string {
const primaryId = projectContacts.find((contact) => contact.primary)?.contactId ?? projectContacts[0]!.contactId;
const organization = organizations.find((contact) => contact.id === primaryId);
if (organization) return organization.orgName.replace(/ (GmbH|GmbH & Co\. KG|eG|Eigenbetrieb)$/, "");
const person = persons.find((contact) => contact.id === primaryId)!;
return `${person.lastName}`;
}
function generateProjects(
employees: readonly SeedEmployee[],
crews: readonly SeedCrew[],
organizations: readonly SeedOrganization[],
persons: readonly SeedPerson[]
): SeedProject[] {
const projectManagers = employees.filter((employee) => employee.role === "Projektleiter/Bauleiter");
const backoffice = employees.filter((employee) => employee.role === "Büro/Backoffice");
const projectTypes = deterministicShuffle(expandCounts(PROJECT_TYPE_COUNTS), 0x524d2026);
const salesStages = deterministicShuffle(expandCounts(SALES_STAGE_COUNTS), 0x53414c45);
const orderStages = deterministicShuffle(expandCounts(ORDER_STAGE_COUNTS), 0x4f524445);
const sources = ["Bestandskunde", "Empfehlung", "Website", "Telefon", "Partner", "Ausschreibung"] as const;
const lostReasons = ["Preisentscheidung", "Zeitfenster nicht passend", "Bestandsanlage wird weiterbetrieben", "Wettbewerber beauftragt"] as const;
return Array.from({ length: PROJECT_COUNT }, (_, index) => {
const projectType = projectTypes[index]!;
const details = PROJECT_TYPE_DETAILS[projectType];
const pipeline = index < salesStages.length ? "sales" : "auftrag";
const stage = pipeline === "sales" ? salesStages[index]! : orderStages[index - salesStages.length]!;
const privateCustomer = (index * 73) % PROJECT_COUNT < 322;
const organization = privateCustomer ? null : organizations[(index * 31) % organizations.length]!;
const person = privateCustomer
? persons[BUSINESS_PERSON_COUNT + ((index * 37) % (PERSON_COUNT - BUSINESS_PERSON_COUNT))]!
: persons[(index * 31) % ORGANIZATION_COUNT]!;
const contacts: SeedProject["contacts"] = organization
? [
{ contactId: organization.id, role: "auftraggeber", primary: true },
{ contactId: organization.id, role: "rechnungsempfaenger", primary: false },
{ contactId: person.id, role: "ansprechpartner", primary: false },
]
: [
{ contactId: person.id, role: "auftraggeber", primary: true },
{ contactId: person.id, role: "bauherr", primary: false },
{ contactId: person.id, role: "rechnungsempfaenger", primary: false },
];
const customerAddress = organization?.address ?? person.address;
const projectAddress = organization && index % 3 !== 0 ? makeAddress(1100 + index) : customerAddress;
const valueSpan = details.maxValue - details.minValue;
const rawValue = details.minValue + ((index * 7919) % (valueSpan + 1));
const roundedValue = rawValue < 5000 ? Math.round(rawValue / 10) * 10 : Math.round(rawValue / 100) * 100;
const duration = details.durationDays[0] + ((index * 11) % (details.durationDays[1] - details.durationDays[0] + 1));
const won = stage === "gewonnen" || stage === "abgeschlossen";
const lost = stage === "verloren" || stage === "storniert";
const desiredStartDate =
pipeline === "sales" && !won
? null
: stage === "abgeschlossen"
? addDays(REFERENCE_DATE, -(duration + 1 + ((index * 17) % 180)))
: stage === "montage"
? addDays(REFERENCE_DATE, -((index * 7) % Math.max(1, duration)))
: stage === "abnahme"
? addDays(REFERENCE_DATE, -Math.max(1, duration - 1))
: stage === "storniert"
? addDays(REFERENCE_DATE, -(2 + (index % 45)))
: addDays(REFERENCE_DATE, 5 + ((index * 13) % 120));
const rawCreatedAt = addDays(REFERENCE_DATE, -((index * 37) % 822));
const createdAt = desiredStartDate ? earlierDate(rawCreatedAt, addDays(desiredStartDate, -(3 + (index % 27)))) : rawCreatedAt;
const startDate = desiredStartDate ? laterDate(desiredStartDate, addDays(createdAt, 1)) : null;
const deadline = startDate ? addDays(startDate, duration) : laterDate(addDays(REFERENCE_DATE, 7 + ((index * 19) % 90)), addDays(createdAt, 7));
const wonAt = won && startDate ? earlierDate(REFERENCE_DATE, laterDate(addDays(createdAt, 1), addDays(startDate, -(2 + (index % 14))))) : null;
const lostAt = lost ? earlierDate(REFERENCE_DATE, addDays(createdAt, 3 + (index % 28))) : null;
const manager = projectManagers[index % projectManagers.length]!;
const primaryCrew = crews[index % crews.length]!;
const crewIds = projectType === "objekt_neubau" && index % 2 === 0 ? [primaryCrew.id, crews[(index + 4) % crews.length]!.id] : [primaryCrew.id];
const contactName = projectContactName(contacts, organizations, persons);
return {
id: seedId("project", index),
projectNumber: `RM-${new Date(createdAt).getUTCFullYear()}-${String(700001 + index)}`,
projectName: `${details.label} ${contactName}`,
description: `${details.descriptions[index % details.descriptions.length]}. Ausführung im Raum ${projectAddress.ort}; Abstimmung, Dokumentation und Einweisung sind im Leistungsumfang berücksichtigt.`,
projectType,
source: sources[(index * 5) % sources.length]!,
priority:
projectType === "reparatur_notdienst" && index % 3 === 0
? "dringend"
: projectType === "objekt_neubau" || index % 11 === 0
? "hoch"
: index % 17 === 0
? "niedrig"
: "normal",
pipeline,
stage,
potentialOrderValue: pipeline === "sales" ? money(roundedValue) : null,
orderVolume: pipeline === "auftrag" || won ? money(roundedValue) : null,
createdAt,
startDate,
deadline,
responsibleEmployeeId: backoffice[index % backoffice.length]!.id,
projectManagerEmployeeId: manager.id,
crewIds,
projectAddress,
invoiceAddress: customerAddress,
clientAddress: customerAddress,
convertedFromLeadId: null,
lostReason: lost ? lostReasons[index % lostReasons.length]! : null,
wonAt,
lostAt,
contacts,
tags:
projectType === "reparatur_notdienst"
? ["Kundendienst", "Zeitkritisch"]
: projectType === "wartung_pruefung"
? ["Wartung"]
: organization
? ["B2B", "Projektgeschäft"]
: ["Privatkunde", "Projektgeschäft"],
};
});
}
function leadMessage(outcome: LeadOutcome, project?: SeedProject): string {
if (outcome === "spam") return "Angebot für Suchmaschinenoptimierung und günstige Firmenkredite. Bitte sofort zurückrufen.";
if (outcome === "converted" && project)
return `Bitte um Beratung und Terminabstimmung für ${PROJECT_TYPE_DETAILS[project.projectType].label.toLowerCase()} am Objekt in ${project.projectAddress.ort}.`;
if (outcome === "offer_lost") return "Vielen Dank für das Angebot. Nach interner Abstimmung haben wir uns für eine andere Ausführung entschieden.";
return "Wir möchten die technische Machbarkeit und einen passenden Vor-Ort-Termin klären. Bitte um Rückmeldung.";
}
function generateLeads(employees: readonly SeedEmployee[], persons: readonly SeedPerson[], projects: SeedProject[]): SeedLead[] {
const salesOwners = employees.filter((employee) => employee.role === "Vertriebler" || employee.role === "Vertriebsleiter");
const outcomes = deterministicShuffle(expandCounts(LEAD_OUTCOME_COUNTS), 0x4c454144);
const sources = ["form", "email", "aircall", "manual", "custom"] as const;
const sourceOrigins = ["Website Kontaktformular", "E-Mail Eingang", "Telefonzentrale", "Manuelle Erfassung", "Partnerportal"] as const;
const disqualifiedReasons = ["Objekt außerhalb des Einsatzgebiets", "Leistungsumfang nicht passend", "Terminwunsch nicht realisierbar"] as const;
let convertedProjectIndex = 0;
let externalPhoneIndex = 833;
return outcomes.map((outcome, index) => {
const convertedProject = outcome === "converted" ? projects[convertedProjectIndex++]! : null;
const linkedPersonId = convertedProject?.contacts.find((contact) => contact.contactId.includes("-person-"))?.contactId ?? null;
const linkedPerson = linkedPersonId ? persons.find((person) => person.id === linkedPersonId)! : null;
const female = index % 2 === 0;
const firstName =
linkedPerson?.firstName ??
(female ? FEMALE_FIRST_NAMES[(index * 3) % FEMALE_FIRST_NAMES.length]! : MALE_FIRST_NAMES[(index * 3) % MALE_FIRST_NAMES.length]!);
const lastName = linkedPerson?.lastName ?? LAST_NAMES[(index * 13) % LAST_NAMES.length]!;
const createdAt = convertedProject ? addDays(convertedProject.createdAt, -3 - (index % 18)) : addDays(REFERENCE_DATE, -((index * 23) % 540));
const contactEmail = linkedPerson?.email ?? `${emailPart(firstName)}.${emailPart(lastName)}.lead-${String(index + 1).padStart(3, "0")}@leads.example.test`;
const contactPhone = linkedPerson?.phone ?? dramaPhone(externalPhoneIndex++);
const id = seedId("lead", index);
if (convertedProject) convertedProject.convertedFromLeadId = id;
return {
id,
outcome,
status: outcome === "spam" ? "spam" : outcome === "converted" ? "converted" : "lost",
source: sources[(index * 7) % sources.length]!,
sourceOrigin: sourceOrigins[(index * 7) % sourceOrigins.length]!,
createdAt,
ownerEmployeeId: salesOwners[index % salesOwners.length]!.id,
firstName,
lastName,
email: contactEmail,
phone: contactPhone,
message: leadMessage(outcome, convertedProject ?? undefined),
furtherProcessingConsent: outcome === "spam" ? "nein" : outcome === "converted" || outcome === "offer_lost" ? "ja" : "unklar",
spamScore: outcome === "spam" ? 85 + (index % 14) : index % 9,
spamReason: outcome === "spam" ? "Honeypot und kommerzielles Spam-Muster erkannt" : null,
isQuarantined: outcome === "spam",
linkedContactId: linkedPerson?.id ?? null,
convertedProjectId: convertedProject?.id ?? null,
convertedAt: convertedProject?.createdAt ?? null,
lostAt: outcome === "disqualified" || outcome === "offer_lost" ? earlierDate(REFERENCE_DATE, addDays(createdAt, 2 + (index % 21))) : null,
disqualifiedReason:
outcome === "disqualified"
? disqualifiedReasons[index % disqualifiedReasons.length]!
: outcome === "offer_lost"
? "Angebot an Wettbewerber vergeben"
: null,
};
});
}
export function generateDemoProSeed(): DemoProSeedGraph {
const { employees, crews } = generateEmployees();
const organizations = generateOrganizations(employees);
const persons = generatePersons(employees, organizations);
const contactRelations = generateContactRelations();
const projects = generateProjects(employees, crews, organizations, persons);
const leads = generateLeads(employees, persons, projects);
const graph: DemoProSeedGraph = {
namespace: DEMO_PRO_SEED_NAMESPACE,
generatedForTenantSlug: "demo-pro-crm",
referenceDate: REFERENCE_DATE,
employees,
crews,
organizations,
persons,
contactRelations,
projects,
leads,
};
const validation = validateDemoProSeedGraph(graph);
if (!validation.valid) {
throw new Error(`Generated demo-pro seed is invalid:\n${validation.errors.join("\n")}`);
}
return graph;
}
function countBy<T extends string>(values: readonly T[]): Record<string, number> {
return values.reduce<Record<string, number>>((counts, value) => {
counts[value] = (counts[value] ?? 0) + 1;
return counts;
}, {});
}
function compareCounts(label: string, actual: Record<string, number>, expected: Readonly<Record<string, number>>, errors: string[]): void {
for (const [key, expectedCount] of Object.entries(expected)) {
if ((actual[key] ?? 0) !== expectedCount) errors.push(`${label} ${key}: expected ${expectedCount}, received ${actual[key] ?? 0}.`);
}
}
export function validateDemoProSeedGraph(graph: DemoProSeedGraph): SeedValidationResult {
const errors: string[] = [];
const expectLength = (label: string, actual: number, expected: number) => {
if (actual !== expected) errors.push(`${label}: expected ${expected}, received ${actual}.`);
};
expectLength("employees", graph.employees.length, 50);
expectLength("office employees", graph.employees.filter((employee) => employee.seatCategory === "office").length, OFFICE_EMPLOYEE_COUNT);
expectLength("field employees", graph.employees.filter((employee) => employee.seatCategory === "field").length, FIELD_EMPLOYEE_COUNT);
expectLength("crews", graph.crews.length, CREW_COUNT);
expectLength("organizations", graph.organizations.length, ORGANIZATION_COUNT);
expectLength("persons", graph.persons.length, PERSON_COUNT);
expectLength("contact relations", graph.contactRelations.length, BUSINESS_PERSON_COUNT);
expectLength("projects", graph.projects.length, PROJECT_COUNT);
expectLength("leads", graph.leads.length, LEAD_COUNT);
compareCounts(
"office role",
countBy(graph.employees.filter((employee) => employee.seatCategory === "office").map((employee) => employee.role)),
Object.fromEntries(OFFICE_ROLE_COUNTS.map(({ role, count }) => [role, count])),
errors
);
compareCounts("project type", countBy(graph.projects.map((project) => project.projectType)), PROJECT_TYPE_COUNTS, errors);
compareCounts("lead outcome", countBy(graph.leads.map((lead) => lead.outcome)), LEAD_OUTCOME_COUNTS, errors);
const allIds = [
...graph.employees.map(({ id }) => id),
...graph.crews.map(({ id }) => id),
...graph.organizations.map(({ id }) => id),
...graph.persons.map(({ id }) => id),
...graph.contactRelations.map(({ id }) => id),
...graph.projects.map(({ id }) => id),
...graph.leads.map(({ id }) => id),
];
if (allIds.some((id) => !id.startsWith(ID_PREFIX))) errors.push(`Every generated ID must start with ${ID_PREFIX}.`);
if (new Set(allIds).size !== allIds.length) errors.push("Generated IDs must be globally unique.");
const projectNumbers = graph.projects.map((project) => project.projectNumber);
if (new Set(projectNumbers).size !== projectNumbers.length) errors.push("Project numbers must be unique.");
if (projectNumbers.some((number) => !/^RM-20\d{2}-7\d{5}$/.test(number))) errors.push("Project numbers must use the RM-YYYY-7xxxxx format.");
const primaryEntities = [...graph.employees, ...graph.organizations, ...graph.persons];
const primaryEmails = primaryEntities.map((entity) => entity.email);
const primaryPhones = primaryEntities.map((entity) => entity.phone);
if (new Set(primaryEmails).size !== primaryEmails.length) errors.push("Primary employee and contact e-mail addresses must be unique.");
if (new Set(primaryPhones).size !== primaryPhones.length) errors.push("Primary employee and contact phone numbers must be unique.");
const allEmails = [
...primaryEmails,
...graph.organizations.flatMap((organization) => organization.additionalEmails.map(({ value }) => value)),
...graph.persons.flatMap((person) => person.additionalEmails.map(({ value }) => value)),
...graph.leads.map((lead) => lead.email),
];
if (allEmails.some((email) => !email.endsWith(".example.test"))) errors.push("Every e-mail address must use an .example.test domain.");
const allPhones = [
...primaryPhones,
...graph.organizations.flatMap((organization) => organization.additionalPhones.map(({ value }) => value)),
...graph.persons.flatMap((person) => person.additionalPhones.map(({ value }) => value)),
...graph.leads.map((lead) => lead.phone),
];
if (allPhones.some((phone) => !/^\+496990009\d{3}$/.test(phone)))
errors.push("Every phone number must use the BNetzA +49 69 90009 000-999 drama-number range.");
const employeeIds = new Set(graph.employees.map(({ id }) => id));
const contactIds = new Set([...graph.organizations.map(({ id }) => id), ...graph.persons.map(({ id }) => id)]);
const crewIds = new Set(graph.crews.map(({ id }) => id));
const projectIds = new Set(graph.projects.map(({ id }) => id));
const personIds = new Set(graph.persons.map(({ id }) => id));
const organizationIds = new Set(graph.organizations.map(({ id }) => id));
const crewMembershipIds = graph.crews.flatMap(({ memberEmployeeIds }) => memberEmployeeIds);
const fieldEmployeeIds = new Set(graph.employees.filter(({ seatCategory }) => seatCategory === "field").map(({ id }) => id));
if (
crewMembershipIds.length !== FIELD_EMPLOYEE_COUNT ||
new Set(crewMembershipIds).size !== FIELD_EMPLOYEE_COUNT ||
crewMembershipIds.some((employeeId) => !fieldEmployeeIds.has(employeeId))
) {
errors.push("Every field employee must belong to exactly one crew.");
}
for (const [index, crew] of graph.crews.entries()) {
const expectedCrewSize = index < TWO_PERSON_CREW_COUNT ? 2 : 3;
if (crew.memberEmployeeIds.length !== expectedCrewSize || new Set(crew.memberEmployeeIds).size !== expectedCrewSize) {
errors.push(`${crew.id} must have exactly ${expectedCrewSize} distinct members.`);
}
if (crew.memberEmployeeIds.some((id) => !employeeIds.has(id))) errors.push(`${crew.id} references an unknown employee.`);
if (!employeeIds.has(crew.projectManagerEmployeeId)) errors.push(`${crew.id} references an unknown project manager.`);
}
for (const employee of graph.employees) {
if (employee.seatCategory === "field" && (!employee.crewId || !crewIds.has(employee.crewId))) {
errors.push(`${employee.id} does not reference a valid crew.`);
}
if (employee.seatCategory === "office" && employee.crewId !== null) errors.push(`${employee.id} must not reference a crew.`);
}
for (const relation of graph.contactRelations) {
if (!organizationIds.has(relation.organizationId) || !personIds.has(relation.personId)) errors.push(`${relation.id} references an unknown contact.`);
}
for (const project of graph.projects) {
if (!employeeIds.has(project.responsibleEmployeeId) || !employeeIds.has(project.projectManagerEmployeeId))
errors.push(`${project.id} references an unknown employee.`);
if (project.crewIds.some((id) => !crewIds.has(id))) errors.push(`${project.id} references an unknown crew.`);
if (project.contacts.some(({ contactId }) => !contactIds.has(contactId))) errors.push(`${project.id} references an unknown contact.`);
if (project.contacts.filter(({ primary }) => primary).length !== 1) errors.push(`${project.id} must have exactly one primary contact.`);
}
for (const lead of graph.leads) {
if (!employeeIds.has(lead.ownerEmployeeId)) errors.push(`${lead.id} references an unknown owner.`);
if (lead.linkedContactId && !personIds.has(lead.linkedContactId)) errors.push(`${lead.id} references an unknown linked contact.`);
if (lead.convertedProjectId && !projectIds.has(lead.convertedProjectId)) errors.push(`${lead.id} references an unknown converted project.`);
if (lead.outcome === "converted" && (!lead.convertedProjectId || !lead.linkedContactId || !lead.convertedAt))
errors.push(`${lead.id} is converted but has an incomplete conversion link.`);
}
const validLocations = new Set(LOCATIONS.map(({ plz, ort }) => `${plz}|${ort}`));
const allAddresses = [
...graph.organizations.map(({ address }) => address),
...graph.persons.map(({ address }) => address),
...graph.projects.flatMap(({ projectAddress, invoiceAddress, clientAddress }) => [projectAddress, invoiceAddress, clientAddress]),
];
if (allAddresses.some(({ plz, ort }) => !validLocations.has(`${plz}|${ort}`)))
errors.push("Every address must use a supported real Rhein-Main place/PLZ pair.");
if (allAddresses.some(({ strasse }) => !STREET_PREFIXES.some((prefix) => strasse.startsWith(prefix))))
errors.push("Every address must use the synthetic street catalog.");
return { valid: errors.length === 0, errors };
}
@@ -0,0 +1,34 @@
import { describe, expect, it, vi } from "vitest";
import { generatedStreetNames, validateGeneratedStreets } from "./geodata";
describe("demo-pro geodata validation", () => {
it("builds the exact deterministic street catalog used by the generator", () => {
const names = generatedStreetNames();
expect(names).toHaveLength(60);
expect(new Set(names).size).toBe(names.length);
});
it("detects collisions against paginated official street responses", async () => {
const collision = generatedStreetNames()[3]!;
const fetchMock = vi.fn(async (url: string | URL | Request) => {
const offset = Number(new URL(String(url)).searchParams.get("offset"));
const features =
offset === 0
? Array.from({ length: 500 }, (_, index) => ({ properties: { text: `Unrelated Street ${index}` } }))
: [{ properties: { text: collision } }];
return new Response(JSON.stringify({ numberMatched: 501, features }), { status: 200 });
});
const report = await validateGeneratedStreets(fetchMock as typeof fetch);
expect(report.collisions).toEqual([collision]);
expect(fetchMock).toHaveBeenCalledTimes(2);
});
it("fails closed on an incomplete successful pagination response", async () => {
const fetchMock = vi.fn(
async () => new Response(JSON.stringify({ numberMatched: 501, features: [{ properties: { text: "Only one" } }] }), { status: 200 })
);
await expect(validateGeneratedStreets(fetchMock as typeof fetch)).rejects.toThrow("incomplete");
});
});
@@ -0,0 +1,95 @@
import { createHash } from "node:crypto";
import { STREET_PREFIXES, STREET_SUFFIXES } from "./catalog";
export const HESSEN_STREET_SOURCE_URL = "https://www.geoportal.hessen.de/spatial-objects/706/collections/ad%3AThoroughfareName/items?f=json&limit=500";
type GeoJsonPage = {
numberMatched?: number;
features?: Array<{ properties?: { text?: unknown } }>;
};
export type GeodataValidationReport = {
sourceUrl: string;
sourceHashSha256: string;
officialStreetCount: number;
generatedStreetCount: number;
collisions: string[];
};
function normalizeStreet(value: string): string {
return value
.normalize("NFD")
.replace(/[\u0300-\u036f]/gu, "")
.replace(/ß/gu, "ss")
.replace(/�/gu, "ss")
.toLowerCase()
.replace(/[^a-z0-9]/gu, "");
}
export function generatedStreetNames(): string[] {
const result = new Set<string>();
for (let index = 0; index < 60; index += 1) {
result.add(`${STREET_PREFIXES[(index * 11) % STREET_PREFIXES.length]!}${STREET_SUFFIXES[(index * 5) % STREET_SUFFIXES.length]!}`);
}
return [...result].sort((left, right) => left.localeCompare(right, "de"));
}
async function fetchPage(fetchImpl: typeof fetch, offset: number): Promise<{ raw: string; page: GeoJsonPage }> {
let lastError: unknown;
for (let attempt = 0; attempt < 3; attempt += 1) {
try {
const response = await fetchImpl(`${HESSEN_STREET_SOURCE_URL}&offset=${offset}`, {
headers: { accept: "application/geo+json" },
signal: AbortSignal.timeout(20_000),
});
if (!response.ok) throw new Error(`Hessen geodata request failed with HTTP ${response.status}.`);
const raw = await response.text();
const page = JSON.parse(raw) as GeoJsonPage;
if (!Array.isArray(page.features)) throw new Error(`Hessen geodata page at offset ${offset} has no feature array.`);
return { raw, page };
} catch (error) {
lastError = error;
}
}
throw lastError instanceof Error ? lastError : new Error(`Hessen geodata page at offset ${offset} failed.`);
}
/**
* Checks the synthetic street catalog against the official Hessen street-name
* snapshot. This is an explicit development-time gate and never runs during a
* staging seed, keeping the production seed independent from remote services.
*/
export async function validateGeneratedStreets(fetchImpl: typeof fetch = fetch): Promise<GeodataValidationReport> {
const first = await fetchPage(fetchImpl, 0);
const numberMatched = first.page.numberMatched ?? first.page.features!.length;
if (!Number.isSafeInteger(numberMatched) || numberMatched <= 0) throw new Error("Hessen geodata response has an invalid numberMatched value.");
const offsets = Array.from({ length: Math.max(0, Math.ceil(numberMatched / 500) - 1) }, (_, index) => (index + 1) * 500);
const pages = [first];
for (const batchStart of Array.from({ length: Math.ceil(offsets.length / 8) }, (_, index) => index * 8)) {
pages.push(...(await Promise.all(offsets.slice(batchStart, batchStart + 8).map((offset) => fetchPage(fetchImpl, offset)))));
}
for (const [pageIndex, { page }] of pages.entries()) {
if (page.numberMatched !== undefined && page.numberMatched !== numberMatched)
throw new Error("Hessen geodata pagination returned inconsistent numberMatched values.");
const expectedFeatures = Math.min(500, numberMatched - pageIndex * 500);
if (page.features!.length !== expectedFeatures) {
throw new Error(`Hessen geodata page at offset ${pageIndex * 500} is incomplete.`);
}
}
const officialNames = pages
.flatMap(({ page }) => page.features!)
.flatMap(({ properties }) => (typeof properties?.text === "string" ? [properties.text] : []));
if (officialNames.length !== numberMatched) throw new Error("Hessen geodata snapshot contains incomplete street-name properties.");
const officialNormalized = new Set(officialNames.map(normalizeStreet));
const generated = generatedStreetNames();
const hash = createHash("sha256");
for (const { raw } of pages) hash.update(raw);
return {
sourceUrl: HESSEN_STREET_SOURCE_URL,
sourceHashSha256: hash.digest("hex"),
officialStreetCount: officialNames.length,
generatedStreetCount: generated.length,
collisions: generated.filter((name) => officialNormalized.has(normalizeStreet(name))),
};
}
@@ -0,0 +1,66 @@
import { readFileSync, readdirSync } from "node:fs";
import { resolve } from "node:path";
import { describe, expect, it } from "vitest";
const repoFile = (path: string): string => readFileSync(resolve(process.cwd(), path), "utf8");
const persistenceSource = repoFile("scripts/demo-pro-seed/persistence.ts");
const projectServiceSource = repoFile("apps/web/app/utils/integrations/projects/projectService.server.ts");
const orderServiceSource = repoFile("apps/web/app/utils/integrations/projects/auftragService.server.ts");
const formTemplateSource = repoFile("apps/web/app/modules/forms/services/shkFormTemplates.server.ts");
const customFieldSource = repoFile("apps/web/app/utils/integrations/crm/customFieldService.server.ts");
const automationSource = repoFile("apps/web/app/services/automation/automation.server.ts");
const crmLegacySeedSource = repoFile("scripts/ops/seed-crm-leads-demo.mts");
const hrLegacySeedSource = repoFile("scripts/ops/seed-hr-demo.mts");
describe("managed staging business data", () => {
it("never persists comprehensive seed rows behind product demo filters", () => {
const creationSource = persistenceSource.split("export async function verifyDemoProTenant")[0]!;
expect(creationSource).toContain("const STAGING_BUSINESS_DATA_IS_DEMO = false;");
expect(creationSource).not.toContain("isDemoData: true");
expect(creationSource).toContain("isDemoData: STAGING_BUSINESS_DATA_IS_DEMO");
expect(creationSource).not.toContain('tags: ["Demo"');
expect(creationSource).not.toContain("Seed-Gruppe");
expect(creationSource).not.toContain("Demo-Signatur");
});
it("creates lazy project defaults as normal tenant data", () => {
expect(projectServiceSource).not.toContain("isDemoData: true");
expect(orderServiceSource).not.toContain("isDemoData: true");
});
it("keeps reachable template writers on the normal-data invariant", () => {
expect(formTemplateSource).toContain("const isDemoData = input.isDemoData ?? false");
expect(customFieldSource).toContain("const isDemoData = input.isDemoData ?? false");
const userTemplateCreation = automationSource.split("export async function createAutomationRuleFromTemplate")[1]!.split("export async function createAutomationRuleFromTemplateForRoute")[0]!;
expect(userTemplateCreation).not.toContain("isDemoData: true");
expect(userTemplateCreation).toContain("isDemoData: false");
});
it("verifies every tenant model that currently carries an isDemoData flag", () => {
const declaredList = persistenceSource.match(/const TENANT_MODELS_WITH_DEMO_FLAG = \[([\s\S]*?)\] as const;/u)?.[1];
expect(declaredList).toBeDefined();
const verifiedModels = [...(declaredList?.matchAll(/"([A-Za-z0-9]+)"/gu) ?? [])].map((match) => match[1]).sort();
const schemaDir = resolve(process.cwd(), "prisma/schema");
const schemaModels = readdirSync(schemaDir)
.filter((name) => name.endsWith(".prisma"))
.flatMap((name) => {
const source = readFileSync(resolve(schemaDir, name), "utf8");
return [...source.matchAll(/model\s+(\w+)\s*\{([\s\S]*?)\n\}/gu)]
.filter(([, , body]) => /\btenantId\s+String\??\b/u.test(body!) && /\bisDemoData\s+Boolean\b/u.test(body!))
.map(([, model]) => model!);
})
.sort();
expect(verifiedModels).toEqual(schemaModels);
});
it("keeps legacy demo scripts away from the managed staging tenant", () => {
for (const source of [crmLegacySeedSource, hrLegacySeedSource]) {
const targetList = source.match(/const DEMO_SLUGS = \[(.*?)\];/u)?.[1];
expect(targetList).toBeDefined();
expect(targetList).not.toContain('"demo-pro-crm"');
expect(source).toContain('const MANAGED_STAGING_TENANT_SLUG = "demo-pro-crm";');
expect(source).toContain("if (t.slug === MANAGED_STAGING_TENANT_SLUG)");
}
});
});
@@ -0,0 +1,145 @@
import { describe, expect, it } from "vitest";
import { generateDemoProSeed } from "./generator";
import { buildSeedFileObjectMetadata, seedFileStorageKey } from "./file-objects";
import { generateOperationalGraph, OPERATIONAL_COUNTS } from "./operations";
describe("demo-pro operational graph", () => {
it("generates all agreed connected entity volumes", () => {
const operational = generateOperationalGraph(generateDemoProSeed());
for (const [key, expected] of Object.entries(OPERATIONAL_COUNTS)) {
expect(operational[key as keyof typeof operational]).toHaveLength(expected);
}
});
it("keeps task assignment and schedule data internally consistent", () => {
const graph = generateDemoProSeed();
const operational = generateOperationalGraph(graph);
expect(operational.tasks.every((task) => Number(Boolean(task.assignedToUserId)) + Number(Boolean(task.assignedToGroupId)) === 1)).toBe(true);
expect(
operational.tasks.every(
(task) =>
new Date(task.createdAt) <= new Date(task.updatedAt) &&
new Date(task.updatedAt) <= new Date(graph.referenceDate) &&
(task.completedAt === null || (new Date(task.createdAt) <= new Date(task.completedAt) && new Date(task.completedAt) <= new Date(graph.referenceDate)))
)
).toBe(true);
expect(operational.scheduleEntries.every((entry) => new Date(entry.startAt) < new Date(entry.endAt))).toBe(true);
const projects = new Map(graph.projects.map((project) => [project.id, project]));
expect(
operational.scheduleEntries.every((entry) => {
const project = projects.get(entry.projectId)!;
return Boolean(project.startDate) && new Date(entry.startAt) >= new Date(project.startDate!) && new Date(entry.endAt) <= new Date(project.deadline);
})
).toBe(true);
expect(
operational.scheduleConflicts.every((conflict) => {
const entry = operational.scheduleEntries.find(({ id }) => id === conflict.entryId)!;
const source = operational.scheduleEntries.find(({ id }) => id === conflict.sourceEntryId)!;
return (
entry.assignedUserId === source.assignedUserId && new Date(entry.startAt) < new Date(source.endAt) && new Date(source.startAt) < new Date(entry.endAt)
);
})
).toBe(true);
expect(
operational.scheduleEntries.every((entry) => {
if (entry.calendarEventId === null) return entry.syncStatus === "pending";
const event = operational.calendarEvents.find(({ id }) => id === entry.calendarEventId);
return (
entry.syncStatus === "synced" &&
event?.projectId === entry.projectId &&
event.userId === entry.assignedUserId &&
event.startsAt === entry.startAt &&
event.endsAt === entry.endAt
);
})
).toBe(true);
expect(new Set(operational.files.map((file) => seedFileStorageKey("tenant-staging", file.id))).size).toBe(operational.files.length);
expect(
operational.files.every(
(file) =>
seedFileStorageKey("tenant-staging", file.id).startsWith("tenants/tenant-staging/files/") &&
file.mimeType === "application/pdf" &&
file.sizeBytes === buildSeedFileObjectMetadata(file).sizeBytes &&
file.checksumSha256 === buildSeedFileObjectMetadata(file).checksumSha256 &&
file.tags.every((tag) => !/demo|synthet/u.test(tag.toLowerCase())) &&
!/demo|synthet|seed/u.test(file.notes.toLowerCase())
)
).toBe(true);
expect(operational.acceptanceSignatures.every((signature) => signature.signerRole === "kunde" || signature.signerRole === "monteur")).toBe(true);
expect(operational.activities.every((activity) => new Date(activity.createdAt) <= new Date(graph.referenceDate))).toBe(true);
expect(operational.acceptances.every((acceptance) => new Set(acceptance.attendees).size === acceptance.attendees.length)).toBe(true);
expect(
operational.acceptances.every(
(acceptance) =>
new Date(acceptance.date) <= new Date(acceptance.createdAt) &&
new Date(acceptance.createdAt) <= new Date(acceptance.updatedAt) &&
new Date(acceptance.updatedAt) <= new Date(graph.referenceDate)
)
).toBe(true);
expect(
operational.acceptances
.filter(({ kind }) => kind === "with_defects")
.every((acceptance) => operational.checklists.find(({ id }) => id === acceptance.checklistId)?.type === "maengel")
).toBe(true);
expect(
operational.signatureDocuments.every((document) => operational.files.find(({ id }) => id === document.sourceFileId)?.displayName.startsWith("Angebot_"))
).toBe(true);
expect(
operational.signatureDocuments.every(
(document) =>
document.createdAt === document.sentAt &&
new Date(document.createdAt) <= new Date(document.updatedAt) &&
new Date(document.updatedAt) <= new Date(graph.referenceDate)
)
).toBe(true);
expect(
operational.invoices.every((invoice) => {
const project = projects.get(invoice.projectId)!;
return project.pipeline === "auftrag" || project.stage === "gewonnen";
})
).toBe(true);
expect(operational.invoices.every((invoice) => new Date(invoice.date) <= new Date(graph.referenceDate))).toBe(true);
const invoiceFileIds = operational.invoices.flatMap(({ fileId }) => (fileId ? [fileId] : []));
expect(invoiceFileIds.length).toBeGreaterThan(0);
expect(new Set(invoiceFileIds).size).toBe(invoiceFileIds.length);
expect(
operational.invoices.every((invoice) => {
if (!invoice.fileId) return true;
const file = operational.files.find(({ id }) => id === invoice.fileId);
return file?.projectId === invoice.projectId && file.displayName.startsWith("Rechnung_");
})
).toBe(true);
expect(operational.checklistItems.every(({ photoFileId }) => photoFileId === null)).toBe(true);
expect(operational.acceptances.some(({ documentFileId }) => documentFileId !== null)).toBe(true);
expect(
operational.acceptances.every((acceptance) => {
if (!acceptance.documentFileId) return true;
const file = operational.files.find(({ id }) => id === acceptance.documentFileId);
return file?.projectId === acceptance.projectId && file.displayName.startsWith("Abnahmeprotokoll_");
})
).toBe(true);
expect(
operational.bookingAppointments.every((appointment) =>
operational.bookingProviders.some(
(provider) => provider.bookingPageId === appointment.bookingPageId && provider.providerUserId === appointment.providerUserId
)
)
).toBe(true);
expect(new Set(operational.bookingAppointments.map(({ internalCalendarEventId }) => internalCalendarEventId)).size).toBe(
operational.bookingAppointments.length
);
expect(
operational.bookingAppointments.every((appointment) => {
const page = operational.bookingPages.find(({ id }) => id === appointment.bookingPageId)!;
return new Date(appointment.endsAt).getTime() - new Date(appointment.startsAt).getTime() === page.durationMinutes * 60_000;
})
).toBe(true);
});
it("is deterministic across complete operational generations", () => {
expect(generateOperationalGraph(generateDemoProSeed())).toEqual(generateOperationalGraph(generateDemoProSeed()));
});
});
@@ -0,0 +1,963 @@
import type { DemoProSeedGraph, ProjectType, SeedProject } from "./types";
import { buildSeedFileObjectMetadata } from "./file-objects";
export const OPERATIONAL_COUNTS = {
projectContacts: 1_611,
projectMembers: 1_876,
tasks: 1_684,
taskWatchers: 421,
activities: 2_731,
scheduleEntries: 1_147,
scheduleConflicts: 23,
calendarEvents: 613,
projectAppointments: 613,
bookingPages: 3,
bookingProviders: 21,
availabilityRules: 35,
availabilityExceptions: 7,
bookingAppointments: 79,
invoices: 347,
checklists: 329,
checklistItems: 1_693,
files: 917,
acceptances: 73,
acceptanceSignatures: 146,
signatureDocuments: 47,
signatureSigners: 47,
} as const;
type ProjectContact = {
id: string;
projectId: string;
contactId: string;
role: "auftraggeber" | "bauherr" | "rechnungsempfaenger" | "ansprechpartner";
primary: boolean;
};
type ProjectMember = {
id: string;
projectId: string;
userId: string | null;
groupId: string | null;
role: "monteur" | "projektleiter" | "zustaendig";
};
type SeedTask = {
id: string;
projectId: string;
title: string;
description: string;
status: "open" | "in_progress" | "blocked" | "done" | "cancelled";
priority: "low" | "normal" | "high" | "urgent";
deadline: string;
assignedToUserId: string | null;
assignedToGroupId: string | null;
completedAt: string | null;
createdAt: string;
updatedAt: string;
};
type SeedActivity = {
id: string;
projectId: string;
actorUserId: string;
activityType: string;
createdAt: string;
summaryText: string;
metadata: Record<string, unknown>;
};
type SeedScheduleEntry = {
id: string;
projectId: string;
assignedUserId: string;
title: string;
startAt: string;
endAt: string;
status: "planned" | "confirmed" | "in_progress" | "done" | "cancelled";
calendarEventId: string | null;
syncStatus: "pending" | "synced";
};
type SeedCalendarEvent = {
id: string;
projectId: string;
userId: string;
title: string;
description: string;
location: string;
startsAt: string;
endsAt: string;
};
type SeedBookingPage = {
id: string;
slug: string;
title: string;
description: string;
durationMinutes: number;
};
type SeedBookingAppointment = {
id: string;
bookingPageId: string;
providerUserId: string;
contactId: string;
projectId: string;
internalCalendarEventId: string;
startsAt: string;
endsAt: string;
status: "scheduled" | "held" | "cancelled";
customerName: string;
customerEmail: string;
customerPhone: string;
request: string;
};
type SeedInvoice = {
id: string;
projectId: string;
invoiceNumber: string;
amount: string;
status: "entwurf" | "gestellt" | "bezahlt" | "storniert";
date: string;
dueAt: string;
fileId: string | null;
createdAt: string;
updatedAt: string;
};
type SeedChecklist = {
id: string;
projectId: string;
title: string;
type: "generisch" | "maengel" | "abnahme_doku";
};
type SeedChecklistItem = {
id: string;
checklistId: string;
title: string;
status: "offen" | "erledigt" | "entfaellt";
defectClass: string | null;
assignedToUserId: string;
dueAt: string;
position: number;
photoFileId: null;
};
type SeedFile = {
id: string;
projectId: string;
displayName: string;
mimeType: string;
sizeBytes: number;
checksumSha256: string;
assignedToUserId: string;
tags: string[];
notes: string;
linkRole: string;
createdAt: string;
updatedAt: string;
};
type SeedAcceptance = {
id: string;
projectId: string;
checklistId: string | null;
creatorUserId: string;
date: string;
kind: "full" | "with_defects";
attendees: string[];
remarks: string;
customerEmail: string;
documentFileId: string | null;
createdAt: string;
updatedAt: string;
};
type SeedSignatureDocument = {
id: string;
projectId: string;
sourceFileId: string;
creatorUserId: string;
status: "sent" | "viewed" | "signed";
title: string;
sentAt: string;
completedAt: string | null;
signerContactId: string;
signerEmail: string;
signerName: string;
createdAt: string;
updatedAt: string;
};
export type DemoProOperationalGraph = {
projectContacts: ProjectContact[];
projectMembers: ProjectMember[];
tasks: SeedTask[];
taskWatchers: Array<{ id: string; taskId: string; userId: string }>;
activities: SeedActivity[];
scheduleEntries: SeedScheduleEntry[];
scheduleConflicts: Array<{ id: string; entryId: string; sourceEntryId: string; resolvedAt: string | null }>;
calendarEvents: SeedCalendarEvent[];
projectAppointments: Array<SeedCalendarEvent & { status: "geplant" | "bestaetigt" | "erledigt" | "abgesagt" }>;
bookingPages: SeedBookingPage[];
bookingProviders: Array<{ id: string; bookingPageId: string; providerUserId: string; displayOrder: number }>;
availabilityRules: Array<{
id: string;
providerUserId: string;
dayOfWeek: "monday" | "tuesday" | "wednesday" | "thursday" | "friday";
startTime: string;
endTime: string;
}>;
availabilityExceptions: Array<{
id: string;
providerUserId: string;
date: string;
kind: "unavailable" | "custom_window";
startTime: string | null;
endTime: string | null;
reason: string;
}>;
bookingAppointments: SeedBookingAppointment[];
invoices: SeedInvoice[];
checklists: SeedChecklist[];
checklistItems: SeedChecklistItem[];
files: SeedFile[];
acceptances: SeedAcceptance[];
acceptanceSignatures: Array<{ id: string; acceptanceId: string; signerName: string; signerRole: "kunde" | "monteur"; signedAt: string }>;
signatureDocuments: SeedSignatureDocument[];
signatureSigners: Array<{
id: string;
documentId: string;
contactId: string;
email: string;
name: string;
status: "sent" | "viewed" | "signed";
signedAt: string | null;
}>;
};
const taskTemplates: Readonly<Record<ProjectType, readonly string[]>> = {
reparatur_notdienst: [
"Störungsbild telefonisch aufnehmen",
"Ersatzteile und Werkzeug disponieren",
"Einsatzbericht mit Messwerten abschließen",
"Kunden über Folgemaßnahmen informieren",
],
wartung_pruefung: [
"Anlagendaten und Wartungshistorie prüfen",
"Wartungsmaterial zusammenstellen",
"Mess- und Wartungsprotokoll erfassen",
"Nächsten Wartungszyklus vormerken",
],
heizungstausch: [
"Heizlast und Bestandssituation prüfen",
"Wärmeerzeuger und Speicher disponieren",
"Montageablauf mit Kunde abstimmen",
"Inbetriebnahme und Einweisung dokumentieren",
],
heizungsoptimierung: [
"Bestandswerte und Heizkreise aufnehmen",
"Einstellwerte berechnen",
"Optimierungsmaßnahmen ausführen",
"Verbrauchsempfehlungen dokumentieren",
],
badsanierung: [
"Aufmaß und Ausstattungsdetails bestätigen",
"Sanitärobjekte und Armaturen disponieren",
"Gewerkeablauf koordinieren",
"Abnahme und Pflegehinweise vorbereiten",
],
sanitaer_rohrarbeiten: [
"Leitungsverlauf und Absperrungen prüfen",
"Rohrmaterial disponieren",
"Druckprobe dokumentieren",
"Bestandsunterlagen aktualisieren",
],
objekt_neubau: [
"Ausführungsplanung mit Fachplanung abstimmen",
"Bauzeitenplan und Materialabrufe aktualisieren",
"Montagefortschritt dokumentieren",
"Teilabnahme vorbereiten",
],
lueftung_klima: [
"Luftmengen und Aufstellorte prüfen",
"Geräte und Kanalmaterial disponieren",
"Anlage montieren und einregulieren",
"Messprotokoll und Einweisung abschließen",
],
};
const activityTemplates = [
["project.created", "Projekt wurde vollständig angelegt"],
["project.contact_linked", "Kunden- und Ansprechpartner wurden verknüpft"],
["project.assignment_changed", "Projektteam und Zuständigkeiten wurden geplant"],
["project.schedule_planned", "Ausführungstermin wurde in der Plantafel reserviert"],
["project.note_added", "Technische Projektnotiz wurde ergänzt"],
["project.stage_changed", "Pipeline-Status wurde aktualisiert"],
] as const;
function id(kind: string, index: number): string {
return `rheinmain-shk-v1-${kind}-${String(index + 1).padStart(5, "0")}`;
}
function addDays(value: string, days: number, hour?: number): string {
const date = new Date(value);
date.setUTCDate(date.getUTCDate() + days);
if (hour !== undefined) date.setUTCHours(hour, 0, 0, 0);
return date.toISOString();
}
function earlierDate(first: string, second: string): string {
return new Date(first) <= new Date(second) ? first : second;
}
function laterDate(first: string, second: string): string {
return new Date(first) >= new Date(second) ? first : second;
}
function euro(value: string | null, factor: number): string {
const amount = Number(value ?? 0);
return Math.max(90, Math.round((amount * factor) / 10) * 10).toFixed(2);
}
function contactDisplayName(graph: DemoProSeedGraph, contactId: string): string {
const organization = graph.organizations.find((contact) => contact.id === contactId);
if (organization) return organization.orgName;
const person = graph.persons.find((contact) => contact.id === contactId);
return person ? `${person.firstName} ${person.lastName}` : "Kunde";
}
function contactEmail(graph: DemoProSeedGraph, contactId: string): string {
return (
graph.organizations.find((contact) => contact.id === contactId)?.email ??
graph.persons.find((contact) => contact.id === contactId)?.email ??
"kunde@unbekannt.example.test"
);
}
function contactPhone(graph: DemoProSeedGraph, contactId: string): string {
return (
graph.organizations.find((contact) => contact.id === contactId)?.phone ??
graph.persons.find((contact) => contact.id === contactId)?.phone ??
"+496990009000"
);
}
function employeeDisplayName(graph: DemoProSeedGraph, employeeId: string): string {
const employee = graph.employees.find(({ id: currentId }) => currentId === employeeId);
return employee ? `${employee.firstName} ${employee.lastName}` : "Mitarbeiter";
}
export function generateOperationalGraph(graph: DemoProSeedGraph): DemoProOperationalGraph {
const crewById = new Map(graph.crews.map((crew) => [crew.id, crew]));
const projectContacts: ProjectContact[] = [];
const projectMembers: ProjectMember[] = [];
const tasks: SeedTask[] = [];
const activities: SeedActivity[] = [];
const scheduleEntries: SeedScheduleEntry[] = [];
const calendarEvents: SeedCalendarEvent[] = [];
const projectAppointments: DemoProOperationalGraph["projectAppointments"] = [];
for (const [projectIndex, project] of graph.projects.entries()) {
for (const contact of project.contacts) {
projectContacts.push({
id: id("project-contact", projectContacts.length),
projectId: project.id,
contactId: contact.contactId,
role: contact.role,
primary: contact.primary,
});
}
const crew = crewById.get(project.crewIds[0]!)!;
projectMembers.push({
id: id("project-member", projectMembers.length),
projectId: project.id,
userId: project.projectManagerEmployeeId,
groupId: null,
role: "projektleiter",
});
for (const userId of crew.memberEmployeeIds) {
projectMembers.push({ id: id("project-member", projectMembers.length), projectId: project.id, userId, groupId: null, role: "monteur" });
}
for (const additionalCrewId of project.crewIds.slice(1)) {
const additionalCrew = crewById.get(additionalCrewId)!;
for (const userId of additionalCrew.memberEmployeeIds) {
projectMembers.push({ id: id("project-member", projectMembers.length), projectId: project.id, userId, groupId: null, role: "monteur" });
}
}
if (projectIndex < 216) {
projectMembers.push({
id: id("project-member", projectMembers.length),
projectId: project.id,
userId: project.responsibleEmployeeId,
groupId: null,
role: "zustaendig",
});
}
const projectTaskCount = projectIndex < 73 ? 4 : 3;
for (let slot = 0; slot < projectTaskCount; slot += 1) {
const deadline = addDays(project.startDate ?? project.createdAt, 1 + slot * 2);
const done = new Date(deadline) < new Date(graph.referenceDate) && (projectIndex + slot) % 4 !== 0;
const assignedToCrew = slot === 1 || (slot === 2 && projectIndex % 3 === 0);
const createdAt = earlierDate(earlierDate(addDays(project.createdAt, slot), deadline), graph.referenceDate);
const completedAt = done ? addDays(deadline, 0, 16) : null;
const statusUpdatedAt =
done || (projectIndex + slot) % 3 !== 0
? (completedAt ?? createdAt)
: earlierDate(addDays(createdAt, 1 + ((projectIndex + slot) % 5)), graph.referenceDate);
tasks.push({
id: id("task", tasks.length),
projectId: project.id,
title: taskTemplates[project.projectType][slot]!,
description: `${project.projectNumber}: ${project.projectName}. Zuständigkeit und Ergebnis nachvollziehbar im Projekt dokumentieren.`,
status: done ? "done" : slot === 2 && projectIndex % 17 === 0 ? "blocked" : slot === 0 && projectIndex % 5 === 0 ? "in_progress" : "open",
priority: project.priority === "dringend" ? "urgent" : project.priority === "hoch" ? "high" : project.priority === "niedrig" ? "low" : "normal",
deadline,
assignedToUserId: assignedToCrew ? null : slot === 0 ? project.responsibleEmployeeId : crew.memberEmployeeIds[slot % crew.memberEmployeeIds.length]!,
assignedToGroupId: assignedToCrew ? crew.id : null,
completedAt,
createdAt,
updatedAt: laterDate(createdAt, statusUpdatedAt),
});
}
const activityCount = projectIndex < 46 ? 6 : 5;
for (let slot = 0; slot < activityCount; slot += 1) {
const [activityType, summaryText] = activityTemplates[slot]!;
const candidateCreatedAt = addDays(project.createdAt, slot * 2);
activities.push({
id: id("activity", activities.length),
projectId: project.id,
actorUserId: slot % 2 === 0 ? project.responsibleEmployeeId : project.projectManagerEmployeeId,
activityType,
createdAt: new Date(candidateCreatedAt) > new Date(graph.referenceDate) ? graph.referenceDate : candidateCreatedAt,
summaryText: `${summaryText}: ${project.projectNumber}`,
metadata: { projectNumber: project.projectNumber, projectType: project.projectType, seedNamespace: graph.namespace },
});
}
const calendarCount = projectIndex < 76 ? 2 : 1;
for (let slot = 0; slot < calendarCount; slot += 1) {
const userId = slot === 0 ? project.projectManagerEmployeeId : project.responsibleEmployeeId;
const calendarWindowStart = project.startDate ?? project.createdAt;
const calendarWindowDays = Math.max(
1,
Math.floor((new Date(project.deadline ?? graph.referenceDate).getTime() - new Date(calendarWindowStart).getTime()) / 86_400_000)
);
const dayOffset = Math.min(calendarWindowDays - 1, (projectIndex * 3 + slot) % calendarWindowDays);
const startsAt = addDays(calendarWindowStart, dayOffset, 9 + slot * 4);
const endsAt = new Date(new Date(startsAt).getTime() + (slot === 0 ? 90 : 45) * 60 * 1_000).toISOString();
const event = {
id: id("calendar", calendarEvents.length),
projectId: project.id,
userId,
title: slot === 0 ? `Baubesprechung · ${project.projectNumber}` : `Kundenabstimmung · ${project.projectNumber}`,
description: `${project.projectName}: Termin, nächste Schritte und offene Punkte abstimmen.`,
location: `${project.projectAddress.strasse} ${project.projectAddress.hausnummer}, ${project.projectAddress.plz} ${project.projectAddress.ort}`,
startsAt,
endsAt,
};
calendarEvents.push(event);
projectAppointments.push({
...event,
id: id("project-appointment", projectAppointments.length),
status: new Date(endsAt) < new Date(graph.referenceDate) ? "erledigt" : slot === 0 ? "bestaetigt" : "geplant",
});
}
}
const scheduleConflictPairs: Array<{ entryId: string; sourceEntryId: string }> = [];
const scheduledProjects = graph.projects.filter((project): project is SeedProject & { startDate: string } => Boolean(project.startDate));
for (const [scheduledProjectIndex, project] of scheduledProjects.entries()) {
const projectStartDate = project.startDate!;
const crew = crewById.get(project.crewIds[0]!)!;
const scheduleCount = scheduledProjectIndex < 157 ? 4 : 3;
const windowDays = Math.max(
1,
Math.floor((new Date(project.deadline ?? graph.referenceDate).getTime() - new Date(projectStartDate).getTime()) / 86_400_000)
);
const projectEntries: SeedScheduleEntry[] = [];
for (let slot = 0; slot < scheduleCount; slot += 1) {
const conflictSlot = scheduledProjectIndex < OPERATIONAL_COUNTS.scheduleConflicts && slot === 2;
const assignedUserId = conflictSlot ? crew.memberEmployeeIds[0] : crew.memberEmployeeIds[slot % crew.memberEmployeeIds.length]!;
const startAt = conflictSlot
? projectEntries[0]!.startAt
: addDays(projectStartDate, Math.min(windowDays - 1, Math.floor(slot / 2)), 9 + Math.floor(slot / 2) * 4);
const endAt = conflictSlot ? projectEntries[0]!.endAt : new Date(new Date(startAt).getTime() + 3 * 60 * 60 * 1_000).toISOString();
const past = new Date(endAt) < new Date(graph.referenceDate);
const entry: SeedScheduleEntry = {
id: id("schedule", scheduleEntries.length),
projectId: project.id,
assignedUserId,
title: `${project.projectNumber} · ${project.projectName}`,
startAt,
endAt,
status: past ? "done" : scheduledProjectIndex % 5 === 0 ? "confirmed" : "planned",
calendarEventId: null,
syncStatus: "pending",
};
projectEntries.push(entry);
scheduleEntries.push(entry);
if (conflictSlot) scheduleConflictPairs.push({ entryId: entry.id, sourceEntryId: projectEntries[0]!.id });
}
}
const bookingPages: SeedBookingPage[] = [
{
id: id("booking-page", 0),
slug: "heizung-bad-beratung",
title: "Heizungs- und Badberatung",
description: "Persönliche Erstberatung für Heizungstausch, Wärmepumpe und Badsanierung im Rhein-Main-Gebiet.",
durationMinutes: 45,
},
{
id: id("booking-page", 1),
slug: "wartung-bestandskunden",
title: "Wartung für Bestandskunden",
description: "Terminabstimmung für die regelmäßige Wartung bestehender Heizungs- und Sanitäranlagen.",
durationMinutes: 60,
},
{
id: id("booking-page", 2),
slug: "notdienst-rueckruf",
title: "Notdienst-Rückruf",
description: "Kurzer technischer Rückruf zur Einschätzung einer akuten Störung und zur Einsatzplanung.",
durationMinutes: 30,
},
];
const providers = graph.employees.filter(({ role }) => role === "Projektleiter/Bauleiter");
const bookingProviders = bookingPages.flatMap((page) =>
providers.map((employee, displayOrder) => ({
id: `${page.id}-provider-${String(displayOrder + 1).padStart(2, "0")}`,
bookingPageId: page.id,
providerUserId: employee.id,
displayOrder,
}))
);
const weekdays = ["monday", "tuesday", "wednesday", "thursday", "friday"] as const;
const availabilityRules = providers.flatMap((provider, providerIndex) =>
weekdays.map((dayOfWeek, weekdayIndex) => ({
id: id("availability-rule", providerIndex * weekdays.length + weekdayIndex),
providerUserId: provider.id,
dayOfWeek,
startTime: weekdayIndex === 4 ? "08:00" : providerIndex % 2 === 0 ? "08:30" : "09:00",
endTime: weekdayIndex === 4 ? "14:00" : providerIndex % 3 === 0 ? "16:30" : "17:00",
}))
);
const availabilityExceptions = providers.map((provider, index) => {
const customWindow = index % 3 === 1;
return {
id: id("availability-exception", index),
providerUserId: provider.id,
date: addDays(graph.referenceDate, 11 + index),
kind: customWindow ? ("custom_window" as const) : ("unavailable" as const),
startTime: customWindow ? "10:00" : null,
endTime: customWindow ? "14:00" : null,
reason: customWindow ? "Fortbildung am Vormittag" : index % 2 === 0 ? "Urlaub" : "Baustellenbegehung außer Haus",
};
});
const projectById = new Map(graph.projects.map((project) => [project.id, project]));
const providerIds = new Set(providers.map(({ id: providerId }) => providerId));
const bookingAppointments = calendarEvents
.filter(({ userId }) => providerIds.has(userId))
.filter(({ startsAt }) => {
const day = new Date(startsAt).getUTCDay();
return day >= 1 && day <= 5;
})
.slice(0, OPERATIONAL_COUNTS.bookingAppointments)
.map((event, index): SeedBookingAppointment => {
const project = projectById.get(event.projectId)!;
const primaryContact = project.contacts.find(({ primary }) => primary)?.contactId ?? project.contacts[0]!.contactId;
const page =
project.projectType === "reparatur_notdienst" ? bookingPages[2]! : project.projectType === "wartung_pruefung" ? bookingPages[1]! : bookingPages[0]!;
const cancelled = index % 17 === 0;
const endsAt = new Date(new Date(event.startsAt).getTime() + page.durationMinutes * 60_000).toISOString();
event.endsAt = endsAt;
const projectAppointment = projectAppointments.find(
(appointment) => appointment.projectId === event.projectId && appointment.userId === event.userId && appointment.startsAt === event.startsAt
);
if (projectAppointment) projectAppointment.endsAt = endsAt;
if (projectAppointment && cancelled) projectAppointment.status = "abgesagt";
return {
id: id("booking-appointment", index),
bookingPageId: page.id,
providerUserId: event.userId,
contactId: primaryContact,
projectId: project.id,
internalCalendarEventId: event.id,
startsAt: event.startsAt,
endsAt,
status: cancelled ? "cancelled" : new Date(endsAt) < new Date(graph.referenceDate) ? "held" : "scheduled",
customerName: contactDisplayName(graph, primaryContact),
customerEmail: contactEmail(graph, primaryContact),
customerPhone: contactPhone(graph, primaryContact),
request: `${project.projectName}: Terminwunsch zu ${project.description}`,
};
});
const calendarEventsByScheduleWindow = new Map<string, SeedCalendarEvent[]>();
for (const event of calendarEvents) {
const key = [event.projectId, event.userId, event.startsAt, event.endsAt].join("\u0000");
const matches = calendarEventsByScheduleWindow.get(key) ?? [];
matches.push(event);
calendarEventsByScheduleWindow.set(key, matches);
}
for (const entry of scheduleEntries) {
const key = [entry.projectId, entry.assignedUserId, entry.startAt, entry.endAt].join("\u0000");
const matches = calendarEventsByScheduleWindow.get(key) ?? [];
// A schedule row may only claim sync when one exact calendar counterpart
// exists. Similar-looking meetings are intentionally not guessed as links.
if (matches.length === 1) {
entry.calendarEventId = matches[0]!.id;
entry.syncStatus = "synced";
}
}
const taskWatchers = tasks.slice(0, OPERATIONAL_COUNTS.taskWatchers).map((task, index) => ({
id: id("task-watcher", index),
taskId: task.id,
userId: graph.employees[(index * 7) % graph.employees.length]!.id,
}));
const scheduleConflicts = scheduleConflictPairs.map((pair, index) => ({
id: id("schedule-conflict", index),
entryId: pair.entryId,
sourceEntryId: pair.sourceEntryId,
resolvedAt: index % 3 === 0 ? null : addDays(scheduleEntries.find(({ id: entryId }) => entryId === pair.entryId)!.startAt, -2),
}));
const billableProjects = graph.projects.filter((project) => project.pipeline === "auftrag" || project.stage === "gewonnen");
const invoiceProjects = Array.from({ length: OPERATIONAL_COUNTS.invoices }, (_, index) => billableProjects[index % billableProjects.length]!);
const invoices = invoiceProjects.map((project, index): SeedInvoice => {
const status: SeedInvoice["status"] =
project.stage === "storniert"
? "storniert"
: project.stage === "abgeschlossen"
? index % 7 === 0
? "gestellt"
: "bezahlt"
: project.stage === "abnahme" && index % 3 === 0
? "gestellt"
: "entwurf";
const date = earlierDate(addDays(project.createdAt, 3 + (index % 21)), graph.referenceDate);
const createdAt = earlierDate(addDays(project.createdAt, index % 3), date);
const lifecycleOffsetDays = status === "bezahlt" ? 7 + (index % 7) : status === "storniert" ? 2 + (index % 4) : status === "gestellt" ? 1 : 0;
return {
id: id("invoice", index),
projectId: project.id,
invoiceNumber: `RE-${new Date(date).getUTCFullYear()}-${String(70419 + index)}`,
amount: euro(project.orderVolume ?? project.potentialOrderValue, index % 4 === 0 ? 0.35 : 1),
status,
date,
dueAt: addDays(date, 14),
fileId: null,
createdAt,
updatedAt: laterDate(createdAt, earlierDate(addDays(date, lifecycleOffsetDays), graph.referenceDate)),
};
});
const checklistProjects = graph.projects
.filter((project) => project.pipeline === "auftrag" || project.stage === "gewonnen")
.slice(0, OPERATIONAL_COUNTS.checklists);
const checklists = checklistProjects.map(
(project, index): SeedChecklist => ({
id: id("checklist", index),
projectId: project.id,
title:
project.stage === "abnahme" || project.stage === "abgeschlossen"
? `Abnahmedokumentation ${project.projectNumber}`
: `Ausführungscheckliste ${project.projectNumber}`,
type: project.stage === "abnahme" ? "abnahme_doku" : index % 9 === 0 ? "maengel" : "generisch",
})
);
const checklistItemTitles = [
"Arbeitsbereich und Absperrungen vorbereitet",
"Material und Bauteile vollständig geprüft",
"Montage nach Herstellervorgaben ausgeführt",
"Messwerte und Druckprobe dokumentiert",
"Arbeitsbereich gereinigt und Kunde eingewiesen",
"Restpunkt mit Verantwortlichem und Termin erfasst",
] as const;
const checklistItems: SeedChecklistItem[] = [];
for (const [checklistIndex, checklist] of checklists.entries()) {
const project = graph.projects.find(({ id: projectId }) => projectId === checklist.projectId)!;
const projectCrew = crewById.get(project.crewIds[0]!)!;
const itemCount = checklistIndex < 48 ? 6 : 5;
for (let position = 0; position < itemCount; position += 1) {
checklistItems.push({
id: id("checklist-item", checklistItems.length),
checklistId: checklist.id,
title: checklistItemTitles[position]!,
status: checklistIndex % 4 === 0 && position > 2 ? "offen" : position === 5 && checklistIndex % 13 === 0 ? "entfaellt" : "erledigt",
defectClass: checklist.type === "maengel" && position === 3 ? "B" : null,
assignedToUserId: projectCrew.memberEmployeeIds[position % projectCrew.memberEmployeeIds.length]!,
dueAt: addDays(project.deadline ?? graph.referenceDate, position - 3),
position,
photoFileId: null,
});
}
}
const files: SeedFile[] = [];
const fileNames = ["Angebot", "Aufmaß", "Montageprotokoll", "Anlagenschema", "Messprotokoll", "Rechnung", "Abnahmeprotokoll"] as const;
for (const [projectIndex, project] of graph.projects.entries()) {
const fileCount = projectIndex < 380 ? 2 : 1;
for (let slot = 0; slot < fileCount; slot += 1) {
const ordinal = files.length;
const baseName = fileNames[(projectIndex + slot) % fileNames.length]!;
const descriptor = {
id: id("file", ordinal),
displayName: `${baseName}_${project.projectNumber}.pdf`,
notes: `Projektunterlage zu ${project.projectName}; dem Projekt ${project.projectNumber} zugeordnet.`,
};
files.push({
...buildSeedFileObjectMetadata(descriptor),
projectId: project.id,
assignedToUserId: project.projectManagerEmployeeId,
tags: [baseName],
linkRole: baseName.toLowerCase(),
createdAt: earlierDate(addDays(project.createdAt, 2 + slot), graph.referenceDate),
updatedAt: earlierDate(addDays(project.createdAt, 2 + slot), graph.referenceDate),
});
}
}
const invoiceFilesByProject = new Map<string, SeedFile[]>();
for (const file of files.filter(({ displayName }) => displayName.startsWith("Rechnung_"))) {
const projectFiles = invoiceFilesByProject.get(file.projectId) ?? [];
projectFiles.push(file);
invoiceFilesByProject.set(file.projectId, projectFiles);
}
for (const invoice of invoices) {
const projectFiles = invoiceFilesByProject.get(invoice.projectId);
invoice.fileId = projectFiles?.shift()?.id ?? null;
}
const acceptanceEligible = graph.projects.filter((project) => project.pipeline === "auftrag" && ["abnahme", "abgeschlossen"].includes(project.stage));
const defectAcceptanceProjects = acceptanceEligible
.filter((project) => checklists.find(({ projectId }) => projectId === project.id)?.type === "maengel")
.slice(0, 10);
const defectProjectIds = new Set(defectAcceptanceProjects.map(({ id: projectId }) => projectId));
const acceptanceProjects = [
...defectAcceptanceProjects,
...acceptanceEligible.filter((project) => !defectProjectIds.has(project.id)).slice(0, OPERATIONAL_COUNTS.acceptances - defectAcceptanceProjects.length),
];
const acceptances = acceptanceProjects.map((project, index): SeedAcceptance => {
const primaryContact = project.contacts.find(({ primary }) => primary)!.contactId;
const checklist = checklists.find(({ projectId }) => projectId === project.id);
const kind: SeedAcceptance["kind"] = index < defectAcceptanceProjects.length ? "with_defects" : "full";
const date = earlierDate(addDays(project.deadline ?? graph.referenceDate, index % 3), addDays(graph.referenceDate, -1));
const documentFileId = files.find((file) => file.projectId === project.id && file.displayName.startsWith("Abnahmeprotokoll_"))?.id ?? null;
const attendees = [...new Set([contactDisplayName(graph, primaryContact), contactDisplayName(graph, project.contacts.at(-1)!.contactId)])];
if (attendees.length < 2) attendees.push(employeeDisplayName(graph, project.projectManagerEmployeeId));
return {
id: id("acceptance", index),
projectId: project.id,
checklistId: checklist?.id ?? null,
creatorUserId: project.projectManagerEmployeeId,
date,
kind,
attendees: attendees.slice(0, 2),
remarks:
kind === "with_defects"
? "Abnahme mit dokumentierten Restpunkten und verbindlichem Nachtermin."
: "Leistung gemeinsam geprüft, Anlage erläutert und ohne Vorbehalt abgenommen.",
customerEmail: contactEmail(graph, primaryContact),
documentFileId,
createdAt: date,
updatedAt: addDays(date, 0, 15),
};
});
const acceptanceSignatures = acceptances.flatMap((acceptance, index) => {
const project = graph.projects.find(({ id: projectId }) => projectId === acceptance.projectId)!;
const crew = crewById.get(project.crewIds[0]!)!;
return [
{
id: id("acceptance-signature", index * 2),
acceptanceId: acceptance.id,
signerName: acceptance.attendees[0]!,
signerRole: "kunde" as const,
signedAt: addDays(acceptance.date, 0, 15),
},
{
id: id("acceptance-signature", index * 2 + 1),
acceptanceId: acceptance.id,
signerName: employeeDisplayName(graph, crew.memberEmployeeIds[0]!),
signerRole: "monteur" as const,
signedAt: addDays(acceptance.date, 0, 15),
},
];
});
const signatureProjects = graph.projects
.filter(
(project) =>
project.pipeline === "sales" &&
["angebot", "gewonnen"].includes(project.stage) &&
files.some((file) => file.projectId === project.id && file.displayName.startsWith("Angebot_"))
)
.slice(0, OPERATIONAL_COUNTS.signatureDocuments);
const signatureDocuments = signatureProjects.map((project, index): SeedSignatureDocument => {
const primaryContact = project.contacts.find(({ primary }) => primary)!.contactId;
const status: SeedSignatureDocument["status"] = index % 4 === 0 ? "sent" : index % 4 === 1 ? "viewed" : "signed";
const sentAt = addDays(project.createdAt, 4 + (index % 8));
const completedAt = status === "signed" ? addDays(sentAt, 2 + (index % 5)) : null;
return {
id: id("signature-document", index),
projectId: project.id,
sourceFileId: files.find((file) => file.projectId === project.id && file.displayName.startsWith("Angebot_"))!.id,
creatorUserId: project.responsibleEmployeeId,
status,
title: `Angebot ${project.projectNumber} zur elektronischen Freigabe`,
sentAt,
completedAt,
signerContactId: primaryContact,
signerEmail: contactEmail(graph, primaryContact),
signerName: contactDisplayName(graph, primaryContact),
createdAt: sentAt,
updatedAt: completedAt ?? (status === "viewed" ? new Date(new Date(sentAt).getTime() + 3_600_000).toISOString() : sentAt),
};
});
const signatureSigners = signatureDocuments.map((document, index) => ({
id: id("signature-signer", index),
documentId: document.id,
contactId: document.signerContactId,
email: document.signerEmail,
name: document.signerName,
status: document.status,
signedAt: document.completedAt,
}));
const operational: DemoProOperationalGraph = {
projectContacts,
projectMembers,
tasks,
taskWatchers,
activities,
scheduleEntries,
scheduleConflicts,
calendarEvents,
projectAppointments,
bookingPages,
bookingProviders,
availabilityRules,
availabilityExceptions,
bookingAppointments,
invoices,
checklists,
checklistItems,
files,
acceptances,
acceptanceSignatures,
signatureDocuments,
signatureSigners,
};
validateOperationalGraph(operational, graph.referenceDate);
return operational;
}
export function validateOperationalGraph(graph: DemoProOperationalGraph, referenceDate: string): void {
for (const [key, expected] of Object.entries(OPERATIONAL_COUNTS)) {
const actual = graph[key as keyof DemoProOperationalGraph].length;
if (actual !== expected) throw new Error(`Operational seed ${key}: expected ${expected}, received ${actual}.`);
}
if (graph.tasks.some((task) => Number(Boolean(task.assignedToUserId)) + Number(Boolean(task.assignedToGroupId)) !== 1)) {
throw new Error("Every operational task must have exactly one assignee.");
}
if (new Set(graph.scheduleEntries.map(({ id: entryId }) => entryId)).size !== graph.scheduleEntries.length) {
throw new Error("Operational schedule IDs must be unique.");
}
const reference = new Date(referenceDate);
const invalidTask = graph.tasks.find(
(task) =>
new Date(task.createdAt) > new Date(task.updatedAt) ||
new Date(task.updatedAt) > reference ||
(task.completedAt !== null && (new Date(task.completedAt) < new Date(task.createdAt) || new Date(task.completedAt) > reference)) ||
(task.status === "done") !== (task.completedAt !== null)
);
if (invalidTask) throw new Error(`Operational task ${invalidTask.id} timestamps violate the task lifecycle.`);
if (
graph.invoices.some(
(invoice) =>
new Date(invoice.createdAt) > new Date(invoice.date) ||
new Date(invoice.date) > new Date(invoice.updatedAt) ||
new Date(invoice.updatedAt) > reference ||
new Date(invoice.date) > new Date(invoice.dueAt)
)
) {
throw new Error("Operational invoice timestamps violate the invoice lifecycle.");
}
if (graph.files.some((file) => new Date(file.createdAt) > new Date(file.updatedAt) || new Date(file.updatedAt) > reference)) {
throw new Error("Operational file timestamps violate the file lifecycle.");
}
if (
graph.acceptances.some(
(acceptance) =>
new Date(acceptance.date) > new Date(acceptance.createdAt) ||
new Date(acceptance.createdAt) > new Date(acceptance.updatedAt) ||
new Date(acceptance.updatedAt) > reference
)
) {
throw new Error("Operational acceptance timestamps violate the acceptance lifecycle.");
}
if (
graph.signatureDocuments.some(
(document) =>
document.createdAt !== document.sentAt ||
new Date(document.createdAt) > new Date(document.updatedAt) ||
new Date(document.updatedAt) > reference ||
(document.status === "signed") !== (document.completedAt !== null) ||
(document.completedAt !== null && document.updatedAt !== document.completedAt)
)
) {
throw new Error("Operational signature timestamps violate the signature lifecycle.");
}
const calendarEventsById = new Map(graph.calendarEvents.map((event) => [event.id, event]));
if (
graph.scheduleEntries.some((entry) => {
if (entry.calendarEventId === null) return entry.syncStatus !== "pending";
const event = calendarEventsById.get(entry.calendarEventId);
return (
entry.syncStatus !== "synced" ||
!event ||
event.projectId !== entry.projectId ||
event.userId !== entry.assignedUserId ||
event.startsAt !== entry.startAt ||
event.endsAt !== entry.endAt
);
})
) {
throw new Error("Operational schedule entries claim calendar sync without an exact matching event.");
}
const filesById = new Map(graph.files.map((file) => [file.id, file]));
const linkedInvoiceFileIds = graph.invoices.flatMap(({ fileId }) => (fileId ? [fileId] : []));
if (
new Set(linkedInvoiceFileIds).size !== linkedInvoiceFileIds.length ||
graph.invoices.some((invoice) => {
if (invoice.fileId === null) return false;
const file = filesById.get(invoice.fileId);
return !file || file.projectId !== invoice.projectId || !file.displayName.startsWith("Rechnung_");
})
) {
throw new Error("Operational invoices contain ambiguous or semantically invalid file links.");
}
if (graph.checklistItems.some(({ photoFileId }) => photoFileId !== null)) {
throw new Error("Operational checklist items cannot use generated PDF files as photos.");
}
if (
graph.acceptances.some((acceptance) => {
if (acceptance.documentFileId === null) return false;
const file = filesById.get(acceptance.documentFileId);
return !file || file.projectId !== acceptance.projectId || !file.displayName.startsWith("Abnahmeprotokoll_");
})
) {
throw new Error("Operational acceptances contain semantically invalid document links.");
}
}
@@ -0,0 +1,176 @@
import { afterEach, describe, expect, it, vi } from "vitest";
import { type DbClient } from "@hivegrid/db/client.server";
import { verifySupportedPassword } from "../../apps/api/src/auth/password";
import { hashDemoProUserPassword, renewDemoProSeedLease, resetDemoProTenant, startDemoProSeedLeaseHeartbeat, type DemoProSeedLease } from "./persistence";
const lease: DemoProSeedLease = {
tenantId: "tenant_staging_demo_pro",
tenantSlug: "demo-pro-crm",
lockId: "demo-pro-seed-lock-tenant_staging_demo_pro",
token: "lease-token",
};
function leaseDb(updateMany: ReturnType<typeof vi.fn>): DbClient {
return { outboxEvent: { updateMany } } as unknown as DbClient;
}
afterEach(() => {
vi.useRealTimers();
});
describe("demo-pro seed lease heartbeat", () => {
it("renews only the lock owned by the current run", async () => {
const updateMany = vi.fn().mockResolvedValue({ count: 1 });
await renewDemoProSeedLease(leaseDb(updateMany), lease);
expect(updateMany).toHaveBeenCalledWith({
where: {
id: lease.lockId,
tenantId: lease.tenantId,
lastError: lease.token,
status: "PROCESSING",
},
data: { lockedUntil: expect.any(Date) },
});
});
it("keeps renewing until stopped", async () => {
vi.useFakeTimers();
const updateMany = vi.fn().mockResolvedValue({ count: 1 });
const heartbeat = startDemoProSeedLeaseHeartbeat(leaseDb(updateMany), lease, 1_000);
await heartbeat.assertHealthy();
await vi.advanceTimersByTimeAsync(3_000);
await heartbeat.assertHealthy();
expect(updateMany).toHaveBeenCalledTimes(4);
await heartbeat.stop();
await vi.advanceTimersByTimeAsync(3_000);
expect(updateMany).toHaveBeenCalledTimes(4);
});
it("fails closed when lease ownership is lost", async () => {
vi.useFakeTimers();
const updateMany = vi.fn().mockResolvedValueOnce({ count: 1 }).mockResolvedValueOnce({ count: 0 });
const heartbeat = startDemoProSeedLeaseHeartbeat(leaseDb(updateMany), lease, 1_000);
await heartbeat.assertHealthy();
await vi.advanceTimersByTimeAsync(1_000);
await expect(heartbeat.assertHealthy()).rejects.toThrow("tenant lease was lost during execution");
await expect(heartbeat.stop()).rejects.toThrow("tenant lease was lost during execution");
});
});
describe("demo-pro seed password hashing", () => {
it("uses the app-standard Argon2id hash format", async () => {
const password = "R7!qL2#vN9@xP4$kT8&m";
const hash = await hashDemoProUserPassword(password);
expect(hash).toMatch(/^\$argon2id\$/u);
await expect(verifySupportedPassword(password, hash)).resolves.toBe(true);
});
});
describe("demo-pro tenant identity reset", () => {
it("revokes John, Luna and admin sessions while preserving other memberships and global account state", async () => {
const targetTenantId = "tenant_staging_demo_pro";
const previousMemberIds = ["old-john", "old-luna", "old-admin", "seed-existing"];
const seedEmployeeIds = ["seed-existing", "seed-new"];
const order: string[] = [];
const tenantUserDeleteMany = vi.fn(async () => {
order.push("purge-target-members");
return { count: previousMemberIds.length };
});
const userSessionDeleteMany = vi.fn().mockResolvedValue({ count: 5 });
const trustedDeviceDeleteMany = vi.fn().mockResolvedValue({ count: 5 });
const magicLinkTokenDeleteMany = vi.fn().mockResolvedValue({ count: 5 });
const deviceTokenDeleteMany = vi.fn().mockResolvedValue({ count: 5 });
const roleDeleteMany = vi.fn().mockResolvedValue({ count: 7 });
const userUpdateMany = vi.fn().mockResolvedValue({ count: 1 });
const fallbackDelegates = new Map<string, { deleteMany: ReturnType<typeof vi.fn> }>();
const txTarget = {
$executeRaw: vi.fn().mockResolvedValue(undefined),
tenantUser: {
findMany: vi.fn(async () => {
order.push("capture-members");
return previousMemberIds.map((userId) => ({ userId }));
}),
deleteMany: tenantUserDeleteMany,
},
knowledgeBase: {
findMany: vi.fn().mockResolvedValue([]),
deleteMany: vi.fn().mockResolvedValue({ count: 0 }),
},
knowledgeBaseArticle: { deleteMany: vi.fn().mockResolvedValue({ count: 0 }) },
knowledgeBaseCategory: { deleteMany: vi.fn().mockResolvedValue({ count: 0 }) },
outboxEvent: {
createMany: vi.fn(async ({ data }: { data: unknown[] }) => ({ count: data.length })),
deleteMany: vi.fn().mockResolvedValue({ count: 0 }),
},
userSession: { deleteMany: userSessionDeleteMany },
trustedDevice: { deleteMany: trustedDeviceDeleteMany },
magicLinkToken: { deleteMany: magicLinkTokenDeleteMany },
deviceToken: { deleteMany: deviceTokenDeleteMany },
role: { deleteMany: roleDeleteMany },
user: { updateMany: userUpdateMany },
};
const tx = new Proxy(txTarget as Record<string, unknown>, {
get(target, property, receiver) {
if (Reflect.has(target, property)) return Reflect.get(target, property, receiver);
const key = String(property);
const delegate = fallbackDelegates.get(key) ?? { deleteMany: vi.fn().mockResolvedValue({ count: 0 }) };
fallbackDelegates.set(key, delegate);
return delegate;
},
});
const db = {
tenant: {
findUnique: vi.fn().mockResolvedValue({ id: targetTenantId, slug: "demo-pro-crm", name: "Demo Pro CRM" }),
},
outboxEvent: {
updateMany: vi.fn().mockResolvedValue({ count: 0 }),
count: vi.fn().mockResolvedValue(0),
},
$transaction: vi.fn(async (callback: (transaction: unknown) => Promise<unknown>) => callback(tx)),
} as unknown as DbClient;
await resetDemoProTenant(db, "demo-pro-crm", seedEmployeeIds);
expect(order).toEqual(["capture-members", "purge-target-members"]);
expect(tenantUserDeleteMany).toHaveBeenCalledTimes(1);
expect(tenantUserDeleteMany).toHaveBeenCalledWith({ where: { tenantId: targetTenantId } });
expect(roleDeleteMany).toHaveBeenCalledWith({
where: {
tenantId: targetTenantId,
OR: [{ isTemplateOrigin: true }, { name: { in: expect.arrayContaining(["Geschäftsführer", "Monteur"]) } }],
},
});
for (const deleteMany of [userSessionDeleteMany, trustedDeviceDeleteMany, magicLinkTokenDeleteMany]) {
expect(deleteMany).toHaveBeenCalledWith({ where: { userId: { in: seedEmployeeIds } } });
}
expect(deviceTokenDeleteMany).toHaveBeenCalledWith({ where: { tenantId: targetTenantId } });
expect(deviceTokenDeleteMany).toHaveBeenCalledWith({ where: { userId: { in: seedEmployeeIds } } });
expect(userUpdateMany).toHaveBeenNthCalledWith(1, {
where: { id: { in: previousMemberIds }, defaultTenantId: targetTenantId },
data: { defaultTenantId: null },
});
expect(userUpdateMany).toHaveBeenNthCalledWith(2, {
where: { id: { in: seedEmployeeIds } },
data: expect.objectContaining({
active: false,
defaultTenantId: null,
passwordHash: null,
totpSecretEncrypted: null,
mfaRecoveryCodeHashes: expect.anything(),
}),
});
const seedResetIds = userUpdateMany.mock.calls[1]![0].where.id.in as string[];
expect(seedResetIds).not.toContain("old-john");
expect(seedResetIds).not.toContain("old-luna");
expect(seedResetIds).not.toContain("old-admin");
});
});
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,35 @@
import { OUTBOX_MAX_PAYLOAD_BYTES } from "@hivegrid/db/outbox";
import { describe, expect, it } from "vitest";
import { generateDemoProSeed } from "./generator";
import { generateOperationalGraph } from "./operations";
import { splitSearchPayload } from "./search-batches";
describe("demo-pro search outbox batches", () => {
it("keeps the largest generated task payloads below the outbox hard limit", () => {
const graph = generateDemoProSeed();
const operational = generateOperationalGraph(graph);
const tenantId = "tenant-demo-pro";
const documents = operational.tasks.map((task) => ({
id: task.id,
tenantId,
title: task.title,
description: task.description,
status: task.status,
priority: task.priority,
linkedEntityId: task.projectId,
deadline: task.deadline,
}));
const payloadFor = (batch: readonly (typeof documents)[number][]) => ({
action: "upsert-batch",
indexName: "tasks",
tenantId,
documents: batch,
});
const batches = splitSearchPayload(documents, payloadFor);
expect(batches.flat()).toEqual(documents);
expect(batches.length).toBeLessThan(20);
expect(batches.every((batch) => Buffer.byteLength(JSON.stringify(payloadFor(batch)), "utf8") < OUTBOX_MAX_PAYLOAD_BYTES)).toBe(true);
});
});
@@ -0,0 +1,29 @@
import { OUTBOX_MAX_PAYLOAD_BYTES } from "@hivegrid/db/outbox";
const SEARCH_OUTBOX_SAFETY_MARGIN_BYTES = 8 * 1024;
export const SEARCH_OUTBOX_TARGET_BYTES = OUTBOX_MAX_PAYLOAD_BYTES - SEARCH_OUTBOX_SAFETY_MARGIN_BYTES;
function payloadBytes(value: unknown): number {
return Buffer.byteLength(JSON.stringify(value), "utf8");
}
export function splitSearchPayload<T>(values: readonly T[], payloadFor: (batch: readonly T[]) => unknown, maxItems = 250): T[][] {
const batches: T[][] = [];
let current: T[] = [];
for (const value of values) {
const candidate = [...current, value];
if (candidate.length <= maxItems && payloadBytes(payloadFor(candidate)) <= SEARCH_OUTBOX_TARGET_BYTES) {
current = candidate;
continue;
}
if (current.length === 0) throw new Error("demo-pro seed: one search document exceeds the safe outbox payload size");
batches.push(current);
current = [value];
if (payloadBytes(payloadFor(current)) > SEARCH_OUTBOX_TARGET_BYTES) {
throw new Error("demo-pro seed: one search document exceeds the safe outbox payload size");
}
}
if (current.length > 0) batches.push(current);
return batches;
}
@@ -0,0 +1,118 @@
import { ALL_SEARCH_INDEXES, createSearchClient, crmContactsIndex, type SearchClient } from "../../packages/search/src/index";
import { createInMemoryMeili } from "../../packages/search/src/testing";
import { describe, expect, it } from "vitest";
import { generateDemoProSeed } from "./generator";
import { generateOperationalGraph } from "./operations";
import { expectedDemoProSearchCounts, expectedDemoProSearchIds, type DemoProSearchIds, waitForDemoProSearch } from "./search-verification";
describe("demo-pro final search verification", () => {
it("requires every registered index to be empty after cleanup", () => {
expect(Object.values(expectedDemoProSearchCounts("cleanup")).every((count) => count === 0)).toBe(true);
});
it("derives the exact expected document IDs from the complete seed graphs", () => {
const graph = generateDemoProSeed();
const operational = generateOperationalGraph(graph);
const ids = expectedDemoProSearchIds(graph, operational);
const counts = expectedDemoProSearchCounts("apply");
for (const schema of ALL_SEARCH_INDEXES) {
expect(ids[schema.name]).toHaveLength(counts[schema.name]);
expect(new Set(ids[schema.name]).size).toBe(counts[schema.name]);
}
});
it("reads tenant-isolated counts from Meilisearch", async () => {
const meili = createInMemoryMeili();
const client = createSearchClient({ url: "http://memory", meiliFactory: meili.factory });
await client.index(crmContactsIndex.name).upsert([{ id: "tenant-a:contact-1", tenantId: "tenant-a", entityType: "contact" }]);
await expect(waitForDemoProSearch({ tenantId: "tenant-b", mode: "cleanup", timeoutMs: 0, client })).resolves.toMatchObject({
[crmContactsIndex.name]: 0,
});
});
it("uses exact tenant facets when estimated hits are capped", async () => {
const meili = createInMemoryMeili({ maxTotalHits: 1_000 });
const client = createSearchClient({ url: "http://memory", meiliFactory: meili.factory });
const expected = expectedDemoProSearchCounts("apply");
const expectedIds: DemoProSearchIds = {};
for (const schema of ALL_SEARCH_INDEXES) {
const count = expected[schema.name] ?? 0;
expectedIds[schema.name] = Array.from({ length: count }, (_, index) => `${schema.name}-${index}`);
await client.index(schema.name).upsert(
expectedIds[schema.name]!.map((id) => ({
id,
tenantId: "tenant-a",
}))
);
}
await expect(waitForDemoProSearch({ tenantId: "tenant-a", mode: "apply", timeoutMs: 0, client, expectedIdsByIndex: expectedIds })).resolves.toMatchObject({
tasks: 1_684,
});
});
it("fails when an index below the pagination cap has the right count but the wrong IDs", async () => {
const meili = createInMemoryMeili({ maxTotalHits: 1_000 });
const client = createSearchClient({ url: "http://memory", meiliFactory: meili.factory });
const expected = expectedDemoProSearchCounts("apply");
const expectedIds: DemoProSearchIds = {};
for (const schema of ALL_SEARCH_INDEXES) {
const count = expected[schema.name] ?? 0;
expectedIds[schema.name] = Array.from({ length: count }, (_, index) => `${schema.name}-${index}`);
await client.index(schema.name).upsert(
expectedIds[schema.name]!.map((id, index) => ({
id: schema.name === crmContactsIndex.name && index === 0 ? "unexpected-contact" : id,
tenantId: "tenant-a",
}))
);
}
await expect(waitForDemoProSearch({ tenantId: "tenant-a", mode: "apply", timeoutMs: 0, client, expectedIdsByIndex: expectedIds })).rejects.toThrow(
/document IDs differ/u
);
});
it("fails closed when Meilisearch omits tenant facets", async () => {
const client = createFacetClient(undefined);
await expect(waitForDemoProSearch({ tenantId: "tenant-a", mode: "cleanup", timeoutMs: 0, client })).rejects.toThrow(
/did not return an exact facet distribution/u
);
});
it("fails closed when a facet is empty despite matching documents", async () => {
const client = createFacetClient({}, 1);
await expect(waitForDemoProSearch({ tenantId: "tenant-a", mode: "cleanup", timeoutMs: 0, client })).rejects.toThrow(/omitted the tenant facet count/u);
});
it.each([-1, 1.5, Number.NaN])("rejects invalid exact tenant facet count %s", async (count) => {
const client = createFacetClient({ "tenant-a": count });
await expect(waitForDemoProSearch({ tenantId: "tenant-a", mode: "cleanup", timeoutMs: 0, client })).rejects.toThrow(/invalid tenant facet count/u);
});
});
function createFacetClient(tenantFacet: Record<string, number> | undefined, estimatedTotalHits = 0): SearchClient {
return {
index() {
return {
async ensure() {},
async search() {
return {
hits: [],
estimatedTotalHits,
...(tenantFacet === undefined ? {} : { facetDistribution: { tenantId: tenantFacet } }),
processingTimeMs: 0,
};
},
async upsert() {},
async delete() {},
async deleteByFilter() {},
};
},
async health() {
return { status: "available" };
},
};
}
@@ -0,0 +1,167 @@
import {
ALL_SEARCH_INDEXES,
createSearchClient,
crmContactsIndex,
filesIndex,
projectsIndex,
searchInIndex,
tasksIndex,
usersIndex,
type SearchClient,
} from "../../packages/search/src/index";
import type { DemoProOperationalGraph } from "./operations";
import type { DemoProSeedGraph } from "./types";
export type DemoProSearchCounts = Record<string, number>;
export type DemoProSearchIds = Record<string, readonly (string | number)[]>;
// Meilisearch caps search pagination at 1,000 documents by default. Counts
// remain exact through tenant facets; exact ID-set verification is performed
// for every index whose complete tenant slice fits inside that API boundary.
const MAX_EXACT_SEARCH_IDS = 1_000;
export function expectedDemoProSearchCounts(mode: "apply" | "cleanup"): DemoProSearchCounts {
const counts = Object.fromEntries(ALL_SEARCH_INDEXES.map(({ name }) => [name, 0]));
if (mode === "apply") {
counts[crmContactsIndex.name] = 976;
counts[projectsIndex.name] = 537;
counts[tasksIndex.name] = 1_684;
counts[filesIndex.name] = 917;
counts[usersIndex.name] = 50;
}
return counts;
}
export function expectedDemoProSearchIds(graph: DemoProSeedGraph, operational: DemoProOperationalGraph): DemoProSearchIds {
const ids: DemoProSearchIds = Object.fromEntries(ALL_SEARCH_INDEXES.map(({ name }) => [name, []]));
ids[crmContactsIndex.name] = [...graph.organizations, ...graph.persons, ...graph.leads].map(({ id }) => id);
ids[projectsIndex.name] = graph.projects.map(({ id }) => id);
ids[tasksIndex.name] = operational.tasks.map(({ id }) => id);
ids[filesIndex.name] = operational.files.map(({ id }) => id);
ids[usersIndex.name] = graph.employees.map(({ id }) => id);
return ids;
}
function searchId(value: string | number): string {
return `${typeof value === "number" ? "n" : "s"}:${String(value)}`;
}
function assertExpectedIds(ids: DemoProSearchIds, expectedCounts: DemoProSearchCounts): void {
for (const schema of ALL_SEARCH_INDEXES) {
const expectedIds = ids[schema.name];
if (!expectedIds) throw new Error(`demo-pro seed: expected Meilisearch IDs are missing for ${schema.name}`);
if (expectedIds.length !== expectedCounts[schema.name]) {
throw new Error(`demo-pro seed: expected Meilisearch ID count does not match ${schema.name}`);
}
if (new Set(expectedIds.map(searchId)).size !== expectedIds.length) {
throw new Error(`demo-pro seed: expected Meilisearch IDs are not unique for ${schema.name}`);
}
}
}
async function readSearchState(
client: SearchClient,
tenantId: string,
expectedIdsByIndex: DemoProSearchIds
): Promise<{ counts: DemoProSearchCounts; idMismatches: string[] }> {
const entries = await Promise.all(
ALL_SEARCH_INDEXES.map(async (schema) => {
const result = await searchInIndex({
client,
schema,
tenantId,
query: "",
options: { limit: 0, facets: ["tenantId"], attributesToRetrieve: [schema.primaryKey] },
});
if (!result.facetDistribution) {
throw new Error(`demo-pro seed: Meilisearch did not return an exact facet distribution for ${schema.name}`);
}
// Meilisearch returns an empty distribution (without the requested
// facet key) when the tenant filter has no matches. The response object
// itself is still mandatory so an unsupported/ignored facets request
// cannot be mistaken for an exact zero.
const count = result.facetDistribution.tenantId?.[tenantId] ?? 0;
if (count === 0 && result.estimatedTotalHits > 0) {
throw new Error(`demo-pro seed: Meilisearch omitted the tenant facet count for ${schema.name} despite matching documents`);
}
if (!Number.isSafeInteger(count) || count < 0) {
throw new Error(`demo-pro seed: Meilisearch returned an invalid tenant facet count for ${schema.name}`);
}
const expectedIds = expectedIdsByIndex[schema.name]!;
if (count !== expectedIds.length || expectedIds.length === 0 || expectedIds.length > MAX_EXACT_SEARCH_IDS) {
return { indexName: schema.name, count, idMismatch: null };
}
const documents = await searchInIndex({
client,
schema,
tenantId,
query: "",
options: {
limit: expectedIds.length,
offset: 0,
attributesToRetrieve: [schema.primaryKey],
},
});
const actualIds = documents.hits
.map(({ document }) => document[schema.primaryKey])
.map((value) => {
if (typeof value !== "string" && typeof value !== "number") {
throw new Error(`demo-pro seed: Meilisearch returned an invalid document ID for ${schema.name}`);
}
return searchId(value);
});
const actualIdSet = new Set(actualIds);
const expectedIdSet = new Set(expectedIds.map(searchId));
const exact =
actualIds.length === expectedIds.length &&
actualIdSet.size === actualIds.length &&
[...expectedIdSet].every((documentId) => actualIdSet.has(documentId));
return {
indexName: schema.name,
count,
idMismatch: exact ? null : `${schema.name}: tenant document IDs differ from the expected set`,
};
})
);
return {
counts: Object.fromEntries(entries.map(({ indexName, count }) => [indexName, count])),
idMismatches: entries.flatMap(({ idMismatch }) => (idMismatch ? [idMismatch] : [])),
};
}
export async function waitForDemoProSearch(input: {
tenantId: string;
mode: "apply" | "cleanup";
timeoutMs: number;
client?: SearchClient;
expectedIdsByIndex?: DemoProSearchIds;
}): Promise<DemoProSearchCounts> {
if (!input.client && !process.env.MEILI_URL) throw new Error("demo-pro seed: MEILI_URL is required for final search verification");
const client =
input.client ??
createSearchClient({
url: process.env.MEILI_URL!,
apiKey: process.env.MEILI_API_KEY,
timeout: 10_000,
});
const expected = expectedDemoProSearchCounts(input.mode);
const expectedIdsByIndex = input.mode === "cleanup" ? Object.fromEntries(ALL_SEARCH_INDEXES.map(({ name }) => [name, []])) : input.expectedIdsByIndex;
if (!expectedIdsByIndex) throw new Error("demo-pro seed: exact Meilisearch IDs are required for apply verification");
assertExpectedIds(expectedIdsByIndex, expected);
const deadline = Date.now() + input.timeoutMs;
let counts: DemoProSearchCounts = {};
let idMismatches: string[] = [];
do {
({ counts, idMismatches } = await readSearchState(client, input.tenantId, expectedIdsByIndex));
if (idMismatches.length === 0 && Object.entries(expected).every(([indexName, expectedCount]) => counts[indexName] === expectedCount)) {
return counts;
}
if (input.timeoutMs <= 0) break;
await new Promise((resolve) => setTimeout(resolve, 1_000));
} while (Date.now() < deadline);
throw new Error(
`demo-pro seed: Meilisearch did not reach the expected tenant state (${JSON.stringify(counts)}${
idMismatches.length > 0 ? `; ${idMismatches.join("; ")}` : ""
})`
);
}
@@ -0,0 +1,9 @@
{
"extends": "../../tsconfig.json",
"include": ["./*.ts", "../seed-demo-pro-crm.ts", "../validate-demo-pro-geodata.ts"],
"exclude": ["./*.test.ts"],
"compilerOptions": {
"types": ["@react-router/node", "vite/client"],
"noEmit": true
}
}
@@ -0,0 +1,172 @@
export const DEMO_PRO_SEED_NAMESPACE = "rheinmain-shk-v1" as const;
export type SeedAddress = {
strasse: string;
hausnummer: string;
plz: string;
ort: string;
land: "DE";
};
export type SeedChannel = {
value: string;
primaer: boolean;
label: "geschäftlich" | "privat" | "mobil" | "zentrale" | "rechnung";
};
export type EmployeeRole = "Geschäftsführer" | "Vertriebsleiter" | "Vertriebler" | "Büro/Backoffice" | "Marketing" | "Projektleiter/Bauleiter" | "Monteur";
export type SeedEmployee = {
id: string;
firstName: string;
lastName: string;
email: string;
phone: string;
role: EmployeeRole;
jobTitle: string;
seatCategory: "office" | "field";
groupNames: string[];
crewId: string | null;
active: true;
locale: "de";
};
export type SeedCrew = {
id: string;
name: string;
memberEmployeeIds: [string, string];
projectManagerEmployeeId: string;
};
export type ContactStatus = "kontakt" | "kunde" | "bestandskunde";
export type SeedOrganization = {
id: string;
kontaktTyp: "organisation";
orgName: string;
orgMerkmal: "gmbh" | "kg" | "oeffentliche_einrichtung" | "sonstige";
branche: string;
kontaktStatus: ContactStatus;
email: string;
phone: string;
additionalEmails: SeedChannel[];
additionalPhones: SeedChannel[];
address: SeedAddress;
language: "de";
ownerEmployeeId: string;
tags: string[];
};
export type SeedPerson = {
id: string;
kontaktTyp: "privatperson";
firstName: string;
lastName: string;
salutation: "Frau" | "Herr" | "Divers";
kontaktStatus: ContactStatus;
email: string;
phone: string;
additionalEmails: SeedChannel[];
additionalPhones: SeedChannel[];
address: SeedAddress;
language: "de";
ownerEmployeeId: string;
tags: string[];
};
export type SeedContactRelation = {
id: string;
organizationId: string;
personId: string;
role: "hauptkontakt" | "sekundaerkontakt" | "mitarbeiter";
context: string;
};
export type ProjectType =
| "reparatur_notdienst"
| "wartung_pruefung"
| "heizungstausch"
| "heizungsoptimierung"
| "badsanierung"
| "sanitaer_rohrarbeiten"
| "objekt_neubau"
| "lueftung_klima";
export type SeedProjectContact = {
contactId: string;
role: "auftraggeber" | "bauherr" | "rechnungsempfaenger" | "ansprechpartner";
primary: boolean;
};
export type SeedProject = {
id: string;
projectNumber: string;
projectName: string;
description: string;
projectType: ProjectType;
source: "Bestandskunde" | "Empfehlung" | "Website" | "Telefon" | "Partner" | "Ausschreibung";
priority: "niedrig" | "normal" | "hoch" | "dringend";
pipeline: "sales" | "auftrag";
stage: string;
potentialOrderValue: string | null;
orderVolume: string | null;
createdAt: string;
startDate: string | null;
deadline: string | null;
responsibleEmployeeId: string;
projectManagerEmployeeId: string;
crewIds: string[];
projectAddress: SeedAddress;
invoiceAddress: SeedAddress;
clientAddress: SeedAddress;
convertedFromLeadId: string | null;
lostReason: string | null;
wonAt: string | null;
lostAt: string | null;
contacts: SeedProjectContact[];
tags: string[];
};
export type LeadOutcome = "spam" | "disqualified" | "offer_lost" | "converted";
export type SeedLead = {
id: string;
outcome: LeadOutcome;
status: "spam" | "lost" | "converted";
source: "form" | "email" | "aircall" | "manual" | "custom";
sourceOrigin: string;
createdAt: string;
ownerEmployeeId: string;
firstName: string;
lastName: string;
email: string;
phone: string;
message: string;
furtherProcessingConsent: "ja" | "nein" | "unklar";
spamScore: number;
spamReason: string | null;
isQuarantined: boolean;
linkedContactId: string | null;
convertedProjectId: string | null;
convertedAt: string | null;
lostAt: string | null;
disqualifiedReason: string | null;
};
export type DemoProSeedGraph = {
namespace: typeof DEMO_PRO_SEED_NAMESPACE;
generatedForTenantSlug: "demo-pro-crm";
referenceDate: string;
employees: SeedEmployee[];
crews: SeedCrew[];
organizations: SeedOrganization[];
persons: SeedPerson[];
contactRelations: SeedContactRelation[];
projects: SeedProject[];
leads: SeedLead[];
};
export type SeedValidationResult = {
valid: boolean;
errors: string[];
};
@@ -0,0 +1,48 @@
#!/usr/bin/env node
// Local-only convenience wrapper around scripts/provision-rls-roles.mjs.
//
// The app-wide RLS cutover migration GRANTs to hivegrid_app / hivegrid_worker /
// hivegrid_rls_definer, so those roles must exist before `prisma migrate deploy`
// touches an empty database — otherwise migration 20260713190000 fails halfway
// and leaves the database in a failed-migration state (P3009).
//
// The managed role passwords are external deployment secrets and therefore have
// no place in .env.example or the config catalog. Locally they are irrelevant:
// dev runs with RLS_RUNTIME_MODE=off and the app connects as the DATABASE_URL
// owner, never as one of these roles. So we mint throwaway random passwords here
// instead of committing any value. Staging and production keep using
// `pnpm run db:roles:provision` with real, externally managed secrets.
import { randomBytes } from "node:crypto";
import { provisionRlsRoles, ROLE_PASSWORD_ENV } from "./provision-rls-roles.mjs";
if (process.env.NODE_ENV === "production") {
process.stderr.write("FAIL dev:db:roles is a local helper; use db:roles:provision with managed secrets instead\n");
process.exit(1);
}
const connectionString = process.env.HIVEGRID_RLS_PROVISION_DATABASE_URL ?? process.env.DIRECT_URL ?? process.env.DATABASE_URL;
if (!connectionString) {
process.stderr.write("FAIL no DATABASE_URL (or DIRECT_URL) found — copy .env.example to .env first\n");
process.exit(1);
}
const env = {
...process.env,
HIVEGRID_RLS_PROVISION_DATABASE_URL: connectionString,
};
for (const passwordEnvName of Object.values(ROLE_PASSWORD_ENV)) {
// 48 hex chars, comfortably above the provisioner's 32-character floor and
// distinct per role (it rejects duplicates).
env[passwordEnvName] = randomBytes(24).toString("hex");
}
try {
await provisionRlsRoles({ env });
process.stdout.write("PASS local RLS roles provisioned (throwaway passwords, not persisted)\n");
} catch (error) {
const message = error instanceof Error ? error.message : "role provisioning failed";
process.stderr.write(`FAIL ${message}\n`);
process.exit(1);
}
@@ -0,0 +1,14 @@
\set ON_ERROR_STOP on
-- The credential normalizer requires this database-level marker in addition
-- to process and URL guards. A loopback SSH tunnel to staging does not carry
-- the marker and therefore cannot trigger the disposable local reset.
DO $local_database_marker$
BEGIN
EXECUTE format(
'ALTER DATABASE %I SET app.local_dev_credentials = %L',
current_database(),
'enabled'
);
END
$local_database_marker$;
@@ -10,16 +10,20 @@
#
# Nutzung: bash scripts/dev/local.sh
# Dann: http://app.localhost:3000 (admin: http://admin.localhost:3000)
set -uo pipefail
set -euo pipefail
# Repo-Root (zwei Ebenen ueber dieser Datei)
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
cd "$ROOT"
# Node 22.12.0 via fnm (falls vorhanden)
# Use the repository-pinned Node version via fnm when available.
if command -v fnm >/dev/null 2>&1; then
eval "$(fnm env)"
fnm use 22.12.0 >/dev/null 2>&1 || true
node_version="$(tr -d '[:space:]' < .nvmrc)"
if ! fnm use "${node_version#v}" >/dev/null 2>&1; then
echo "FEHLER: Node ${node_version} aus .nvmrc ist lokal nicht installiert." >&2
exit 1
fi
fi
# Env laden: zuerst .env (SOPS-pull), dann .env.local (lokale Overrides gewinnen)
@@ -35,6 +39,20 @@ if [ -z "${DATABASE_URL:-}" ]; then
exit 1
fi
# Canonical disposable local credentials. The credential command additionally
# checks the local DB marker before any password or permission write.
if [ -n "${NODE_ENV:-}" ] && [ "$NODE_ENV" != "development" ]; then
echo "FEHLER: pnpm dev:local akzeptiert nur NODE_ENV=development." >&2
exit 1
fi
export NODE_ENV=development
export LOCAL_DEV_CREDENTIALS=1
export ADMIN_FALLBACK_LOGIN_ENABLED=true
export ADMIN_FALLBACK_LOGIN_EMAILS=admin@email.com
export DEMO_USER=admin@email.com:password
pnpm dev:local:credentials
# Lokales Redis (BullMQ / Session-Cache) sicherstellen
if ! nc -z localhost 6379 >/dev/null 2>&1; then
docker start hg-redis >/dev/null 2>&1 \
@@ -42,5 +60,5 @@ if ! nc -z localhost 6379 >/dev/null 2>&1; then
|| echo "WARN: konnte Redis nicht starten (BullMQ/Session-Cache evtl. eingeschraenkt)." >&2
fi
echo "Lokaler Dev-Server: http://app.localhost:3000 (admin: http://admin.localhost:3000)"
echo "Lokaler Dev-Server: http://app.localhost:3000 (admin: http://admin.localhost:3000; Login: admin@email.com / password)"
exec pnpm dev
@@ -0,0 +1,13 @@
#!/usr/bin/env bash
set -euo pipefail
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
cd "$ROOT"
# Deliberately target only this repository's Docker Compose Postgres service.
# Never follow DATABASE_URL here: it might point through a tunnel.
docker compose -f docker-compose.yml -f docker-compose.dev.yml exec -T postgres \
sh -eu -c 'exec psql -v ON_ERROR_STOP=1 -U "$POSTGRES_USER" -d "$POSTGRES_DB"' \
< scripts/dev/init-local-database.sql
echo "Marked the repository Docker Postgres database as disposable local development data."
@@ -1,31 +1,65 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-$$}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! $DOCKER_SMOKE_RUN_ID =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
# shellcheck source=scripts/lib/docker-rls-role-fixture.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-rls-role-fixture.sh"
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-runtime-smoke.sh"
IMAGE="${1:-hivegrid-api:smoke}"
MIGRATOR_IMAGE="${DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke}"
PORT="${DOCKER_API_SMOKE_PORT:-}"
CONTAINER_NAME="${DOCKER_API_SMOKE_CONTAINER:-hivegrid-api-runtime-smoke-$$}"
DB_CONTAINER_NAME="${DOCKER_API_SMOKE_DB_CONTAINER:-hivegrid-api-runtime-smoke-db-$$}"
NETWORK_NAME="${DOCKER_API_SMOKE_NETWORK:-hivegrid-api-runtime-smoke-$$}"
CONTAINER_NAME="${DOCKER_API_SMOKE_CONTAINER:-hivegrid-api-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
DB_CONTAINER_NAME="${DOCKER_API_SMOKE_DB_CONTAINER:-hivegrid-api-runtime-smoke-db-${DOCKER_SMOKE_RUN_ID}}"
REDIS_CONTAINER_NAME="${DOCKER_API_SMOKE_REDIS_CONTAINER:-hivegrid-api-runtime-smoke-redis-${DOCKER_SMOKE_RUN_ID}}"
NETWORK_NAME="${DOCKER_API_SMOKE_NETWORK:-hivegrid-api-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
MIGRATION_CONTAINER_NAME="${DOCKER_API_SMOKE_MIGRATION_CONTAINER:-hivegrid-api-runtime-smoke-migrate-${DOCKER_SMOKE_RUN_ID}}"
ASSERT_CONTAINER_NAME="${DOCKER_API_SMOKE_ASSERT_CONTAINER:-hivegrid-api-runtime-smoke-assert-${DOCKER_SMOKE_RUN_ID}}"
TRANSPORT="${DOCKER_API_SMOKE_TRANSPORT:-host}"
SMOKE_REVISION="${DOCKER_API_SMOKE_REVISION:-}"
HEALTH_ATTEMPTS="${DOCKER_API_SMOKE_HEALTH_ATTEMPTS:-300}"
HEALTH_ATTEMPTS="${DOCKER_API_SMOKE_HEALTH_ATTEMPTS:-120}"
DB_PASSWORD="hivegrid"
DB_NAME="hivegrid"
DB_USER="hivegrid"
APP_DB_PASSWORD="hivegrid-app-smoke"
WORKER_DB_PASSWORD="hivegrid-worker-smoke"
MIGRATOR_DB_PASSWORD="hivegrid-migrator-smoke"
AUTHENTIK_JIT_DB_PASSWORD="hivegrid-authentik-jit-smoke"
cleanup() {
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
docker rm -f "$DB_CONTAINER_NAME" >/dev/null 2>&1 || true
docker network rm "$NETWORK_NAME" >/dev/null 2>&1 || true
docker_smoke_cleanup_container "api:cleanup-containers" \
"$CONTAINER_NAME" "$MIGRATION_CONTAINER_NAME" "$ASSERT_CONTAINER_NAME" \
"$DB_CONTAINER_NAME" "$REDIS_CONTAINER_NAME"
docker_smoke_cleanup_network "api:cleanup-network" "$NETWORK_NAME"
}
resolve_smoke_revision() {
local image_revision
if [[ -n "$SMOKE_REVISION" ]]; then
printf "%s" "$SMOKE_REVISION"
return
fi
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
docker_smoke_capture image_revision "api:inspect-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
printf "%s" "$image_revision"
}
verify_migrator_revision() {
local migrator_revision
docker_smoke_capture migrator_revision "api:inspect-migrator-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$MIGRATOR_IMAGE"
if [[ "$migrator_revision" != "$SMOKE_REVISION" ]]; then
echo "Migrator image ${MIGRATOR_IMAGE} revision ${migrator_revision:-<empty>} does not match API image revision ${SMOKE_REVISION}" >&2
exit 1
fi
}
http_status() {
@@ -33,9 +67,15 @@ http_status() {
local code
if [[ "$TRANSPORT" == "exec" ]]; then
code="$(docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: "api.localhost" } }, (response) => { process.stdout.write(String(response.statusCode ?? "000")); response.resume(); }); request.on("error", () => process.stdout.write("000")); request.end();' "$path" || true)"
if ! docker_smoke_capture code "api:http-status" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: "api.localhost" } }, (response) => { process.stdout.write(String(response.statusCode ?? "000")); response.resume(); }); request.on("error", () => process.stdout.write("000")); request.end();' "$path" 2>/dev/null; then
code="000"
fi
else
code="$(curl -s -o /dev/null -w "%{http_code}" -H "Host: api.localhost" "http://127.0.0.1:${PORT}${path}" || true)"
if ! docker_smoke_capture code "api:http-status" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
curl -s -o /dev/null -w "%{http_code}" -H "Host: api.localhost" "http://127.0.0.1:${PORT}${path}" 2>/dev/null; then
code="000"
fi
fi
if [[ -z "$code" ]]; then
@@ -48,12 +88,17 @@ http_status() {
http_body() {
local path="$1"
local body
if [[ "$TRANSPORT" == "exec" ]]; then
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: "api.localhost" } }, (response) => { let body = ""; response.setEncoding("utf8"); response.on("data", (chunk) => { body += chunk; }); response.on("end", () => process.stdout.write(body)); }); request.on("error", () => process.exit(1)); request.end();' "$path"
docker_smoke_capture body "api:http-body" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: "api.localhost" } }, (response) => { let body = ""; response.setEncoding("utf8"); response.on("data", (chunk) => { body += chunk; }); response.on("end", () => process.stdout.write(body)); }); request.on("error", () => process.exit(1)); request.end();' "$path"
else
curl --fail --silent --show-error -H "Host: api.localhost" "http://127.0.0.1:${PORT}${path}"
docker_smoke_capture body "api:http-body" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
curl --fail --silent --show-error -H "Host: api.localhost" "http://127.0.0.1:${PORT}${path}"
fi
printf "%s" "$body"
}
expect_status() {
@@ -64,7 +109,7 @@ expect_status() {
actual="$(http_status "$path")"
if [[ "$actual" != "$expected" ]]; then
echo "Expected ${path} to return ${expected}, got ${actual}" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "api:logs-status" "$CONTAINER_NAME" >&2 || true
exit 1
fi
}
@@ -78,7 +123,7 @@ expect_health_revision() {
actual="$(printf "%s" "$body" | node -e 'const fs = require("node:fs"); try { const payload = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(payload.revision || ""); } catch { process.exit(1); }')"
if [[ "$actual" != "$SMOKE_REVISION" ]]; then
echo "Expected ${path} revision ${SMOKE_REVISION}, got ${actual:-<empty>}" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "api:logs-revision" "$CONTAINER_NAME" >&2 || true
exit 1
fi
}
@@ -98,49 +143,105 @@ if (!payload.paths || !payload.paths["/v1/health"] || !payload.paths["/v1/sessio
'
}
trap cleanup EXIT
assert_api_container_running() {
local running
if ! docker_smoke_capture running "api:inspect-running" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker inspect -f '{{.State.Running}}' "$CONTAINER_NAME" 2>/dev/null; then
running=""
fi
if [[ "$running" == "true" ]]; then
return
fi
echo "API container stopped before becoming healthy" >&2
docker_smoke_run "api:inspect-exit" "$DOCKER_SMOKE_LOG_TIMEOUT_SECONDS" docker inspect \
-f 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}} error={{json .State.Error}} finished={{.State.FinishedAt}}' \
"$CONTAINER_NAME" >&2 || true
docker_smoke_logs "api:logs-exit" "$CONTAINER_NAME" >&2 || true
return 1
}
docker_smoke_install_cleanup_traps cleanup
cleanup
SMOKE_REVISION="$(resolve_smoke_revision)"
if [[ -z "$SMOKE_REVISION" || "$SMOKE_REVISION" == "<no value>" || "$SMOKE_REVISION" == "unknown" ]]; then
echo "Image ${IMAGE} does not expose a concrete org.opencontainers.image.revision; build with --build-arg APP_REVISION or set DOCKER_API_SMOKE_REVISION explicitly" >&2
exit 1
fi
docker network create "$NETWORK_NAME" >/dev/null
verify_migrator_revision
docker_smoke_run "api:create-network" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker network create "$NETWORK_NAME" >/dev/null
docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db -p 127.0.0.1::5432 \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
CONTAINER_DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
docker_smoke_run "api:start-redis" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$REDIS_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias redis redis:7-alpine >/dev/null
for attempt in $(seq 1 30); do
if docker exec "$DB_CONTAINER_NAME" pg_isready -U "$DB_USER" -d "$DB_NAME" >/dev/null 2>&1; then
if docker_smoke_probe "api:probe-redis" docker exec "$REDIS_CONTAINER_NAME" redis-cli ping 2>/dev/null | grep -q PONG; then
break
fi
if [[ "$attempt" == "30" ]]; then
echo "Postgres smoke database did not become ready" >&2
docker logs "$DB_CONTAINER_NAME" >&2 || true
echo "Redis smoke service did not become ready" >&2
docker_smoke_logs "api:logs-redis" "$REDIS_CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
docker run --rm --network "$NETWORK_NAME" \
-e NODE_ENV=production \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
--entrypoint /bin/sh \
"$IMAGE" -lc 'cd /myapp && pnpm exec prisma migrate deploy --config prisma.config.ts' >/dev/null
docker_smoke_run "api:start-db" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
MIGRATOR_DATABASE_URL="postgresql://hivegrid_migrator:${MIGRATOR_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
APP_DATABASE_URL="postgresql://hivegrid_app:${APP_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
# Probe over TCP, not the unix socket. On first boot the postgres image starts a
# temporary server that listens on the socket ONLY (initdb + init scripts), then
# shuts it down before starting the real one. A socket-based pg_isready reports
# ready during that window, so the very next psql can hit
# "FATAL: the database system is shutting down". The temp server sets
# listen_addresses='', so a TCP probe cannot succeed too early.
if ! docker_smoke_wait_for_postgres "api:probe-db" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME"; then
echo "Postgres smoke database did not become ready within the ${DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS}-second budget" >&2
docker_smoke_logs "api:logs-db" "$DB_CONTAINER_NAME" >&2 || true
exit 1
fi
provision_docker_smoke_rls_roles \
"api:provision-rls-roles" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME" \
"$MIGRATOR_DB_PASSWORD" "$APP_DB_PASSWORD" "$WORKER_DB_PASSWORD" "$AUTHENTIK_JIT_DB_PASSWORD"
# The web image is the deployment migration authority and already contains the
# reviewed migrations plus Prisma CLI. Reusing it keeps this isolated smoke job
# independent from host package managers without widening the API runtime.
docker_smoke_run "api:migrate" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" docker run --rm --name "$MIGRATION_CONTAINER_NAME" --network "$NETWORK_NAME" \
-e DIRECT_URL="$MIGRATOR_DATABASE_URL" \
"$MIGRATOR_IMAGE" migrate
# API runtime instances never migrate schemas. Keeping the optional Prisma CLI
# out of this image cuts the attack surface and leaves migration authority with
# the dedicated deployment workflow.
docker_smoke_run "api:assert-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$ASSERT_CONTAINER_NAME" --entrypoint node "$IMAGE" -e '
try {
require.resolve("prisma");
process.exit(1);
} catch (error) {
if (error?.code !== "MODULE_NOT_FOUND") throw error;
}
' >/dev/null
publish_args=(-p 127.0.0.1::8080)
if [[ -n "$PORT" ]]; then
publish_args=(-p "${PORT}:8080")
fi
docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args[@]}" \
docker_smoke_run "api:start-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args[@]}" \
-e NODE_ENV=production \
-e PORT=8080 \
-e API_PORT=8080 \
@@ -150,26 +251,35 @@ docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args
-e ADMIN_APP_HOST=admin.localhost \
-e API_HOST=api.localhost \
-e APP_PROTOCOL=http \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
-e DATABASE_URL="$APP_DATABASE_URL" \
-e DATABASE_RUNTIME_ROLE=hivegrid_app \
-e RLS_RUNTIME_MODE=required \
-e REDIS_URL='redis://redis:6379/0' \
-e SESSION_SECRET='deploy-smoke-session-secret-minimum-32' \
-e CRYPTO_SECRET='deploy-smoke-crypto-secret-minimum-32' \
-e ADMIN_CONNECTION_MASTER_KEY='deploy-smoke-admin-connection-key-minimum-32' \
-e JWT_SECRET='deploy-smoke-jwt-secret-minimum-32' \
-e API_ACCESS_TOKEN='deploy-smoke-api-access-token-minimum-32' \
-e ANALYTICS_TOKEN='deploy-smoke-analytics-token-minimum-32' \
-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32' \
"$IMAGE" >/dev/null
if [[ -z "$PORT" ]]; then
PORT="$(docker port "$CONTAINER_NAME" 8080/tcp | awk -F: 'NR == 1 { print $NF }')"
docker_smoke_capture PORT "api:resolve-port" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker port "$CONTAINER_NAME" 8080/tcp
PORT="$(printf "%s\n" "$PORT" | awk -F: 'NR == 1 { print $NF }')"
fi
for attempt in $(seq 1 "$HEALTH_ATTEMPTS"); do
assert_api_container_running
if [[ "$(http_status /healthz)" == "200" ]]; then
break
fi
if [[ "$attempt" == "$HEALTH_ATTEMPTS" ]]; then
echo "API container did not become healthy on port ${PORT} after ${HEALTH_ATTEMPTS}s" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "api:logs-health" "$CONTAINER_NAME" >&2 || true
exit 1
fi
@@ -0,0 +1,255 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-$$}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! $DOCKER_SMOKE_RUN_ID =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
# shellcheck source=scripts/lib/docker-rls-role-fixture.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-rls-role-fixture.sh"
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-runtime-smoke.sh"
IMAGE="${1:-hivegrid-hocuspocus:smoke}"
MIGRATOR_IMAGE="${DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke}"
CONTAINER_NAME="${DOCKER_HOCUSPOCUS_SMOKE_CONTAINER:-hivegrid-hocuspocus-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
DB_CONTAINER_NAME="${DOCKER_HOCUSPOCUS_SMOKE_DB_CONTAINER:-hivegrid-hocuspocus-runtime-smoke-db-${DOCKER_SMOKE_RUN_ID}}"
NETWORK_NAME="${DOCKER_HOCUSPOCUS_SMOKE_NETWORK:-hivegrid-hocuspocus-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
MIGRATION_CONTAINER_NAME="${DOCKER_HOCUSPOCUS_SMOKE_MIGRATION_CONTAINER:-hivegrid-hocuspocus-runtime-smoke-migrate-${DOCKER_SMOKE_RUN_ID}}"
ASSERT_CONTAINER_NAME="${DOCKER_HOCUSPOCUS_SMOKE_ASSERT_CONTAINER:-hivegrid-hocuspocus-runtime-smoke-assert-${DOCKER_SMOKE_RUN_ID}}"
SMOKE_REVISION="${DOCKER_HOCUSPOCUS_SMOKE_REVISION:-}"
STARTUP_ATTEMPTS="${DOCKER_HOCUSPOCUS_SMOKE_STARTUP_ATTEMPTS:-60}"
DB_PASSWORD="hivegrid"
DB_NAME="hivegrid"
DB_USER="hivegrid"
APP_DB_PASSWORD="hivegrid-app-smoke"
WORKER_DB_PASSWORD="hivegrid-worker-smoke"
MIGRATOR_DB_PASSWORD="hivegrid-migrator-smoke"
AUTHENTIK_JIT_DB_PASSWORD="hivegrid-authentik-jit-smoke"
cleanup() {
docker_smoke_cleanup_container "hocuspocus:cleanup-containers" \
"$CONTAINER_NAME" "$MIGRATION_CONTAINER_NAME" "$ASSERT_CONTAINER_NAME" "$DB_CONTAINER_NAME"
docker_smoke_cleanup_network "hocuspocus:cleanup-network" "$NETWORK_NAME"
}
resolve_smoke_revision() {
local image_revision
if [[ -n "$SMOKE_REVISION" ]]; then
printf "%s" "$SMOKE_REVISION"
return
fi
docker_smoke_capture image_revision "hocuspocus:inspect-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
printf "%s" "$image_revision"
}
verify_migrator_revision() {
local migrator_revision
docker_smoke_capture migrator_revision "hocuspocus:inspect-migrator-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$MIGRATOR_IMAGE"
if [[ "$migrator_revision" != "$SMOKE_REVISION" ]]; then
echo "Migrator image ${MIGRATOR_IMAGE} revision ${migrator_revision:-<empty>} does not match Hocuspocus image revision ${SMOKE_REVISION}" >&2
exit 1
fi
}
docker_smoke_install_cleanup_traps cleanup
cleanup
SMOKE_REVISION="$(resolve_smoke_revision)"
if [[ -z "$SMOKE_REVISION" || "$SMOKE_REVISION" == "<no value>" || "$SMOKE_REVISION" == "unknown" ]]; then
echo "Image ${IMAGE} does not expose a concrete org.opencontainers.image.revision; build with --build-arg APP_REVISION or set DOCKER_HOCUSPOCUS_SMOKE_REVISION explicitly" >&2
exit 1
fi
verify_migrator_revision
IMAGE_USER=""
docker_smoke_capture IMAGE_USER "hocuspocus:inspect-user" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ .Config.User }}' "$IMAGE"
if [[ "$IMAGE_USER" != "node" && "$IMAGE_USER" != "1000" && "$IMAGE_USER" != "1000:1000" ]]; then
echo "Image ${IMAGE} must declare the non-root node user, got ${IMAGE_USER:-<empty>}" >&2
exit 1
fi
# Inspect the exact runtime filesystem before boot. This catches development
# artifacts and package-manager executables even when the server itself starts.
docker_smoke_run "hocuspocus:assert-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$ASSERT_CONTAINER_NAME" --entrypoint node "$IMAGE" -e '
const fs = require("node:fs");
const path = require("node:path");
if (process.getuid?.() !== 1000) {
console.error(`Expected runtime uid 1000, got ${process.getuid?.()}`);
process.exit(1);
}
const forbiddenExecutables = [
"/usr/local/bin/corepack",
"/usr/local/bin/npm",
"/usr/local/bin/npx",
"/usr/local/bin/pnpm",
"/usr/local/bin/pnpx",
"/usr/local/bin/yarn",
"/usr/local/bin/yarnpkg",
];
const retainedExecutables = forbiddenExecutables.filter((file) => fs.existsSync(file));
if (retainedExecutables.length > 0) {
console.error(`Runtime retained package-manager executables: ${retainedExecutables.join(", ")}`);
process.exit(1);
}
const roots = ["/myapp/apps/hocuspocus/dist", "/myapp/node_modules"];
const retainedSourceArtifacts = [];
for (const root of roots) {
const pending = [root];
while (pending.length > 0) {
const current = pending.pop();
for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
const absolute = path.join(current, entry.name);
if (entry.isDirectory() && !entry.isSymbolicLink()) pending.push(absolute);
else if (entry.name.endsWith(".map") || entry.name.endsWith(".d.ts")) retainedSourceArtifacts.push(absolute);
if (retainedSourceArtifacts.length >= 10) break;
}
if (retainedSourceArtifacts.length >= 10) break;
}
}
if (retainedSourceArtifacts.length > 0) {
console.error(`Runtime retained source artifacts: ${retainedSourceArtifacts.join(", ")}`);
process.exit(1);
}
const sbom = JSON.parse(fs.readFileSync("/myapp/sbom-pnpm.json", "utf8"));
if (sbom.schema !== "hivegrid.sbom-pnpm/v2" || sbom.target !== "hocuspocus") {
console.error(`Expected target-specific Hocuspocus SBOM, got schema=${sbom.schema} target=${sbom.target}`);
process.exit(1);
}
if (sbom.source !== "installed pruned pnpm runtime tree" || !Array.isArray(sbom.packages)) {
console.error("Hocuspocus SBOM must describe the installed pruned runtime tree");
process.exit(1);
}
if (sbom.packageCount !== sbom.packages.length || sbom.packageCount === 0 || "workspaces" in sbom) {
console.error("Hocuspocus SBOM package inventory is inconsistent or contains workspace development data");
process.exit(1);
}
const packageNames = new Set(sbom.packages.map((pkg) => pkg.name));
if (!packageNames.has("@hocuspocus/server")) {
console.error("Hocuspocus SBOM is missing @hocuspocus/server");
process.exit(1);
}
const forbiddenPackages = ["esbuild", "tsx", "typescript", "vitest"].filter((name) => packageNames.has(name));
if (forbiddenPackages.length > 0) {
console.error(`Hocuspocus SBOM retained development packages: ${forbiddenPackages.join(", ")}`);
process.exit(1);
}
const expectedPrismaCompilers = [
"@prisma/client/runtime/query_compiler_fast_bg.postgresql.mjs",
"@prisma/client/runtime/query_compiler_fast_bg.postgresql.wasm-base64.mjs",
];
const runtimeSource = fs.readFileSync("/myapp/apps/hocuspocus/dist/index.js", "utf8");
const importedPrismaCompilers = [...new Set(runtimeSource.match(/@prisma\/client\/runtime\/query_compiler_[^"\s)]+/gu) ?? [])].sort();
if (JSON.stringify(importedPrismaCompilers) !== JSON.stringify(expectedPrismaCompilers)) {
console.error(`Unexpected generated Prisma compiler imports: ${importedPrismaCompilers.join(", ")}`);
process.exit(1);
}
const prismaPackageEntry = fs.readdirSync("/myapp/node_modules/.pnpm").find((entry) => entry.startsWith("@prisma+client@"));
if (!prismaPackageEntry) {
console.error("Hocuspocus runtime is missing @prisma/client");
process.exit(1);
}
const prismaClientRoot = path.join("/myapp/node_modules/.pnpm", prismaPackageEntry, "node_modules/@prisma/client");
const retainedPrismaCompilers = fs.readdirSync(path.join(prismaClientRoot, "runtime")).filter((file) => file.startsWith("query_compiler_"));
if (JSON.stringify(retainedPrismaCompilers.sort()) !== JSON.stringify(expectedPrismaCompilers.map((specifier) => specifier.split("/").at(-1)).sort())) {
console.error(`Runtime retained unexpected Prisma compiler payloads: ${retainedPrismaCompilers.join(", ")}`);
process.exit(1);
}
if (fs.existsSync(path.join(prismaClientRoot, "generator-build"))) {
console.error("Runtime retained the build-only Prisma client generator");
process.exit(1);
}
Promise.all(expectedPrismaCompilers.map((specifier) => import(specifier))).catch((error) => {
console.error(`Retained Prisma compiler failed to load: ${error.message}`);
process.exit(1);
});
' >/dev/null
docker_smoke_run "hocuspocus:create-network" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker network create "$NETWORK_NAME" >/dev/null
docker_smoke_run "hocuspocus:start-db" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
# Probe over TCP, not the unix socket. On first boot the postgres image starts a
# temporary server that listens on the socket ONLY (initdb + init scripts), then
# shuts it down before starting the real one. A socket-based pg_isready reports
# ready during that window, so the very next psql can hit
# "FATAL: the database system is shutting down". The temp server sets
# listen_addresses='', so a TCP probe cannot succeed too early.
if ! docker_smoke_wait_for_postgres "hocuspocus:probe-db" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME"; then
echo "Postgres smoke database did not become ready within the ${DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS}-second budget" >&2
docker_smoke_logs "hocuspocus:logs-db" "$DB_CONTAINER_NAME" >&2 || true
exit 1
fi
MIGRATOR_DATABASE_URL="postgresql://hivegrid_migrator:${MIGRATOR_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
APP_DATABASE_URL="postgresql://hivegrid_app:${APP_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
provision_docker_smoke_rls_roles \
"hocuspocus:provision-rls-roles" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME" \
"$MIGRATOR_DB_PASSWORD" "$APP_DB_PASSWORD" "$WORKER_DB_PASSWORD" "$AUTHENTIK_JIT_DB_PASSWORD"
docker_smoke_run "hocuspocus:migrate" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" docker run --rm --name "$MIGRATION_CONTAINER_NAME" --network "$NETWORK_NAME" \
-e DIRECT_URL="$MIGRATOR_DATABASE_URL" \
"$MIGRATOR_IMAGE" migrate
docker_smoke_run "hocuspocus:start-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" \
-e NODE_ENV=production \
-e HOCUSPOCUS_AUTH_SECRET="smoke-only-hocuspocus-auth-secret-not-real" \
-e DATABASE_URL="$APP_DATABASE_URL" \
-e DATABASE_RUNTIME_ROLE=hivegrid_app \
-e RLS_RUNTIME_MODE=required \
"$IMAGE" >/dev/null
for attempt in $(seq 1 "$STARTUP_ATTEMPTS"); do
if docker_smoke_probe "hocuspocus:probe-listener" docker exec "$CONTAINER_NAME" node -e '
const socket = require("node:net").connect(1234, "127.0.0.1");
socket.setTimeout(1000);
socket.once("connect", () => { socket.destroy(); process.exit(0); });
socket.once("timeout", () => { socket.destroy(); process.exit(1); });
socket.once("error", () => process.exit(1));
' >/dev/null 2>&1; then
break
fi
running=""
docker_smoke_capture running "hocuspocus:inspect-running" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker inspect -f '{{.State.Running}}' "$CONTAINER_NAME" 2>/dev/null || true
if [[ "$running" != "true" ]]; then
echo "Hocuspocus container exited before opening its TCP listener" >&2
docker_smoke_logs "hocuspocus:logs-exit" "$CONTAINER_NAME" >&2 || true
exit 1
fi
if [[ "$attempt" == "$STARTUP_ATTEMPTS" ]]; then
echo "Hocuspocus container did not open port 1234 after ${STARTUP_ATTEMPTS}s" >&2
docker_smoke_logs "hocuspocus:logs-startup" "$CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
RUNTIME_REVISION=""
docker_smoke_capture RUNTIME_REVISION "hocuspocus:runtime-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node -e 'process.stdout.write(process.env.APP_REVISION || "")'
if [[ "$RUNTIME_REVISION" != "$SMOKE_REVISION" ]]; then
echo "Expected runtime revision ${SMOKE_REVISION}, got ${RUNTIME_REVISION:-<empty>}" >&2
exit 1
fi
echo "Docker Hocuspocus runtime smoke passed for ${IMAGE}"
@@ -1,24 +1,67 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-$$}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! $DOCKER_SMOKE_RUN_ID =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
# shellcheck source=scripts/lib/docker-rls-role-fixture.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-rls-role-fixture.sh"
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-runtime-smoke.sh"
IMAGE="${1:-hivegrid-mcp:smoke}"
MIGRATOR_IMAGE="${DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke}"
PORT="${DOCKER_MCP_SMOKE_PORT:-}"
CONTAINER_NAME="${DOCKER_MCP_SMOKE_CONTAINER:-hivegrid-mcp-runtime-smoke-$$}"
CONTAINER_NAME="${DOCKER_MCP_SMOKE_CONTAINER:-hivegrid-mcp-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
REDIS_CONTAINER_NAME="${DOCKER_MCP_SMOKE_REDIS_CONTAINER:-hivegrid-mcp-runtime-smoke-redis-${DOCKER_SMOKE_RUN_ID}}"
DB_CONTAINER_NAME="${DOCKER_MCP_SMOKE_DB_CONTAINER:-hivegrid-mcp-runtime-smoke-db-${DOCKER_SMOKE_RUN_ID}}"
NETWORK_NAME="${DOCKER_MCP_SMOKE_NETWORK:-hivegrid-mcp-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
MIGRATION_CONTAINER_NAME="${DOCKER_MCP_SMOKE_MIGRATION_CONTAINER:-hivegrid-mcp-runtime-smoke-migrate-${DOCKER_SMOKE_RUN_ID}}"
ASSERT_CONTAINER_NAME="${DOCKER_MCP_SMOKE_ASSERT_CONTAINER:-hivegrid-mcp-runtime-smoke-assert-${DOCKER_SMOKE_RUN_ID}}"
TRANSPORT="${DOCKER_MCP_SMOKE_TRANSPORT:-host}"
SMOKE_REVISION="${DOCKER_MCP_SMOKE_REVISION:-}"
EXPECTED_SMOKE_REVISION="${DOCKER_MCP_SMOKE_REVISION:-}"
SMOKE_REVISION=""
HEALTH_ATTEMPTS="${DOCKER_MCP_SMOKE_HEALTH_ATTEMPTS:-120}"
DEPENDENCY_ATTEMPTS="${DOCKER_MCP_SMOKE_DEPENDENCY_ATTEMPTS:-30}"
DB_PASSWORD="hivegrid"
DB_NAME="hivegrid"
DB_USER="hivegrid"
APP_DB_PASSWORD="hivegrid-app-smoke"
WORKER_DB_PASSWORD="hivegrid-worker-smoke"
MIGRATOR_DB_PASSWORD="hivegrid-migrator-smoke"
AUTHENTIK_JIT_DB_PASSWORD="hivegrid-authentik-jit-smoke"
cleanup() {
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
docker_smoke_cleanup_container "mcp:cleanup-containers" \
"$CONTAINER_NAME" "$MIGRATION_CONTAINER_NAME" "$ASSERT_CONTAINER_NAME" \
"$REDIS_CONTAINER_NAME" "$DB_CONTAINER_NAME"
docker_smoke_cleanup_network "mcp:cleanup-network" "$NETWORK_NAME"
}
resolve_smoke_revision() {
if [[ -n "$SMOKE_REVISION" ]]; then
printf "%s" "$SMOKE_REVISION"
return
local image_revision
docker_smoke_capture image_revision "mcp:inspect-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
if [[ -n "$EXPECTED_SMOKE_REVISION" && "$EXPECTED_SMOKE_REVISION" != "$image_revision" ]]; then
echo "Image ${IMAGE} revision ${image_revision:-<empty>} does not match expected revision ${EXPECTED_SMOKE_REVISION}" >&2
return 1
fi
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
printf "%s" "$image_revision"
}
verify_migrator_revision() {
local migrator_revision
docker_smoke_capture migrator_revision "mcp:inspect-migrator-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$MIGRATOR_IMAGE"
if [[ "$migrator_revision" != "$SMOKE_REVISION" ]]; then
echo "Migrator image ${MIGRATOR_IMAGE} revision ${migrator_revision:-<empty>} does not match MCP image revision ${SMOKE_REVISION}" >&2
exit 1
fi
}
http_status() {
@@ -27,9 +70,15 @@ http_status() {
local code
if [[ "$TRANSPORT" == "exec" ]]; then
code="$(docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path, method] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, method, headers: { Host: "mcp.hivegrid.de" } }, (response) => { process.stdout.write(String(response.statusCode ?? "000")); response.resume(); }); request.on("error", () => process.stdout.write("000")); request.end();' "$path" "$method" || true)"
if ! docker_smoke_capture code "mcp:http-status" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path, method] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, method, headers: { Host: "mcp.hivegrid.de" } }, (response) => { process.stdout.write(String(response.statusCode ?? "000")); response.resume(); }); request.on("error", () => process.stdout.write("000")); request.end();' "$path" "$method" 2>/dev/null; then
code="000"
fi
else
code="$(curl -s -o /dev/null -w "%{http_code}" -X "$method" -H "Host: mcp.hivegrid.de" "http://127.0.0.1:${PORT}${path}" || true)"
if ! docker_smoke_capture code "mcp:http-status" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
curl -s -o /dev/null -w "%{http_code}" -X "$method" -H "Host: mcp.hivegrid.de" "http://127.0.0.1:${PORT}${path}" 2>/dev/null; then
code="000"
fi
fi
if [[ -z "$code" ]]; then
@@ -42,12 +91,17 @@ http_status() {
http_body() {
local path="$1"
local body
if [[ "$TRANSPORT" == "exec" ]]; then
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: "mcp.hivegrid.de" } }, (response) => { let body = ""; response.setEncoding("utf8"); response.on("data", (chunk) => { body += chunk; }); response.on("end", () => process.stdout.write(body)); }); request.on("error", () => process.exit(1)); request.end();' "$path"
docker_smoke_capture body "mcp:http-body" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: "mcp.hivegrid.de" } }, (response) => { let body = ""; response.setEncoding("utf8"); response.on("data", (chunk) => { body += chunk; }); response.on("end", () => process.stdout.write(body)); }); request.on("error", () => process.exit(1)); request.end();' "$path"
else
curl --fail --silent --show-error -H "Host: mcp.hivegrid.de" "http://127.0.0.1:${PORT}${path}"
docker_smoke_capture body "mcp:http-body" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
curl --fail --silent --show-error -H "Host: mcp.hivegrid.de" "http://127.0.0.1:${PORT}${path}"
fi
printf "%s" "$body"
}
expect_status() {
@@ -59,11 +113,28 @@ expect_status() {
actual="$(http_status "$path" "$method")"
if [[ "$actual" != "$expected" ]]; then
echo "Expected ${method} ${path} to return ${expected}, got ${actual}" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "mcp:logs-status" "$CONTAINER_NAME" >&2 || true
exit 1
fi
}
wait_for_status() {
local path="$1"
local expected="$2"
local description="$3"
for attempt in $(seq 1 "$DEPENDENCY_ATTEMPTS"); do
if [[ "$(http_status "$path")" == "$expected" ]]; then
return
fi
sleep 1
done
echo "MCP ${description} did not reach HTTP ${expected} within ${DEPENDENCY_ATTEMPTS}s" >&2
docker_smoke_logs "mcp:logs-readiness" "$CONTAINER_NAME" >&2 || true
exit 1
}
expect_health_revision() {
local body
local actual
@@ -74,34 +145,118 @@ expect_health_revision() {
service="$(printf "%s" "$body" | node -e 'const fs = require("node:fs"); const payload = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(payload.service || "");')"
if [[ "$actual" != "$SMOKE_REVISION" || "$service" != "mcp" ]]; then
echo "Expected /healthz service=mcp revision=${SMOKE_REVISION}, got service=${service:-<empty>} revision=${actual:-<empty>}" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "mcp:logs-revision" "$CONTAINER_NAME" >&2 || true
exit 1
fi
}
trap cleanup EXIT
expect_deploy_health() {
local output="$1"
printf "%s" "$output" | node -e '
const expectedRevision = process.argv[1];
const payload = JSON.parse(require("node:fs").readFileSync(0, "utf8"));
if (payload.status !== "ready" || payload.service !== "mcp" || payload.revision !== expectedRevision) {
console.error("MCP deployment health did not prove the expected live revision");
process.exit(1);
}
' "$SMOKE_REVISION"
}
docker_smoke_install_cleanup_traps cleanup
cleanup
SMOKE_REVISION="$(resolve_smoke_revision)"
if [[ -z "$SMOKE_REVISION" || "$SMOKE_REVISION" == "<no value>" || "$SMOKE_REVISION" == "unknown" ]]; then
echo "Image ${IMAGE} does not expose a concrete org.opencontainers.image.revision; build with --build-arg APP_REVISION or set DOCKER_MCP_SMOKE_REVISION explicitly" >&2
echo "Image ${IMAGE} does not expose a concrete org.opencontainers.image.revision; build with --build-arg APP_REVISION" >&2
exit 1
fi
verify_migrator_revision
docker_smoke_run "mcp:create-network" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker network create "$NETWORK_NAME" >/dev/null
docker_smoke_run "mcp:start-redis" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$REDIS_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias redis redis:7-alpine >/dev/null
docker_smoke_run "mcp:start-db" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
MIGRATOR_DATABASE_URL="postgresql://hivegrid_migrator:${MIGRATOR_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
APP_DATABASE_URL="postgresql://hivegrid_app:${APP_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
for attempt in $(seq 1 30); do
if docker_smoke_probe "mcp:probe-redis" docker exec "$REDIS_CONTAINER_NAME" redis-cli ping 2>/dev/null | grep -q PONG; then
break
fi
if [[ "$attempt" == "30" ]]; then
echo "Redis smoke service did not become ready" >&2
docker_smoke_logs "mcp:logs-redis" "$REDIS_CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
# Probe over TCP, not the unix socket. On first boot the postgres image starts a
# temporary server that listens on the socket ONLY (initdb + init scripts), then
# shuts it down before starting the real one. A socket-based pg_isready reports
# ready during that window, so the very next psql can hit
# "FATAL: the database system is shutting down". The temp server sets
# listen_addresses='', so a TCP probe cannot succeed too early.
if ! docker_smoke_wait_for_postgres "mcp:probe-db" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME"; then
echo "Postgres smoke database did not become ready within the ${DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS}-second budget" >&2
docker_smoke_logs "mcp:logs-db" "$DB_CONTAINER_NAME" >&2 || true
exit 1
fi
provision_docker_smoke_rls_roles \
"mcp:provision-rls-roles" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME" \
"$MIGRATOR_DB_PASSWORD" "$APP_DB_PASSWORD" "$WORKER_DB_PASSWORD" "$AUTHENTIK_JIT_DB_PASSWORD"
# Exercise the same reviewed migration closure as deployment. MCP readiness
# queries both credential tables, so an unmigrated database must stay unready.
docker_smoke_run "mcp:migrate" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" docker run --rm --name "$MIGRATION_CONTAINER_NAME" --network "$NETWORK_NAME" \
-e DIRECT_URL="$MIGRATOR_DATABASE_URL" \
"$MIGRATOR_IMAGE" migrate
# MCP instances never migrate schemas or compile source. Keep build-only
# toolchains out of the remotely reachable runtime closure.
docker_smoke_run "mcp:assert-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$ASSERT_CONTAINER_NAME" --entrypoint node "$IMAGE" -e '
for (const specifier of ["prisma", "typescript", "@prisma/engines"]) {
try {
require.resolve(specifier);
throw new Error(`MCP runtime retained build-only package ${specifier}`);
} catch (error) {
if (error?.code !== "MODULE_NOT_FOUND") throw error;
}
}
' >/dev/null
publish_args=(-p 127.0.0.1::8080)
if [[ -n "$PORT" ]]; then
publish_args=(-p "${PORT}:8080")
fi
docker run -d --name "$CONTAINER_NAME" "${publish_args[@]}" \
docker_smoke_run "mcp:start-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args[@]}" \
-e NODE_ENV=production \
-e PORT=8080 \
-e MCP_PORT=8080 \
-e APP_REVISION="$SMOKE_REVISION" \
-e DATABASE_URL="$APP_DATABASE_URL" \
-e DATABASE_RUNTIME_ROLE=hivegrid_app \
-e RLS_RUNTIME_MODE=required \
-e REDIS_URL='redis://redis:6379/0' \
-e MCP_OAUTH_TOKEN_HASH_SECRET="smoke-only-mcp-token-hash-secret-not-real" \
-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32' \
"$IMAGE" >/dev/null
if [[ -z "$PORT" ]]; then
PORT="$(docker port "$CONTAINER_NAME" 8080/tcp | awk -F: 'NR == 1 { print $NF }')"
docker_smoke_capture PORT "mcp:resolve-port" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker port "$CONTAINER_NAME" 8080/tcp
PORT="$(printf "%s\n" "$PORT" | awk -F: 'NR == 1 { print $NF }')"
fi
for attempt in $(seq 1 "$HEALTH_ATTEMPTS"); do
@@ -111,7 +266,7 @@ for attempt in $(seq 1 "$HEALTH_ATTEMPTS"); do
if [[ "$attempt" == "$HEALTH_ATTEMPTS" ]]; then
echo "MCP container did not become healthy on port ${PORT} after ${HEALTH_ATTEMPTS}s" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "mcp:logs-health" "$CONTAINER_NAME" >&2 || true
exit 1
fi
@@ -120,8 +275,56 @@ done
expect_status /healthz 200
expect_health_revision
expect_status /readyz 200
wait_for_status /readyz 200 "initial dependency readiness"
docker_smoke_run "mcp:assert-revision-file" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker exec "$CONTAINER_NAME" node -e '
const fs = require("node:fs");
const expectedRevision = process.argv[1];
const path = "/myapp/.image-revision";
const stat = fs.statSync(path);
const actualRevision = fs.readFileSync(path, "utf8").trim();
if (stat.uid !== 0 || (stat.mode & 0o022) !== 0 || actualRevision !== expectedRevision) {
console.error("MCP immutable image revision file is not root-owned, read-only, and exact");
process.exit(1);
}
' "$SMOKE_REVISION"
deploy_health_output=""
docker_smoke_capture deploy_health_output "mcp:deploy-health" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node apps/mcp/dist/deploy-health.js "$SMOKE_REVISION"
expect_deploy_health "$deploy_health_output"
MISMATCHED_REVISION="$(printf '0%.0s' {1..40})"
if [[ "$MISMATCHED_REVISION" == "$SMOKE_REVISION" ]]; then
MISMATCHED_REVISION="$(printf 'f%.0s' {1..40})"
fi
docker_smoke_expect_docker_exec_rejection "mcp:reject-spoofed-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
env APP_REVISION="$MISMATCHED_REVISION" \
node apps/mcp/dist/deploy-health.js "$MISMATCHED_REVISION"
expect_status /mcp 404 POST
expect_status / 401 POST
# Readiness must reflect the exact Redis and Postgres dependencies used by
# authenticated MCP traffic while liveness remains process-only.
docker_smoke_run "mcp:stop-redis" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker stop "$REDIS_CONTAINER_NAME" >/dev/null
wait_for_status /readyz 503 "Redis outage readiness"
expect_status /healthz 200
docker_smoke_expect_docker_exec_rejection "mcp:reject-redis-outage" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
node apps/mcp/dist/deploy-health.js "$SMOKE_REVISION"
docker_smoke_run "mcp:start-redis-recovery" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker start "$REDIS_CONTAINER_NAME" >/dev/null
for attempt in $(seq 1 30); do
if docker_smoke_probe "mcp:probe-redis-recovery" docker exec "$REDIS_CONTAINER_NAME" redis-cli ping 2>/dev/null | grep -q PONG; then
break
fi
sleep 1
done
wait_for_status /readyz 200 "Redis recovery readiness"
docker_smoke_capture deploy_health_output "mcp:deploy-health-recovery" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node apps/mcp/dist/deploy-health.js "$SMOKE_REVISION"
expect_deploy_health "$deploy_health_output"
docker_smoke_run "mcp:stop-db" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker stop "$DB_CONTAINER_NAME" >/dev/null
wait_for_status /readyz 503 "Postgres outage readiness"
expect_status /healthz 200
docker_smoke_expect_docker_exec_rejection "mcp:reject-db-outage" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
node apps/mcp/dist/deploy-health.js "$SMOKE_REVISION"
echo "Docker MCP runtime smoke passed for ${IMAGE}"
@@ -0,0 +1,206 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-$$}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! $DOCKER_SMOKE_RUN_ID =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-runtime-smoke.sh"
IMAGE="${1:-hivegrid-portal-domain-controller:smoke}"
CONTAINER_NAME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_CONTAINER:-hivegrid-portal-domain-controller-smoke-${DOCKER_SMOKE_RUN_ID}}"
REDIS_CONTAINER_NAME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_REDIS_CONTAINER:-hivegrid-portal-domain-controller-redis-${DOCKER_SMOKE_RUN_ID}}"
NETWORK_NAME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_NETWORK:-hivegrid-portal-domain-controller-smoke-${DOCKER_SMOKE_RUN_ID}}"
CONFIG_VOLUME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_VOLUME:-hivegrid-portal-domain-controller-config-${DOCKER_SMOKE_RUN_ID}}"
RELOAD_TRIGGER_VOLUME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_RELOAD_VOLUME:-hivegrid-portal-domain-controller-reload-${DOCKER_SMOKE_RUN_ID}}"
ASSERT_CONTAINER_NAME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_ASSERT_CONTAINER:-hivegrid-portal-domain-controller-assert-${DOCKER_SMOKE_RUN_ID}}"
CONFIG_INIT_CONTAINER_NAME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_CONFIG_INIT_CONTAINER:-hivegrid-portal-domain-controller-config-init-${DOCKER_SMOKE_RUN_ID}}"
RELOAD_INIT_CONTAINER_NAME="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_RELOAD_INIT_CONTAINER:-hivegrid-portal-domain-controller-reload-init-${DOCKER_SMOKE_RUN_ID}}"
EXPECTED_REVISION="${DOCKER_PORTAL_DOMAIN_CONTROLLER_SMOKE_REVISION:-}"
COMMAND_SECRET="smoke-command-secret-that-is-not-a-production-secret"
METRICS_TOKEN="smoke-metrics-token-that-is-not-a-production-token"
cleanup() {
docker_smoke_cleanup_container "portal-controller:cleanup-containers" \
"$CONTAINER_NAME" "$REDIS_CONTAINER_NAME" "$ASSERT_CONTAINER_NAME" \
"$CONFIG_INIT_CONTAINER_NAME" "$RELOAD_INIT_CONTAINER_NAME"
docker_smoke_cleanup_network "portal-controller:cleanup-network" "$NETWORK_NAME"
docker_smoke_cleanup_volume "portal-controller:cleanup-volumes" "$CONFIG_VOLUME" "$RELOAD_TRIGGER_VOLUME"
}
http_status() {
local path="$1"
local token="${2:-}"
local code
if ! docker_smoke_capture code "portal-controller:http-status" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node -e '
const [path, token] = process.argv.slice(1);
const headers = token ? { authorization: `Bearer ${token}` } : {};
fetch(`http://127.0.0.1:8080${path}`, { headers })
.then((response) => { process.stdout.write(String(response.status)); })
.catch(() => { process.stdout.write("000"); });
' "$path" "$token" 2>/dev/null; then
code="000"
fi
printf "%s" "$code"
}
expect_status() {
local path="$1"
local expected="$2"
local token="${3:-}"
local actual
actual="$(http_status "$path" "$token")"
if [[ "$actual" != "$expected" ]]; then
echo "Portal-domain controller ${path} returned ${actual:-<empty>}, expected ${expected}" >&2
docker_smoke_logs "portal-controller:logs-status" "$CONTAINER_NAME" >&2 || true
exit 1
fi
}
docker_smoke_install_cleanup_traps cleanup
cleanup
docker_smoke_capture IMAGE_USER "portal-controller:inspect-user" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ .Config.User }}' "$IMAGE"
if [[ "$IMAGE_USER" != "node" && "$IMAGE_USER" != "1000" && "$IMAGE_USER" != "1000:1000" ]]; then
echo "Portal-domain controller image must declare the non-root node user, got ${IMAGE_USER:-<empty>}" >&2
exit 1
fi
docker_smoke_capture IMAGE_REVISION "portal-controller:inspect-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
if [[ ! "$IMAGE_REVISION" =~ ^[0-9a-fA-F]{40}$ ]]; then
echo "Portal-domain controller image does not expose a concrete org.opencontainers.image.revision" >&2
exit 1
fi
if [[ -n "$EXPECTED_REVISION" && "$IMAGE_REVISION" != "$EXPECTED_REVISION" ]]; then
echo "Portal-domain controller image revision ${IMAGE_REVISION:-<empty>} does not match ${EXPECTED_REVISION}" >&2
exit 1
fi
EXPECTED_REVISION="$IMAGE_REVISION"
docker_smoke_run "portal-controller:assert-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$ASSERT_CONTAINER_NAME" --entrypoint node "$IMAGE" -e '
const fs = require("node:fs");
const path = require("node:path");
if (process.getuid?.() !== 1000) throw new Error(`expected uid 1000, got ${process.getuid?.()}`);
if (!fs.existsSync("/usr/bin/flock")) throw new Error("runtime is missing the kernel flock binary");
for (const executable of ["/usr/local/bin/corepack", "/usr/local/bin/npm", "/usr/local/bin/npx", "/usr/local/bin/pnpm", "/usr/local/bin/pnpx", "/usr/local/bin/yarn"]) {
if (fs.existsSync(executable)) throw new Error(`runtime retained package manager ${executable}`);
}
for (const root of ["/myapp/apps/portal-domain-controller/dist", "/myapp/node_modules"]) {
const pending = [root];
while (pending.length > 0) {
const current = pending.pop();
for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
const absolute = path.join(current, entry.name);
if (entry.isDirectory() && !entry.isSymbolicLink()) pending.push(absolute);
if (entry.name.endsWith(".map") || entry.name.endsWith(".d.ts")) throw new Error(`runtime retained source artifact ${absolute}`);
}
}
}
const sbom = JSON.parse(fs.readFileSync("/myapp/sbom-pnpm.json", "utf8"));
if (sbom.schema !== "hivegrid.sbom-pnpm/v2" || sbom.target !== "portal-domain-controller") throw new Error("wrong controller SBOM target");
if (sbom.source !== "installed pruned pnpm runtime tree" || !Array.isArray(sbom.packages) || sbom.packageCount !== sbom.packages.length) throw new Error("invalid controller SBOM inventory");
const packages = new Set(sbom.packages.map((entry) => entry.name));
for (const required of ["bullmq", "ioredis", "pino", "prom-client"]) if (!packages.has(required)) throw new Error(`SBOM missing ${required}`);
for (const forbidden of ["@prisma/client", "pg", "prisma", "tsx", "typescript", "vitest", "esbuild"]) if (packages.has(forbidden)) throw new Error(`SBOM retained forbidden package ${forbidden}`);
' >/dev/null
docker_smoke_run "portal-controller:create-network" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker network create "$NETWORK_NAME" >/dev/null
docker_smoke_run "portal-controller:create-config-volume" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker volume create "$CONFIG_VOLUME" >/dev/null
docker_smoke_run "portal-controller:create-reload-volume" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker volume create "$RELOAD_TRIGGER_VOLUME" >/dev/null
docker_smoke_run "portal-controller:init-config-volume" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$CONFIG_INIT_CONTAINER_NAME" --user 0 --entrypoint node \
-v "$CONFIG_VOLUME:/data/coolify/proxy/dynamic/hivegrid-portal-domains" \
"$IMAGE" -e 'require("node:fs").chownSync("/data/coolify/proxy/dynamic/hivegrid-portal-domains", 1000, 1000)' >/dev/null
docker_smoke_run "portal-controller:init-reload-volume" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$RELOAD_INIT_CONTAINER_NAME" --user 0 --entrypoint node \
-v "$RELOAD_TRIGGER_VOLUME:/sentinel" \
"$IMAGE" -e '
const fs = require("node:fs");
const file = "/sentinel/.hivegrid-portal-domains.reload";
fs.writeFileSync(file, "ready\n", { mode: 0o600, flag: "wx" });
fs.chownSync(file, 1000, 1000);
fs.chmodSync(file, 0o600);
' >/dev/null
docker_smoke_run "portal-controller:start-redis" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$REDIS_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias redis redis:7-alpine >/dev/null
for attempt in $(seq 1 30); do
if docker_smoke_probe "portal-controller:probe-redis" docker exec "$REDIS_CONTAINER_NAME" redis-cli ping 2>/dev/null | grep -q PONG; then break; fi
if [[ "$attempt" == "30" ]]; then
echo "Controller smoke Redis did not become ready" >&2
docker_smoke_logs "portal-controller:logs-redis" "$REDIS_CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
docker_smoke_run "portal-controller:start-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" \
-v "$CONFIG_VOLUME:/data/coolify/proxy/dynamic/hivegrid-portal-domains" \
--mount "type=volume,source=$RELOAD_TRIGGER_VOLUME,destination=/data/coolify/proxy/dynamic/.hivegrid-portal-domains.reload,volume-subpath=.hivegrid-portal-domains.reload" \
-e PORTAL_DOMAIN_CONTROLLER_REDIS_URL="redis://redis:6379/0" \
-e PORTAL_DOMAIN_CONTROLLER_COMMAND_SECRET="$COMMAND_SECRET" \
-e PORTAL_DOMAIN_CONTROLLER_METRICS_TOKEN="$METRICS_TOKEN" \
-e PORTAL_DOMAIN_CONTROLLER_EXPECTED_CNAME="portal-ingress.tool-ctrl.de" \
-e PORTAL_DOMAIN_CONTROLLER_ENTRYPOINT="https" \
-e PORTAL_DOMAIN_CONTROLLER_BACKEND_SERVICE="hivegrid-portal@docker" \
-e COOLIFY_BRANCH="main" \
-e COOLIFY_CONTAINER_NAME="hivegrid-portal-domain-controller-smoke" \
-e COOLIFY_FQDN="" \
-e COOLIFY_RESOURCE_UUID="joyyh5b89vpfp8ocri8xr96m" \
-e COOLIFY_URL="" \
-e GIT_SHA="$EXPECTED_REVISION" \
"$IMAGE" >/dev/null
for attempt in $(seq 1 60); do
if [[ "$(http_status /readyz)" == "200" ]]; then break; fi
if [[ "$attempt" == "60" ]]; then
echo "Portal-domain controller did not become ready" >&2
docker_smoke_logs "portal-controller:logs-readiness" "$CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
expect_status /healthz 200
expect_status /readyz 200
expect_status /metrics 401
expect_status /metrics 200 "$METRICS_TOKEN"
docker_smoke_run "portal-controller:assert-health-payload" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" docker exec "$CONTAINER_NAME" node -e '
fetch("http://127.0.0.1:8080/healthz")
.then((response) => response.json())
.then((payload) => {
if (payload.status !== "ok" || payload.service !== "hivegrid-portal-domain-controller" || payload.revision !== process.argv[1]) process.exit(1);
});
' "$EXPECTED_REVISION"
docker_smoke_run "portal-controller:deploy-health" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node apps/portal-domain-controller/dist/deploy-health.js "$EXPECTED_REVISION" >/dev/null
FOREIGN_REVISION="$(printf 'f%.0s' {1..40})"
if [[ "$FOREIGN_REVISION" == "$EXPECTED_REVISION" ]]; then
FOREIGN_REVISION="$(printf 'e%.0s' {1..40})"
fi
docker_smoke_expect_docker_exec_rejection "portal-controller:reject-foreign-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
node apps/portal-domain-controller/dist/deploy-health.js "$FOREIGN_REVISION"
RUNTIME_ENV_KEYS=""
docker_smoke_capture RUNTIME_ENV_KEYS "portal-controller:inspect-runtime-env" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
bash -o pipefail -c 'docker inspect -f '\''{{range .Config.Env}}{{println .}}{{end}}'\'' "$1" | sed '\''s/=.*//'\''' \
_ "$CONTAINER_NAME"
for forbidden in DATABASE_URL DIRECT_URL DOCKER_HOST COOLIFY_TOKEN CLOUDFLARE_API_TOKEN SSH_PRIVATE_KEY; do
if grep -qx "$forbidden" <<<"$RUNTIME_ENV_KEYS"; then
echo "Controller runtime received forbidden credential ${forbidden}" >&2
exit 1
fi
done
echo "Portal-domain controller runtime smoke passed for ${IMAGE}"
@@ -1,4 +1,6 @@
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { ECDH } from "node:crypto";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
@@ -11,10 +13,243 @@ const rootDir = path.resolve(__dirname, "..");
const smokeScripts = [
"scripts/docker-web-runtime-smoke.sh",
"scripts/docker-api-runtime-smoke.sh",
"scripts/docker-mcp-runtime-smoke.sh",
"scripts/docker-worker-runtime-smoke.sh",
"scripts/docker-hocuspocus-runtime-smoke.sh",
];
const allSmokeScripts = [...smokeScripts, "scripts/docker-portal-domain-controller-runtime-smoke.sh"];
describe("Docker runtime smoke contract", () => {
it.each([
["Dockerfile", "hivegrid-pnpm-store-v2", 3],
["apps/hocuspocus/Dockerfile", "hivegrid-hocuspocus-pnpm-store", 3],
])("locks each writable pnpm store: %s (%s)", (relativePath, cacheId, expectedMounts) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const storeMounts = source.match(new RegExp(`--mount=type=cache,id=${cacheId},[^\\s\\\\]+`, "g")) ?? [];
assert.equal(storeMounts.length, expectedMounts);
assert.equal(
storeMounts.every((mount) => mount.includes("sharing=locked")),
true
);
});
it("builds all production closures in one locked warm-store bundle", () => {
const source = fs.readFileSync(path.join(rootDir, "Dockerfile"), "utf8");
const normalized = source.replace(/\\\r?\n\s*/gu, " ");
const bundleBody = normalized.match(/^FROM build AS production-deps-bundle\s*$([\s\S]*?)(?=^FROM\s)/mu)?.[1] ?? "";
const bundleInstructions = bundleBody
.split("\n")
.map((line) => line.replace(/\s+/gu, " ").trim())
.filter((line) => line.length > 0 && !line.startsWith("#"));
assert.deepEqual(bundleInstructions, [
"RUN --mount=type=cache,id=hivegrid-pnpm-store-v2,target=/pnpm/store,sharing=locked bash scripts/ci/deploy-production-closures.sh",
]);
assert.doesNotMatch(source, /hivegrid-pnpm-store-v5-production|PNPM_STORE_CACHE_SCOPE|sharing=shared(?:,ro)?/u);
assert.equal((source.match(/FROM production-deps-bundle AS [a-z-]+-production-deps/gu) ?? []).length, 5);
assert.equal((source.match(/pnpm --offline[^\n]* deploy /gu) ?? []).length, 0);
});
it("deploys every production closure concurrently and collects every result in each wave", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/ci/deploy-production-closures.sh"), "utf8");
const normalized = source.replace(/\\\r?\n\s*/gu, " ").replace(/\s+/gu, " ");
const runWave = source.match(/^run_wave\(\)\s*\{\s*\n([\s\S]*?)^\}/mu)?.[1] ?? "";
for (const target of ["web", "api", "mcp", "worker", "portal-domain-controller"]) {
assert.match(source, new RegExp(`--filter @hivegrid/runtime-${target} deploy`, "u"));
}
assert.equal((source.match(/pnpm --offline/gu) ?? []).length, 5);
assert.match(runWave, /local -a pids=\(\)/u);
assert.match(runWave, /"\$task" &/u);
assert.match(runWave, /pids\+=\("\$!"\)/u);
assert.match(runWave, /for index in "\$\{!pids\[@\]\}"; do/u);
assert.match(runWave, /if wait "\$\{pids\[\$index\]\}"; then/u);
assert.match(runWave, /if \[\[ "\$status" -eq 0 \]\]; then\s+status="\$child_status"/u);
assert.match(runWave, /return "\$status"/u);
assert.equal((normalized.match(/\brun_wave (?:offline-first|after-fetch)\b/gu) ?? []).length, 2);
});
it("refreshes a missed warm store once, retries one complete wave, and fails closed", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/ci/deploy-production-closures.sh"), "utf8");
const normalized = source
.replace(/\\\r?\n\s*/gu, " ")
.replace(/\s+/gu, " ")
.trim();
const initialWaveIndex = normalized.indexOf("run_wave offline-first || initial_status=$?");
const cleanupIndex = normalized.indexOf('for target in "${targets[@]}"; do rm -rf -- "/prod/${target}" done');
const fetchIndex = normalized.indexOf("if pnpm fetch --frozen-lockfile; then");
const retryIndex = normalized.indexOf("run_wave after-fetch || retry_status=$?");
assert.match(source, /^tasks=\(deploy_web deploy_api deploy_mcp deploy_portal_controller deploy_worker\)$/mu);
assert.match(source, /^targets=\(web api mcp portal-domain-controller worker\)$/mu);
assert.equal((source.match(/\brm -rf\b/gu) ?? []).length, 1);
assert.equal((source.match(/\bpnpm fetch --frozen-lockfile\b/gu) ?? []).length, 1);
assert.ok(initialWaveIndex >= 0 && cleanupIndex > initialWaveIndex && fetchIndex > cleanupIndex && retryIndex > fetchIndex);
assert.match(
normalized,
/if \[\[ "\$initial_status" -eq 0 \]\]; then .* exit 0 fi .* if pnpm fetch --frozen-lockfile; then .* else fetch_status=\$\? .* exit "\$fetch_status" fi/u
);
assert.match(
normalized,
/retry_status=0 run_wave after-fetch \|\| retry_status=\$\? if \[\[ "\$retry_status" -ne 0 \]\]; then .* exit "\$retry_status" fi/u
);
assert.doesNotMatch(source, /sentinel|sha256sum|lockfile[_-]?hash/iu);
assert.doesNotMatch(source, /\brm\s+-rf\s+(?:--\s+)?["']?\/prod["']?(?:\s|;|$)/u);
assert.doesNotMatch(source, /\brm\s+-rf\s+(?:--\s+)?["']?\/prod\/\*/u);
assert.doesNotMatch(source, /\|\|\s*(?:true|:|exit\s+0)\b/u);
});
it("rehydrates the hocuspocus production store in the deploy layer", () => {
const source = fs.readFileSync(path.join(rootDir, "apps/hocuspocus/Dockerfile"), "utf8");
const normalized = source.replace(/\\\r?\n\s*/gu, " ");
const deploys = normalized
.split("\n")
.filter(
(line) =>
line.includes("RUN --mount=type=cache,id=hivegrid-hocuspocus-pnpm-store,target=/pnpm/store,sharing=locked") &&
line.includes("pnpm fetch --frozen-lockfile") &&
line.includes("&& pnpm --offline") &&
line.includes(" deploy ")
);
assert.equal(deploys.length, 1);
});
it.each(allSmokeScripts)("isolates Docker resources by run and installs bounded cleanup traps: %s", (relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const cleanupBlock = source.match(/cleanup\(\) \{([\s\S]*?)\n\}/u)?.[1] ?? "";
assert.match(source, /source "\$\(dirname "\$\{BASH_SOURCE\[0\]\}"\)\/lib\/docker-runtime-smoke\.sh"/);
assert.match(source, /DOCKER_SMOKE_RUN_ID="\$\{DOCKER_SMOKE_RUN_ID:-\$\$\}"/);
assert.match(source, /\^\[A-Za-z0-9_\.\-\]\+\$/);
assert.match(source, /docker_smoke_install_cleanup_traps cleanup/);
assert.match(cleanupBlock, /docker_smoke_cleanup_(?:container|network|volume)/);
assert.doesNotMatch(cleanupBlock, /\bdocker\s+(?:rm|network\s+rm|volume\s+rm)\b/);
assert.doesNotMatch(source, /trap cleanup EXIT/);
assert.ok((cleanupBlock.match(/docker_smoke_cleanup_(?:container|network|volume)/gu) ?? []).length <= 3);
execFileSync("bash", ["-n", path.join(rootDir, relativePath)]);
});
it.each(allSmokeScripts)("names every Docker one-shot with the run-scoped cleanup contract: %s", (relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const oneShots = source.split("\n").filter((line) => line.includes("docker run --rm"));
assert.ok(oneShots.length > 0);
assert.equal(
oneShots.every((line) => line.includes("--name")),
true
);
});
it("bounds Postgres readiness by an absolute shared deadline", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/lib/docker-runtime-smoke.sh"), "utf8");
const helper = source.match(/docker_smoke_wait_for_postgres\(\) \{([\s\S]*?)\n\}/u)?.[1] ?? "";
assert.match(helper, /deadline_seconds=\$\(\(SECONDS \+ DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS\)\)/u);
assert.match(helper, /while \[\[ "\$SECONDS" -lt "\$deadline_seconds" \]\]; do/u);
assert.match(helper, /docker_smoke_probe "\$stage" docker exec "\$container_name"/u);
assert.match(helper, /pg_isready -h 127\.0\.0\.1 -U "\$database_user" -d "\$database_name"/u);
assert.doesNotMatch(helper, /seq|attempt/u);
});
it.each(smokeScripts)("uses the shared bounded Postgres readiness helper: %s", (relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const readinessBlock = source.match(/if ! docker_smoke_wait_for_postgres ([\s\S]*?)\nfi/u)?.[1] ?? "";
assert.match(readinessBlock, /"\$DB_CONTAINER_NAME" "\$DB_USER" "\$DB_NAME"/u);
assert.match(readinessBlock, /DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS/u);
assert.match(readinessBlock, /docker_smoke_logs|emit_runtime_logs/u);
assert.match(readinessBlock, /exit 1/u);
assert.doesNotMatch(source, /for attempt in \$\(seq 1 "\$DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS"\)/u);
});
it.each([
["scripts/docker-web-runtime-smoke.sh", "web:migrate:initial"],
["scripts/docker-api-runtime-smoke.sh", "api:migrate"],
["scripts/docker-mcp-runtime-smoke.sh", "mcp:migrate"],
["scripts/docker-worker-runtime-smoke.sh", "worker:migrate"],
["scripts/docker-hocuspocus-runtime-smoke.sh", "hocuspocus:migrate"],
])("streams migration failures through a named timeout stage: %s", (relativePath, stage) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
if (relativePath.endsWith("docker-web-runtime-smoke.sh")) {
assert.match(source, new RegExp(`run_migrator MIGRATOR_LOGS "${stage}"`));
assert.match(source, /docker_smoke_capture "\$output_variable" "\$stage" "\$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS"/);
} else {
assert.match(source, new RegExp(`docker_smoke_run "${stage}" "\\$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS"`));
}
assert.doesNotMatch(source, /migrate\s*>\/dev\/null/);
});
it.each([
["scripts/docker-web-runtime-smoke.sh", "web:provision-rls-roles"],
["scripts/docker-api-runtime-smoke.sh", "api:provision-rls-roles"],
["scripts/docker-mcp-runtime-smoke.sh", "mcp:provision-rls-roles"],
["scripts/docker-worker-runtime-smoke.sh", "worker:provision-rls-roles"],
["scripts/docker-hocuspocus-runtime-smoke.sh", "hocuspocus:provision-rls-roles"],
])("runs RLS role provisioning through a named command timeout: %s", (relativePath, stage) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const roleFixture = fs.readFileSync(path.join(rootDir, "scripts/lib/docker-rls-role-fixture.sh"), "utf8");
assert.match(source, new RegExp(`provision_docker_smoke_rls_roles \\\\\\n "${stage}"`));
assert.match(roleFixture, /docker_smoke_run "\$stage" "\$DOCKER_SMOKE_ROLE_PROVISION_TIMEOUT_SECONDS"/);
});
it.each([
["scripts/docker-worker-runtime-smoke.sh", "worker:reject-spoofed-revision"],
["scripts/docker-worker-runtime-smoke.sh", "worker:reject-wrong-group"],
["scripts/docker-worker-runtime-smoke.sh", "worker:reject-disabled"],
["scripts/docker-mcp-runtime-smoke.sh", "mcp:reject-spoofed-revision"],
["scripts/docker-mcp-runtime-smoke.sh", "mcp:reject-redis-outage"],
["scripts/docker-mcp-runtime-smoke.sh", "mcp:reject-db-outage"],
["scripts/docker-portal-domain-controller-runtime-smoke.sh", "portal-controller:reject-foreign-revision"],
])("distinguishes an expected product rejection from infrastructure failure: %s", (relativePath, stage) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
assert.match(source, new RegExp(`docker_smoke_expect_docker_exec_rejection "${stage}" "\\$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "\\$CONTAINER_NAME"`));
assert.doesNotMatch(source, new RegExp(`docker_smoke_probe "${stage}"`));
});
it("fails closed when portal-controller environment inspection cannot run", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-portal-domain-controller-runtime-smoke.sh"), "utf8");
assert.match(source, /docker_smoke_capture RUNTIME_ENV_KEYS "portal-controller:inspect-runtime-env"/);
assert.ok(source.includes("| sed '\\''s/=.*//'\\'''"));
assert.match(source, /grep -qx "\$forbidden" <<<"\$RUNTIME_ENV_KEYS"/);
assert.doesNotMatch(source, /docker_smoke_run "portal-controller:inspect-runtime-env"[\s\S]{0,180}\| grep/);
});
it("diagnoses portal-controller status mismatches with expected values and bounded logs", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-portal-domain-controller-runtime-smoke.sh"), "utf8");
assert.match(source, /expect_status\(\)/);
assert.match(source, /returned \$\{actual:-<empty>\}, expected \$\{expected\}/);
assert.match(source, /docker_smoke_logs "portal-controller:logs-status"/);
assert.match(source, /expect_status \/healthz 200/);
assert.match(source, /expect_status \/readyz 200/);
assert.match(source, /expect_status \/metrics 401/);
assert.match(source, /expect_status \/metrics 200 "\$METRICS_TOKEN"/);
assert.doesNotMatch(source, /^\[\[ "\$\(http_status \/(?:healthz|readyz|metrics)[^\n]*\]\]$/mu);
});
it("does not reuse a global worker temp file and derives one-shot names from the run ID", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-worker-runtime-smoke.sh"), "utf8");
assert.doesNotMatch(source, /\/tmp\/hivegrid-worker-runtime-smoke/);
assert.match(source, /DISABLED_HEALTH_CONTAINER_NAME=.*\$\{DOCKER_SMOKE_RUN_ID\}/);
assert.match(source, /ENABLED_HEALTH_CONTAINER_NAME=.*\$\{DOCKER_SMOKE_RUN_ID\}/);
assert.match(source, /MAIL_HEALTH_CONTAINER_NAME=.*\$\{DOCKER_SMOKE_RUN_ID\}/);
});
it("derives the portal-controller revision from the exact image instead of a fake SHA", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-portal-domain-controller-runtime-smoke.sh"), "utf8");
assert.doesNotMatch(source, /0123456789abcdef0123456789abcdef01234567/);
assert.match(source, /org\.opencontainers\.image\.revision/);
assert.match(source, /EXPECTED_REVISION="\$IMAGE_REVISION"/);
});
it.each(smokeScripts)("reads the expected revision from the built image label: %s", (relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
@@ -29,14 +264,28 @@ describe("Docker runtime smoke contract", () => {
assert.match(source, /does not expose a concrete org\.opencontainers\.image\.revision/);
});
it.each(smokeScripts)("does not override APP_REVISION at container runtime: %s", (relativePath) => {
it.each(smokeScripts)("does not override APP_REVISION when launching the runtime: %s", (relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const sourceWithoutNegativeSpoofChecks = source
.split("\n")
.filter((line) => !line.includes('docker exec -e APP_REVISION="$MISMATCHED_REVISION"'))
.join("\n");
assert.doesNotMatch(source, /-e APP_REVISION=/);
assert.doesNotMatch(sourceWithoutNegativeSpoofChecks, /-e APP_REVISION=/);
});
it.each(["scripts/docker-web-runtime-smoke.sh", "scripts/docker-api-runtime-smoke.sh"])("validates the runtime OpenAPI JSON contract: %s", (relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
it.each(["scripts/docker-mcp-runtime-smoke.sh", "scripts/docker-worker-runtime-smoke.sh"])(
"proves that runtime APP_REVISION spoofing fails closed: %s",
(relativePath) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
assert.match(source, /env APP_REVISION="\$MISMATCHED_REVISION"/);
assert.match(source, /docker_smoke_expect_docker_exec_rejection "(?:mcp|worker):reject-spoofed-revision"/);
}
);
it("validates the API runtime OpenAPI JSON contract", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-api-runtime-smoke.sh"), "utf8");
assert.match(source, /expect_openapi_json/);
assert.match(source, /\/v1\/openapi\.json/);
@@ -44,53 +293,362 @@ describe("Docker runtime smoke contract", () => {
assert.doesNotMatch(source, /payload\.paths\["\/v1\/workflows\/run\/\{id\}"\]/);
});
it("boots the web image through the entrypoint migration path (MIGRATE_ON_BOOT/SEED_ON_BOOT)", () => {
it("keeps the separately deployed API surface out of the web runtime", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /-e MIGRATE_ON_BOOT=true/);
assert.match(source, /-e SEED_ON_BOOT=true/);
assert.match(source, /MIGRATE_ON_BOOT migration banner/);
assert.match(source, /SEED_ON_BOOT seed banner/);
// Migrations must not run in a separate one-off container anymore — the
// smoke rehearses the exact Coolify boot contract of the web resource.
assert.doesNotMatch(source, /--entrypoint \/bin\/sh/);
assert.doesNotMatch(source, /DATABASE_URL="\$HOST_DATABASE_URL" pnpm exec prisma migrate deploy/);
assert.doesNotMatch(source, /expect_openapi_json/);
assert.match(source, /expect_status api\.localhost \/v1\/docs 404/);
assert.match(source, /expect_status api\.localhost \/v1\/openapi\.json 404/);
assert.match(source, /expect_status api\.localhost \/v1\/health 404/);
});
it("runs the API smoke migration inside the final API image network", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-api-runtime-smoke.sh"), "utf8");
it("requires the built web runtime to expose a fetch-capable service-worker CSP", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /docker run --rm --network "\$NETWORK_NAME"/);
assert.match(source, /-e DATABASE_URL="\$CONTAINER_DATABASE_URL"/);
assert.match(source, /--entrypoint \/bin\/sh/);
assert.match(source, /pnpm exec prisma migrate deploy --config prisma\.config\.ts/);
assert.doesNotMatch(source, /HOST_DATABASE_URL/);
assert.doesNotMatch(source, /DATABASE_URL="\$HOST_DATABASE_URL" pnpm exec prisma migrate deploy/);
assert.match(source, /expect_status app\.localhost \/sw\.js 200/);
assert.match(source, /expect_service_worker_csp app\.localhost/);
assert.match(source, /connect-src 'self'/);
assert.match(source, /connect-src 'none'/);
});
it("runs the worker smoke migration inside the final worker image network", () => {
it("requires the built login document to recover already-controlled tabs before stylesheet discovery", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /expect_service_worker_recovery_bootstrap app\.localhost/);
assert.match(source, /service-worker-csp-recovery:v3/);
assert.match(source, /stylesheetIndex <= markerIndex/);
assert.match(source, /nonce=/);
});
it("boots the web runtime with a valid public VAPID fixture", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
const publicKey = source.match(/SMOKE_WEB_PUSH_VAPID_PUBLIC_KEY='([^']+)'/)?.[1];
assert.ok(publicKey);
assert.doesNotThrow(() => ECDH.convertKey(publicKey, "prime256v1", "base64url", "hex", "uncompressed"));
assert.match(source, /-e WEB_PUSH_VAPID_PUBLIC_KEY="\$SMOKE_WEB_PUSH_VAPID_PUBLIC_KEY"/);
});
it("boots all three web surfaces with the same encrypted GDPR export storage fixture", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
const coreLaunch = source.indexOf('docker run -d --name "$CONTAINER_NAME"');
const adminLaunch = source.indexOf('docker run -d --name "$ADMIN_CONTAINER_NAME"');
const portalLaunch = source.indexOf('docker run -d --name "$PORTAL_CONTAINER_NAME"');
const coreRuntime = source.slice(coreLaunch, adminLaunch);
const adminRuntime = source.slice(adminLaunch, portalLaunch);
const portalRuntime = source.slice(portalLaunch);
const fixtureKey = source.match(/SMOKE_GDPR_EXPORT_SSE_C_KEY_BASE64='([^']+)'/)?.[1];
const requiredStorageEnv = [
"STORAGE_ENDPOINT='https://storage.example.test'",
"STORAGE_REGION='eu-central-1'",
"STORAGE_BUCKET='docker-smoke-private-exports'",
"STORAGE_ACCESS_KEY_ID='docker-smoke-storage-access-key'",
"STORAGE_SECRET_ACCESS_KEY='docker-smoke-storage-secret-key'",
"STORAGE_SESSION_TOKEN='docker-smoke-storage-session-token'",
"STORAGE_FORCE_PATH_STYLE=false",
'GDPR_EXPORT_SSE_C_KEY_BASE64="$SMOKE_GDPR_EXPORT_SSE_C_KEY_BASE64"',
];
assert.ok(coreLaunch >= 0 && adminLaunch > coreLaunch && portalLaunch > adminLaunch);
assert.ok(fixtureKey);
assert.equal(Buffer.from(fixtureKey, "base64").byteLength, 32);
for (const env of requiredStorageEnv) {
assert.equal(coreRuntime.includes(`-e ${env}`), true);
assert.equal(adminRuntime.includes(`-e ${env}`), true);
assert.equal(portalRuntime.includes(`-e ${env}`), true);
}
});
it("proves password login and server-session persistence in the exact web image under required RLS", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /SMOKE_LOGIN_EMAIL="[^"]+@mitarbeiter\.example\.test"/);
assert.match(source, /docker run --rm --name "\$PASSWORD_HASH_CONTAINER_NAME" --entrypoint node "\$IMAGE" -e/);
assert.match(source, /import\("argon2"\)/);
assert.match(source, /type: argon2\.argon2id/);
assert.match(source, /INSERT INTO "User"/);
assert.match(source, /INSERT INTO "TenantUser"/);
assert.match(source, /"active"\)\s*\nVALUES \([^\n]+true\);/);
assert.match(source, /-e DATABASE_RUNTIME_ROLE=hivegrid_app/);
assert.match(source, /-e WEB_RUNTIME_SURFACE=core/);
assert.match(source, /-e PORTAL_APP_HOST=portal\.localhost/);
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
assert.match(source, /-e SENTRY_ENVIRONMENT=staging/);
assert.match(source, /-e STAGING_DEMO_LOGIN_ENABLED=true/);
assert.match(source, /expect_password_login_session/);
assert.match(source, /name=\["\\x27\]csrf-token/);
assert.match(source, /loginPage\.headers\["set-cookie"\]/);
assert.match(source, /Cookie: cookieHeader/);
assert.match(source, /Origin: "http:\/\/app\.localhost"/);
assert.match(source, /Referer: "http:\/\/app\.localhost\/login"/);
assert.match(source, /__Host-hivegrid_app_session=/);
assert.match(source, /FROM "UserSession"/);
assert.match(source, /"revokedAt" IS NULL/);
assert.match(source, /"expiresAt" > now\(\)/);
assert.match(source, /active_session_count" != "1"/);
assert.doesNotMatch(source, /(?:echo|printf)[^\n]*SMOKE_LOGIN_PASSWORD(?:_HASH)?/);
});
it("runs migration in a DIRECT_URL-only one-shot web container before the app runtime", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /provision_docker_smoke_rls_roles/);
assert.match(source, /-e DIRECT_URL="\$MIGRATOR_DATABASE_URL"/);
assert.match(source, /"\$IMAGE" migrate/);
assert.match(source, /One-shot migrator logs are missing the migration banner/);
assert.match(source, /permission-catalog-sync-complete/);
assert.match(source, /run_migrator SECOND_MIGRATOR_LOGS "web:migrate:idempotency"/);
assert.match(source, /run_migrator THIRD_MIGRATOR_LOGS "web:migrate:drift-repair"/);
assert.match(source, /docker_smoke_capture "\$output_variable" "\$stage" "\$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS"/);
assert.match(source, /--name "\$MIGRATION_CONTAINER_NAME"/);
assert.match(source, /docker_smoke_run "web:db-push" "\$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS"/);
assert.match(source, /--name "\$DB_PUSH_CONTAINER_NAME"/);
assert.doesNotMatch(source, /db push[\s\S]{0,160}>\/dev\/null/);
assert.match(source, /seed_permission_catalog_sentinel/);
assert.match(source, /inject_permission_catalog_drift/);
assert.match(source, /Idempotent permission catalog sync changed canonical catalog state/);
assert.match(source, /Permission catalog drift repair mutated a tenant-owned template role/);
assert.match(source, /Permission catalog drift repair did not restore canonical values and grants/);
assert.match(source, /relation\.relforcerowsecurity AS force_rls/);
assert.match(source, /NOT has_table_dml AND NOT has_column_dml/);
assert.match(source, /-e DATABASE_URL="\$APP_DATABASE_URL"/);
assert.match(source, /-e DATABASE_RUNTIME_ROLE=hivegrid_app/);
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
assert.doesNotMatch(source, /-e MIGRATE_ON_BOOT=/);
assert.doesNotMatch(source, /-e SEED_ON_BOOT=/);
assert.doesNotMatch(source, /RLS_RUNTIME_MODE=off/);
});
it("boots the exact web image as the isolated portal surface against the disposable migrated database", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
const roleFixture = fs.readFileSync(path.join(rootDir, "scripts/lib/docker-rls-role-fixture.sh"), "utf8");
const migration = source.indexOf('"$IMAGE" migrate');
const coreReadiness = source.indexOf("expect_status app.localhost /readyz 200");
const legacyRecut = source.indexOf('apply_image_sql_artifact "/myapp/prisma/rls/portal-legacy-commerce-recut-pre-db-push.sql"');
const schemaSync = source.indexOf("/myapp/node_modules/prisma/build/index.js db push");
const tenantPolicies = source.indexOf('apply_image_sql_artifact "/myapp/prisma/rls/tenant-policy-contract-isolation.sql"');
const portalPolicies = source.indexOf('apply_image_sql_artifact "/myapp/prisma/rls/portal-policy-contract-isolation.sql"');
const domainCapabilities = source.indexOf('apply_image_sql_artifact "/myapp/prisma/rls/portal-domain-capabilities.sql"');
const portalLaunch = source.indexOf('docker run -d --name "$PORTAL_CONTAINER_NAME"');
const portalAssertions = source.slice(portalLaunch);
assert.ok(migration >= 0);
assert.ok(legacyRecut > migration);
assert.ok(schemaSync > legacyRecut);
assert.ok(tenantPolicies > schemaSync);
assert.ok(portalPolicies > tenantPolicies);
assert.ok(domainCapabilities > portalPolicies);
assert.ok(coreReadiness > domainCapabilities);
assert.ok(portalLaunch > coreReadiness);
assert.match(roleFixture, /DOCKER_SMOKE_PORTAL_DB_PASSWORD="\$\{DOCKER_SMOKE_PORTAL_DB_PASSWORD:-portal_smoke_[^}]+\}"/);
assert.match(roleFixture, /local portal_password="\$DOCKER_SMOKE_PORTAL_DB_PASSWORD"/);
assert.match(source, /PORTAL_DATABASE_URL="postgresql:\/\/hivegrid_portal:\$\{DOCKER_SMOKE_PORTAL_DB_PASSWORD\}@db:5432/);
assert.match(portalAssertions, /-e PORTAL_APP_HOST=portal\.localhost/);
assert.match(portalAssertions, /-e WEB_RUNTIME_SURFACE=portal/);
assert.match(portalAssertions, /-e DATABASE_URL="\$PORTAL_DATABASE_URL"/);
assert.match(portalAssertions, /-e DATABASE_RUNTIME_ROLE=hivegrid_portal/);
assert.match(portalAssertions, /-e RLS_RUNTIME_MODE=required/);
assert.match(portalAssertions, /-e PORTAL_SESSION_SECRET=/);
assert.match(portalAssertions, /-e CAPTCHA_PROVIDER=mcaptcha/);
assert.match(portalAssertions, /-e MCAPTCHA_INSTANCE_URL=/);
assert.match(portalAssertions, /-e MCAPTCHA_SITEKEY_LOGIN=/);
assert.match(portalAssertions, /-e MCAPTCHA_ACCOUNT_SECRET=/);
assert.match(portalAssertions, /-e REDIS_URL='redis:\/\/redis:6379\/0'/);
assert.match(portalAssertions, /-e BULLMQ_REDIS_URL='redis:\/\/redis:6379\/0'/);
assert.doesNotMatch(portalAssertions, /-e SESSION_SECRET=/);
assert.doesNotMatch(portalAssertions, /-e DIRECT_URL=/);
assert.match(portalAssertions, /expect_status portal\.localhost \/healthz 200/);
assert.match(portalAssertions, /expect_runtime_payload portal\.localhost \/healthz ok hivegrid-portal portal/);
assert.match(portalAssertions, /expect_status portal\.localhost \/readyz 200/);
assert.match(portalAssertions, /expect_runtime_payload portal\.localhost \/readyz ready hivegrid-portal portal/);
});
it("boots the exact web image as a fail-closed admin-only surface", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
const adminLaunch = source.indexOf('docker run -d --name "$ADMIN_CONTAINER_NAME"');
const portalLaunch = source.indexOf('docker run -d --name "$PORTAL_CONTAINER_NAME"');
const coreAssertions = source.slice(0, adminLaunch);
const adminAssertions = source.slice(adminLaunch, portalLaunch);
assert.ok(adminLaunch >= 0 && portalLaunch > adminLaunch);
assert.match(coreAssertions, /expect_status admin\.localhost \/settings 404/);
assert.match(adminAssertions, /-e WEB_RUNTIME_SURFACE=admin/);
assert.match(adminAssertions, /-e DATABASE_URL="\$APP_DATABASE_URL"/);
assert.match(adminAssertions, /-e DATABASE_RUNTIME_ROLE=hivegrid_app/);
assert.match(adminAssertions, /-e RLS_RUNTIME_MODE=required/);
assert.match(adminAssertions, /-e SESSION_SECRET='deploy-smoke-admin-session-secret-minimum-32'/);
assert.match(adminAssertions, /-e ADMIN_FALLBACK_LOGIN_ENABLED=false/);
assert.match(adminAssertions, /-e AUTHENTIK_ISSUER_URL=/);
assert.match(adminAssertions, /-e AUTHENTIK_ADMIN_CLIENT_ID=/);
assert.match(adminAssertions, /-e AUTHENTIK_ADMIN_CLIENT_SECRET=/);
assert.match(adminAssertions, /-e AUTHENTIK_ADMIN_REDIRECT_URI='https:\/\/admin\.localhost\/auth\/admin\/callback'/);
assert.match(adminAssertions, /-e AUTHENTIK_ADMIN_JIT_DATABASE_URL="postgresql:\/\/hivegrid_authentik_jit:/);
assert.doesNotMatch(adminAssertions, /-e PORTAL_SESSION_SECRET=/);
assert.doesNotMatch(adminAssertions, /-e DIRECT_URL=/);
assert.match(adminAssertions, /expect_runtime_payload admin\.localhost \/healthz ok hivegrid-admin admin/);
assert.match(adminAssertions, /expect_runtime_payload admin\.localhost \/readyz ready hivegrid-admin admin/);
assert.match(adminAssertions, /expect_status app\.localhost \/healthz 404/);
assert.match(adminAssertions, /expect_status portal\.localhost \/healthz 404/);
assert.match(adminAssertions, /expect_status admin\.localhost \/settings 302/);
});
it("requires the web smoke to observe Docker health as well as HTTP health", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /\.State\.Health/);
assert.match(source, /CONTAINER_HEALTH/);
assert.match(source, /"\$HTTP_STATUS" == "200" && "\$CONTAINER_HEALTH" == "healthy"/);
assert.match(source, /Docker HEALTHCHECK became unhealthy with HTTP status/);
});
it("boots the web runtime with its required production Redis dependency", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-web-runtime-smoke.sh"), "utf8");
assert.match(source, /--network-alias redis redis:7-alpine/);
assert.match(source, /redis-cli ping/);
assert.match(source, /-e REDIS_URL='redis:\/\/redis:6379\/0'/);
assert.match(source, /-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32'/);
assert.match(source, /-e ADMIN_CONNECTION_MASTER_KEY='deploy-smoke-admin-connection-key-minimum-32'/);
assert.match(source, /\\\[DEP0169\\\]/);
assert.match(source, /deprecated url\.parse\(\) runtime path/);
});
it("rejects deprecated Redis URL parsing in the worker runtime", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-worker-runtime-smoke.sh"), "utf8");
assert.match(source, /docker run --rm --network "\$NETWORK_NAME"/);
assert.match(source, /-e DATABASE_URL="\$CONTAINER_DATABASE_URL"/);
assert.match(source, /--entrypoint \/bin\/sh/);
assert.match(source, /pnpm exec prisma migrate deploy --config prisma\.config\.ts/);
assert.doesNotMatch(source, /HOST_DATABASE_URL/);
assert.doesNotMatch(source, /DATABASE_URL="\$HOST_DATABASE_URL" pnpm exec prisma migrate deploy/);
assert.match(source, /-e AUDIT_CHAIN_SECRET=deploy-smoke-audit-chain-secret-minimum-32/);
assert.match(source, /-e ADMIN_CONNECTION_MASTER_KEY=deploy-smoke-admin-connection-key-minimum-32/);
assert.match(source, /WORKER_LOGS="\$\(docker_smoke_logs "worker:logs-deprecation"/);
assert.match(source, /\\\[DEP0169\\\]/);
assert.match(source, /deprecated url\.parse\(\) runtime path/);
});
it("migrates the API smoke database with the matching web image and keeps the migrator out of the API image", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-api-runtime-smoke.sh"), "utf8");
assert.match(source, /MIGRATOR_IMAGE="\$\{DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke\}"/);
assert.match(source, /migrator_revision" != "\$SMOKE_REVISION/);
assert.match(source, /provision_docker_smoke_rls_roles/);
assert.match(source, /-e DIRECT_URL="\$MIGRATOR_DATABASE_URL"/);
assert.match(source, /"\$MIGRATOR_IMAGE" migrate/);
assert.match(source, /-e DATABASE_URL="\$APP_DATABASE_URL"/);
assert.match(source, /-e DATABASE_RUNTIME_ROLE=hivegrid_app/);
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
assert.match(source, /require\.resolve\("prisma"\)/);
assert.doesNotMatch(source, /\bpnpm\s+(?:exec|run|install)\b/);
assert.doesNotMatch(source, /127\.0\.0\.1::5432/);
});
it("boots the API smoke with the required production Redis dependency", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-api-runtime-smoke.sh"), "utf8");
assert.match(source, /--network-alias redis redis:7-alpine/);
assert.match(source, /redis-cli ping/);
assert.match(source, /-e REDIS_URL='redis:\/\/redis:6379\/0'/);
assert.match(source, /-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32'/);
assert.match(source, /-e ADMIN_CONNECTION_MASTER_KEY='deploy-smoke-admin-connection-key-minimum-32'/);
});
it("fails the API health poll immediately with container exit diagnostics", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-api-runtime-smoke.sh"), "utf8");
assert.match(source, /DOCKER_API_SMOKE_HEALTH_ATTEMPTS:-120/);
assert.match(source, /assert_api_container_running/);
assert.match(source, /docker inspect -f '\{\{\.State\.Running\}\}'/);
assert.match(source, /exit=\{\{\.State\.ExitCode\}\} oom=\{\{\.State\.OOMKilled\}\}/);
assert.match(source, /docker_smoke_logs "api:logs-exit" "\$CONTAINER_NAME"/);
assert.match(source, /\n'\n}\n\nassert_api_container_running\(\)/);
assert.match(source, /for attempt in \$\(seq 1 "\$HEALTH_ATTEMPTS"\); do\n assert_api_container_running/);
});
it("migrates the worker smoke database with the matching web image and keeps build toolchains out of the worker image", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-worker-runtime-smoke.sh"), "utf8");
assert.match(source, /MIGRATOR_IMAGE="\$\{DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke\}"/);
assert.match(source, /migrator_revision" != "\$SMOKE_REVISION/);
assert.match(source, /provision_docker_smoke_rls_roles/);
assert.match(source, /-e DIRECT_URL="\$MIGRATOR_DATABASE_URL"/);
assert.match(source, /"\$MIGRATOR_IMAGE" migrate/);
assert.match(source, /-e DATABASE_URL="\$WORKER_DATABASE_URL"/);
assert.match(source, /-e DATABASE_RUNTIME_ROLE=hivegrid_worker/);
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
assert.match(source, /\^prisma@/);
assert.match(source, /\^typescript@/);
assert.match(source, /\^@prisma\\\+engines@/);
assert.doesNotMatch(source, /\bpnpm\s+(?:exec|run|install)\b/);
assert.doesNotMatch(source, /127\.0\.0\.1::5432/);
});
it("proves worker queue-group routing for general and mail workers", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-worker-runtime-smoke.sh"), "utf8");
const mailHealthBlock = source.match(/mail_health_output=""[\s\S]*?expect_worker_health "\$mail_health_output"[^\n]*/)?.[0];
const mailCryptoFixture = /-e CRYPTO_SECRET=deploy-smoke-shared-tenant-envelope-secret-minimum-32/;
assert.match(source, /-e WORKER_QUEUE_GROUP=general/);
assert.match(source, /-e WORKER_QUEUE_GROUP=mail/);
assert.ok(mailHealthBlock, "worker smoke must keep a dedicated mail-health block");
assert.match(mailHealthBlock, mailCryptoFixture);
assert.equal(source.match(new RegExp(mailCryptoFixture.source, "g"))?.length, 1, "CRYPTO_SECRET smoke fixture must remain mail-only");
assert.match(source, /expect_worker_health "\$enabled_health_output" ready true general hivegrid\.notifications/);
assert.match(source, /expect_worker_health "\$mail_health_output" ready true mail hivegrid\.email/);
assert.match(source, /report\.workerGroup !== expectedGroup/);
assert.match(source, /report\.queues\.includes\(expectedQueue\)/);
assert.match(source, /product_acquisition_env=\(/);
assert.match(source, /-e LAGO_API_URL=/);
assert.match(source, /-e LAGO_API_KEY=/);
assert.match(source, /-e LAGO_TIMEOUT_MS=/);
assert.match(source, /-e MOLLIE_API_KEY=/);
assert.match(source, /-e MOLLIE_PROFILE_ID=/);
assert.match(source, /-e MOLLIE_TIMEOUT_MS=/);
assert.match(source, /"\$\{product_acquisition_env\[@\]\}"/);
});
it("boots the MCP image with a token hash secret so the production fail-closed guard is satisfied", () => {
it("boots the general worker with delete-only retention and hard-delete fixtures", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-worker-runtime-smoke.sh"), "utf8");
const hardDeleteBlock = source.match(/general_hard_delete_env=\([\s\S]*?\n\)/)?.[0];
const requiredFixtures = [
"EXPORT_RETENTION_QUEUE_ENABLED=true",
"STORAGE_ENDPOINT=https://storage.example.test",
"STORAGE_REGION=eu-central-1",
"STORAGE_BUCKET=docker-smoke-private-exports",
"STORAGE_ACCESS_KEY_ID=docker-smoke-retention-access-key",
"STORAGE_SECRET_ACCESS_KEY=docker-smoke-retention-secret-key",
"STORAGE_FORCE_PATH_STYLE=false",
"MEILI_URL=http://meili:7700",
"MEILI_API_KEY=docker-smoke-tenant-delete-meili-master-key",
];
assert.ok(hardDeleteBlock, "worker smoke must keep a dedicated general hard-delete fixture");
for (const fixture of requiredFixtures) {
assert.equal(hardDeleteBlock.includes(`-e ${fixture}`), true);
}
assert.doesNotMatch(hardDeleteBlock, /GDPR_EXPORT_SSE_C_KEY_BASE64/);
assert.equal(
source.match(/"\$\{general_hard_delete_env\[@\]\}"/g)?.length,
2,
"hard-delete fixtures must cover both the health probe and the running general worker"
);
assert.match(source, /--network-alias meili/);
assert.match(source, /MEILI_IMAGE="\$\{DOCKER_WORKER_SMOKE_MEILI_IMAGE:-getmeili\/meilisearch:v1\.8\}"/);
assert.match(source, /worker:pull-meili/);
assert.match(source, /docker run -d --pull=never/);
assert.match(source, /worker:probe-meili/);
});
it("checks the running worker revision without starting a second Node runtime", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-worker-runtime-smoke.sh"), "utf8");
const revisionBlock = source.match(
/docker_smoke_run "worker:assert-revision-file"[\s\S]*?' _ "\$SMOKE_REVISION"/
)?.[0];
assert.ok(revisionBlock, "worker smoke must prove the immutable revision file");
assert.match(revisionBlock, /docker exec "\$CONTAINER_NAME" sh -eu -c/);
assert.match(revisionBlock, /stat -c "%u"/);
assert.match(revisionBlock, /0\$mode & 022/);
assert.doesNotMatch(revisionBlock, /\bnode\s+-e\b/);
});
it("boots the MCP image with its required production secrets and Redis dependency", () => {
// The MCP runtime refuses to boot in production without a token hash secret
// (security audit #7). The smoke runs NODE_ENV=production, so it must supply
// one or the container exits before the health check.
@@ -98,5 +656,78 @@ describe("Docker runtime smoke contract", () => {
assert.match(source, /-e NODE_ENV=production/);
assert.match(source, /-e MCP_OAUTH_TOKEN_HASH_SECRET=/);
assert.match(source, /-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32'/);
assert.match(source, /--network-alias redis redis:7-alpine/);
assert.match(source, /redis-cli ping/);
assert.match(source, /-e REDIS_URL='redis:\/\/redis:6379\/0'/);
assert.match(source, /--network-alias db/);
assert.match(source, /pg_isready/);
assert.match(source, /provision_docker_smoke_rls_roles/);
assert.match(source, /-e DIRECT_URL="\$MIGRATOR_DATABASE_URL"/);
assert.match(source, /MIGRATOR_IMAGE="\$\{DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke\}"/);
assert.match(source, /migrator_revision" != "\$SMOKE_REVISION/);
assert.match(source, /"\$MIGRATOR_IMAGE" migrate/);
assert.match(source, /-e DATABASE_URL="\$APP_DATABASE_URL"/);
assert.match(source, /-e DATABASE_RUNTIME_ROLE=hivegrid_app/);
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
assert.match(source, /\["prisma", "typescript", "@prisma\/engines"\]/);
assert.match(source, /MCP runtime retained build-only package/);
assert.match(source, /wait_for_status \/readyz 200 "initial dependency readiness"/);
assert.match(source, /docker stop "\$REDIS_CONTAINER_NAME"/);
assert.match(source, /wait_for_status \/readyz 503 "Redis outage readiness"/);
assert.match(source, /wait_for_status \/readyz 200 "Redis recovery readiness"/);
assert.match(source, /docker stop "\$DB_CONTAINER_NAME"/);
assert.match(source, /wait_for_status \/readyz 503 "Postgres outage readiness"/);
assert.match(source, /expect_status \/healthz 200/);
});
it("boots the Hocuspocus image as non-root and validates its pruned target-specific runtime inventory", () => {
const source = fs.readFileSync(path.join(rootDir, "scripts/docker-hocuspocus-runtime-smoke.sh"), "utf8");
assert.match(source, /docker_smoke_capture IMAGE_USER "hocuspocus:inspect-user"/);
assert.match(source, /process\.getuid\?\.\(\) !== 1000/);
assert.match(source, /Runtime retained package-manager executables/);
assert.match(source, /entry\.name\.endsWith\("\.map"\)/);
assert.match(source, /entry\.name\.endsWith\("\.d\.ts"\)/);
assert.match(source, /sbom\.schema !== "hivegrid\.sbom-pnpm\/v2"/);
assert.match(source, /sbom\.target !== "hocuspocus"/);
assert.match(source, /installed pruned pnpm runtime tree/);
assert.match(source, /packageNames\.has\("@hocuspocus\/server"\)/);
assert.match(source, /query_compiler_fast_bg\.postgresql\.mjs/);
assert.match(source, /query_compiler_fast_bg\.postgresql\.wasm-base64\.mjs/);
assert.match(source, /Runtime retained unexpected Prisma compiler payloads/);
assert.match(source, /Runtime retained the build-only Prisma client generator/);
assert.match(source, /expectedPrismaCompilers\.map\(\(specifier\) => import\(specifier\)\)/);
assert.match(source, /--network-alias db/);
assert.match(source, /pg_isready/);
assert.match(source, /MIGRATOR_IMAGE="\$\{DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke\}"/);
assert.match(source, /migrator_revision" != "\$SMOKE_REVISION/);
assert.match(source, /provision_docker_smoke_rls_roles/);
assert.match(source, /-e DIRECT_URL="\$MIGRATOR_DATABASE_URL"/);
assert.match(source, /"\$MIGRATOR_IMAGE" migrate/);
assert.match(source, /-e DATABASE_URL="\$APP_DATABASE_URL"/);
assert.match(source, /-e DATABASE_RUNTIME_ROLE=hivegrid_app/);
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
assert.match(source, /-e HOCUSPOCUS_AUTH_SECRET=/);
assert.match(source, /require\("node:net"\)\.connect\(1234, "127\.0\.0\.1"\)/);
assert.match(source, /docker_smoke_capture RUNTIME_REVISION "hocuspocus:runtime-revision"/);
});
it.each([
["scripts/docker-web-runtime-smoke.sh", "hivegrid_app"],
["scripts/docker-api-runtime-smoke.sh", "hivegrid_app"],
["scripts/docker-mcp-runtime-smoke.sh", "hivegrid_app"],
["scripts/docker-worker-runtime-smoke.sh", "hivegrid_worker"],
["scripts/docker-hocuspocus-runtime-smoke.sh", "hivegrid_app"],
])("keeps privileged database credentials out of the long-lived runtime: %s", (relativePath, role) => {
const source = fs.readFileSync(path.join(rootDir, relativePath), "utf8");
const runtimeLaunch = source.slice(source.indexOf('docker run -d --name "$CONTAINER_NAME"'));
assert.match(source, new RegExp(`-e DATABASE_RUNTIME_ROLE=${role}`));
assert.match(source, /-e RLS_RUNTIME_MODE=required/);
if (role === "hivegrid_worker") assert.match(runtimeLaunch, /"\$\{worker_env\[@\]\}"/);
assert.doesNotMatch(runtimeLaunch, /-e DIRECT_URL=/);
assert.doesNotMatch(runtimeLaunch, /-e (?:MIGRATE_ON_BOOT|SEED_ON_BOOT|SEED_ONCE)=/);
assert.doesNotMatch(runtimeLaunch, /RLS_RUNTIME_MODE=off/);
});
});
@@ -1,24 +1,63 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-$$}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! $DOCKER_SMOKE_RUN_ID =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
# shellcheck source=scripts/lib/docker-rls-role-fixture.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-rls-role-fixture.sh"
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-runtime-smoke.sh"
IMAGE="${1:-hivegrid-web:smoke}"
PORT="${DOCKER_WEB_SMOKE_PORT:-}"
CONTAINER_NAME="${DOCKER_WEB_SMOKE_CONTAINER:-hivegrid-web-runtime-smoke-$$}"
DB_CONTAINER_NAME="${DOCKER_WEB_SMOKE_DB_CONTAINER:-hivegrid-web-runtime-smoke-db-$$}"
NETWORK_NAME="${DOCKER_WEB_SMOKE_NETWORK:-hivegrid-web-runtime-smoke-$$}"
ADMIN_PORT="${DOCKER_WEB_SMOKE_ADMIN_PORT:-}"
PORTAL_PORT="${DOCKER_WEB_SMOKE_PORTAL_PORT:-}"
CORE_CONTAINER_NAME="${DOCKER_WEB_SMOKE_CONTAINER:-hivegrid-web-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
ADMIN_CONTAINER_NAME="${DOCKER_WEB_SMOKE_ADMIN_CONTAINER:-hivegrid-admin-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
PORTAL_CONTAINER_NAME="${DOCKER_WEB_SMOKE_PORTAL_CONTAINER:-hivegrid-portal-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
CONTAINER_NAME="$CORE_CONTAINER_NAME"
DB_CONTAINER_NAME="${DOCKER_WEB_SMOKE_DB_CONTAINER:-hivegrid-web-runtime-smoke-db-${DOCKER_SMOKE_RUN_ID}}"
REDIS_CONTAINER_NAME="${DOCKER_WEB_SMOKE_REDIS_CONTAINER:-hivegrid-web-runtime-smoke-redis-${DOCKER_SMOKE_RUN_ID}}"
NETWORK_NAME="${DOCKER_WEB_SMOKE_NETWORK:-hivegrid-web-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
SQL_ARTIFACT_CONTAINER_NAME="${DOCKER_WEB_SMOKE_SQL_ARTIFACT_CONTAINER:-hivegrid-web-runtime-smoke-sql-artifact-${DOCKER_SMOKE_RUN_ID}}"
PASSWORD_HASH_CONTAINER_NAME="${DOCKER_WEB_SMOKE_PASSWORD_HASH_CONTAINER:-hivegrid-web-runtime-smoke-password-hash-${DOCKER_SMOKE_RUN_ID}}"
MIGRATION_CONTAINER_NAME="${DOCKER_WEB_SMOKE_MIGRATION_CONTAINER:-hivegrid-web-runtime-smoke-migrate-${DOCKER_SMOKE_RUN_ID}}"
DB_PUSH_CONTAINER_NAME="${DOCKER_WEB_SMOKE_DB_PUSH_CONTAINER:-hivegrid-web-runtime-smoke-db-push-${DOCKER_SMOKE_RUN_ID}}"
TRANSPORT="${DOCKER_WEB_SMOKE_TRANSPORT:-host}"
SMOKE_REVISION="${DOCKER_WEB_SMOKE_REVISION:-}"
# The boot path runs migrate + seed before the server listens, so the health
# window has to cover the full migration chain against an empty database.
HEALTH_ATTEMPTS="${DOCKER_WEB_SMOKE_HEALTH_ATTEMPTS:-600}"
DB_PASSWORD="hivegrid"
DB_NAME="hivegrid"
DB_USER="hivegrid"
APP_DB_PASSWORD="hivegrid-app-smoke"
WORKER_DB_PASSWORD="hivegrid-worker-smoke"
MIGRATOR_DB_PASSWORD="hivegrid-migrator-smoke"
AUTHENTIK_JIT_DB_PASSWORD="hivegrid-authentik-jit-smoke"
SMOKE_LOGIN_TENANT_ID="docker-runtime-login-tenant"
SMOKE_LOGIN_TENANT_SLUG="docker-runtime-login"
SMOKE_LOGIN_USER_ID="docker-runtime-login-user"
SMOKE_LOGIN_EMAIL="docker.runtime.login.01@mitarbeiter.example.test"
SMOKE_LOGIN_PASSWORD='Docker-Runtime-Smoke-Only-2026!'
CATALOG_SENTINEL_TENANT_ID="docker-catalog-sentinel-tenant"
CATALOG_SENTINEL_ROLE_ID="docker-catalog-sentinel-role"
CATALOG_SENTINEL_GRANT_ID="docker-catalog-sentinel-grant"
CATALOG_STALE_GRANT_ID="docker-catalog-stale-global-grant"
SMOKE_WEB_PUSH_VAPID_PUBLIC_KEY='BHzyexiNA09-ilI4AwS1GsPAiWnid_IbNaYLSPxHZpl4B3dVENuO0EApPZrGn3Qw27p9reY86YIpngS3nSJ4c9E'
SMOKE_GDPR_EXPORT_SSE_C_KEY_BASE64='BwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwcHBwc='
cleanup() {
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
docker rm -f "$DB_CONTAINER_NAME" >/dev/null 2>&1 || true
docker network rm "$NETWORK_NAME" >/dev/null 2>&1 || true
docker_smoke_cleanup_container "web:cleanup:containers" \
"$CORE_CONTAINER_NAME" "$ADMIN_CONTAINER_NAME" "$PORTAL_CONTAINER_NAME" "$DB_CONTAINER_NAME" "$REDIS_CONTAINER_NAME" \
"$SQL_ARTIFACT_CONTAINER_NAME" "$PASSWORD_HASH_CONTAINER_NAME" "$MIGRATION_CONTAINER_NAME" "$DB_PUSH_CONTAINER_NAME"
docker_smoke_cleanup_network "web:cleanup:network" "$NETWORK_NAME"
}
emit_runtime_logs() {
local container_name="$1"
docker_smoke_logs "web:runtime-logs" "$container_name" >&2 || true
}
resolve_smoke_revision() {
@@ -27,7 +66,8 @@ resolve_smoke_revision() {
return
fi
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
docker_smoke_probe "web:image-revision" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
}
http_status() {
@@ -36,9 +76,9 @@ http_status() {
local code
if [[ "$TRANSPORT" == "exec" ]]; then
code="$(docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [host, path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: host } }, (response) => { process.stdout.write(String(response.statusCode ?? "000")); response.resume(); }); request.on("error", () => process.stdout.write("000")); request.end();' "$host" "$path" || true)"
code="$(docker_smoke_probe "web:http-status" docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [host, path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: host } }, (response) => { process.stdout.write(String(response.statusCode ?? "000")); response.resume(); }); request.on("error", () => process.stdout.write("000")); request.end();' "$host" "$path" 2>/dev/null || true)"
else
code="$(curl -s -o /dev/null -w "%{http_code}" -H "Host: ${host}" "http://127.0.0.1:${PORT}${path}" || true)"
code="$(docker_smoke_probe "web:http-status" curl -s -o /dev/null -w "%{http_code}" -H "Host: ${host}" "http://127.0.0.1:${PORT}${path}" 2>/dev/null || true)"
fi
if [[ -z "$code" ]]; then
@@ -54,9 +94,47 @@ http_body() {
local path="$2"
if [[ "$TRANSPORT" == "exec" ]]; then
docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [host, path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: host } }, (response) => { let body = ""; response.setEncoding("utf8"); response.on("data", (chunk) => { body += chunk; }); response.on("end", () => process.stdout.write(body)); }); request.on("error", () => process.exit(1)); request.end();' "$host" "$path"
docker_smoke_probe "web:http-body" docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [host, path] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, headers: { Host: host } }, (response) => { let body = ""; response.setEncoding("utf8"); response.on("data", (chunk) => { body += chunk; }); response.on("end", () => process.stdout.write(body)); }); request.on("error", () => process.exit(1)); request.end();' "$host" "$path"
else
curl --fail --silent --show-error -H "Host: ${host}" "http://127.0.0.1:${PORT}${path}"
docker_smoke_probe "web:http-body" curl --fail --silent --show-error -H "Host: ${host}" "http://127.0.0.1:${PORT}${path}"
fi
}
http_header() {
local host="$1"
local path="$2"
local header_name="$3"
if [[ "$TRANSPORT" == "exec" ]]; then
docker_smoke_probe "web:http-header" docker exec "$CONTAINER_NAME" node -e 'const http = require("node:http"); const [host, path, headerName] = process.argv.slice(1); const request = http.request({ hostname: "127.0.0.1", port: 8080, path, method: "HEAD", headers: { Host: host } }, (response) => { const value = response.headers[headerName.toLowerCase()]; process.stdout.write(Array.isArray(value) ? value.join(", ") : value ?? ""); response.resume(); }); request.on("error", () => process.exit(1)); request.end();' "$host" "$path" "$header_name"
else
docker_smoke_probe "web:http-header" curl --fail --silent --show-error --head -H "Host: ${host}" "http://127.0.0.1:${PORT}${path}" \
| tr -d '\r' \
| awk -F': *' -v expected="$(printf '%s' "$header_name" | tr '[:upper:]' '[:lower:]')" 'tolower($1) == expected { sub(/^[^:]+:[[:space:]]*/, ""); print; exit }'
fi
}
expect_service_worker_csp() {
local host="$1"
local policy
policy="$(http_header "$host" /sw.js Content-Security-Policy)"
if [[ "$policy" != *"default-src 'none'"* || "$policy" != *"connect-src 'self'"* || "$policy" == *"connect-src 'none'"* ]]; then
echo "Expected ${host}/sw.js to allow only same-origin worker fetches, got ${policy:-<empty>}" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
expect_service_worker_recovery_bootstrap() {
local host="$1"
local body
body="$(http_body "$host" /login)"
if ! printf '%s' "$body" | node -e 'const fs = require("node:fs"); const html = fs.readFileSync(0, "utf8"); const markerIndex = html.indexOf("service-worker-csp-recovery:v3"); const stylesheetIndex = html.indexOf("rel=\"stylesheet\""); const scriptStart = html.lastIndexOf("<script", markerIndex); const scriptTagEnd = html.indexOf(">", scriptStart); const scriptTag = scriptStart >= 0 && scriptTagEnd > scriptStart ? html.slice(scriptStart, scriptTagEnd + 1) : ""; if (markerIndex < 0 || stylesheetIndex <= markerIndex || !/\snonce="[^"]+"/.test(scriptTag)) process.exit(1);'; then
echo "Expected ${host}/login to emit the nonce-protected worker recovery before stylesheet discovery" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
@@ -69,7 +147,7 @@ expect_status() {
actual="$(http_status "$host" "$path")"
if [[ "$actual" != "$expected" ]]; then
echo "Expected ${host}${path} to return ${expected}, got ${actual}" >&2
docker logs "$CONTAINER_NAME" >&2 || true
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
@@ -84,68 +162,583 @@ expect_health_revision() {
actual="$(printf "%s" "$body" | node -e 'const fs = require("node:fs"); try { const payload = JSON.parse(fs.readFileSync(0, "utf8")); process.stdout.write(payload.revision || ""); } catch { process.exit(1); }')"
if [[ "$actual" != "$SMOKE_REVISION" ]]; then
echo "Expected ${host}${path} revision ${SMOKE_REVISION}, got ${actual:-<empty>}" >&2
docker logs "$CONTAINER_NAME" >&2 || true
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
expect_openapi_json() {
expect_runtime_payload() {
local host="$1"
local path="$2"
local expected_status="$3"
local expected_service="$4"
local expected_surface="$5"
local body
body="$(http_body "$host" "$path")"
printf "%s" "$body" | node -e '
const fs = require("node:fs");
const payload = JSON.parse(fs.readFileSync(0, "utf8"));
if (typeof payload.openapi !== "string") throw new Error("missing openapi version");
if (!payload.paths || !payload.paths["/v1/health"] || !payload.paths["/v1/session/current-user"]) {
throw new Error("missing expected OpenAPI paths");
}
'
if ! printf "%s" "$body" | node -e '
const fs = require("node:fs");
const [expectedStatus, expectedService, expectedSurface, expectedRevision] = process.argv.slice(1);
try {
const payload = JSON.parse(fs.readFileSync(0, "utf8"));
if (
payload.status !== expectedStatus ||
payload.service !== expectedService ||
payload.surface !== expectedSurface ||
payload.revision !== expectedRevision
) process.exit(1);
} catch {
process.exit(1);
}
' "$expected_status" "$expected_service" "$expected_surface" "$SMOKE_REVISION"; then
echo "Expected ${host}${path} to report status=${expected_status}, service=${expected_service}, surface=${expected_surface}, revision=${SMOKE_REVISION}" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
trap cleanup EXIT
wait_for_runtime_health() {
local host="$1"
local label="$2"
for attempt in $(seq 1 "$HEALTH_ATTEMPTS"); do
HTTP_STATUS="$(http_status "$host" /healthz)"
CONTAINER_HEALTH="$(docker_smoke_probe "web:health-inspect" docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}missing{{end}}' "$CONTAINER_NAME" 2>/dev/null || true)"
if [[ "$HTTP_STATUS" == "200" && "$CONTAINER_HEALTH" == "healthy" ]]; then
return
fi
if [[ "$(docker_smoke_probe "web:running-inspect" docker inspect -f '{{.State.Running}}' "$CONTAINER_NAME" 2>/dev/null || true)" != "true" ]]; then
echo "${label} runtime container exited during boot" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
if [[ "$CONTAINER_HEALTH" == "unhealthy" ]]; then
echo "${label} container Docker HEALTHCHECK became unhealthy with HTTP status ${HTTP_STATUS}" >&2
docker_smoke_run "web:health-diagnostic" "$DOCKER_SMOKE_LOG_TIMEOUT_SECONDS" \
docker inspect -f '{{json .State.Health}}' "$CONTAINER_NAME" >&2 || true
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
if [[ "$attempt" == "$HEALTH_ATTEMPTS" ]]; then
echo "${label} container did not become HTTP- and Docker-healthy on port ${PORT} after ${HEALTH_ATTEMPTS}s" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
sleep 1
done
}
assert_runtime_boot_is_mutation_free() {
local label="$1"
local boot_logs
docker_smoke_capture boot_logs "web:runtime-logs:capture" "$DOCKER_SMOKE_LOG_TIMEOUT_SECONDS" \
docker logs --tail "$DOCKER_SMOKE_LOG_TAIL" "$CONTAINER_NAME"
if grep -Eq '^\[(?:boot|migrator)\]' <<<"$boot_logs"; then
echo "${label} runtime unexpectedly executed migration or seed work" >&2
exit 1
fi
if grep -q '\[DEP0169\]' <<<"$boot_logs"; then
echo "${label} container used Node's deprecated url.parse() runtime path" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
apply_image_sql_artifact() {
local artifact_path="$1"
local stage="$2"
docker_smoke_run "$stage" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" bash -o pipefail -c '
docker run --rm --name "$1" --entrypoint /bin/sh "$2" \
-c "test -f \"\$1\" && cat \"\$1\"" _ "$6" \
| docker exec -e "PGPASSWORD=$3" -e PGOPTIONS="--client-min-messages=warning" -i "$4" \
psql -v ON_ERROR_STOP=1 -h 127.0.0.1 -U hivegrid_migrator -d "$5" >/dev/null
' _ "$SQL_ARTIFACT_CONTAINER_NAME" "$IMAGE" "$MIGRATOR_DB_PASSWORD" "$DB_CONTAINER_NAME" "$DB_NAME" "$artifact_path"
}
seed_password_login_fixture() {
local password_hash
# Generate the fixture hash with argon2 from the exact image under test. The
# command substitution deliberately captures the hash so neither credential
# material nor the hash is written to smoke logs.
docker_smoke_capture password_hash "web:password-hash" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run --rm --name "$PASSWORD_HASH_CONTAINER_NAME" --entrypoint node "$IMAGE" -e '
import("argon2")
.then(({ default: argon2 }) => argon2.hash(process.argv[1], {
type: argon2.argon2id,
memoryCost: 19456,
timeCost: 2,
parallelism: 1,
}))
.then((hash) => process.stdout.write(hash))
.catch(() => process.exit(1));
' "$SMOKE_LOGIN_PASSWORD"
if [[ "$password_hash" != '$argon2id$'* ]]; then
echo "Exact web image failed to generate the password-login fixture hash" >&2
exit 1
fi
docker_smoke_run "web:seed-login-fixture" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -q \
-U "$DB_USER" -d "$DB_NAME" \
-v smoke_password_hash="$password_hash" \
-v smoke_tenant_id="$SMOKE_LOGIN_TENANT_ID" \
-v smoke_tenant_slug="$SMOKE_LOGIN_TENANT_SLUG" \
-v smoke_user_id="$SMOKE_LOGIN_USER_ID" \
-v smoke_email="$SMOKE_LOGIN_EMAIL" >/dev/null <<'SQL'
INSERT INTO "Tenant" ("id", "updatedAt", "slug", "name", "active")
VALUES (:'smoke_tenant_id', now(), :'smoke_tenant_slug', 'Docker runtime login', true);
INSERT INTO "User" ("id", "updatedAt", "email", "passwordHash", "firstName", "lastName", "defaultTenantId", "active")
VALUES (:'smoke_user_id', now(), :'smoke_email', :'smoke_password_hash', 'Docker', 'Runtime', :'smoke_tenant_id', true);
INSERT INTO "TenantUser" ("id", "tenantId", "userId", "type", "joined", "status")
VALUES ('docker-runtime-login-membership', :'smoke_tenant_id', :'smoke_user_id', 0, 0, 2);
SQL
}
expect_password_login_session() {
if ! docker_smoke_run "web:password-login" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker exec \
-e SMOKE_LOGIN_EMAIL="$SMOKE_LOGIN_EMAIL" \
-e SMOKE_LOGIN_PASSWORD="$SMOKE_LOGIN_PASSWORD" \
"$CONTAINER_NAME" node -e '
const http = require("node:http");
function request(options, body) {
return new Promise((resolve, reject) => {
const req = http.request(
{ hostname: "127.0.0.1", port: 8080, ...options },
(response) => {
let responseBody = "";
response.setEncoding("utf8");
response.on("data", (chunk) => { responseBody += chunk; });
response.on("end", () => resolve({
status: response.statusCode ?? 0,
headers: response.headers,
body: responseBody,
}));
},
);
req.on("error", reject);
if (body) req.write(body);
req.end();
});
}
(async () => {
const loginPage = await request({
path: "/login",
method: "GET",
headers: { Host: "app.localhost", Accept: "text/html" },
});
const csrf = loginPage.body.match(/<meta[^>]+name=["\x27]csrf-token["\x27][^>]+content=["\x27]([^"\x27]+)["\x27]/i)?.[1];
const loginPageCookies = loginPage.headers["set-cookie"] ?? [];
const cookieHeader = loginPageCookies.map((value) => value.split(";", 1)[0]).join("; ");
if (loginPage.status !== 200 || !csrf || !cookieHeader) {
throw new Error("login bootstrap did not provide status, CSRF, and cookies");
}
const form = new URLSearchParams({
email: process.env.SMOKE_LOGIN_EMAIL,
password: process.env.SMOKE_LOGIN_PASSWORD,
redirectTo: "",
csrf,
}).toString();
const loginResponse = await request({
path: "/login",
method: "POST",
headers: {
Host: "app.localhost",
Origin: "http://app.localhost",
Referer: "http://app.localhost/login",
Accept: "text/html,application/xhtml+xml",
Cookie: cookieHeader,
"Content-Type": "application/x-www-form-urlencoded",
"Content-Length": Buffer.byteLength(form),
},
}, form);
const responseCookies = loginResponse.headers["set-cookie"] ?? [];
const hasAuthenticatedCookie = responseCookies.some((value) => value.startsWith("__Host-hivegrid_app_session="));
const location = loginResponse.headers.location ?? "";
if (![302, 303].includes(loginResponse.status) || !hasAuthenticatedCookie || !location || location.includes("/login")) {
throw new Error(`login did not create an authenticated redirect (status ${loginResponse.status})`);
}
})().catch((error) => {
process.stderr.write(`${error instanceof Error ? error.message : "password login failed"}\n`);
process.exit(1);
});
' >/dev/null; then
echo "Expected exact web image to complete password login under required RLS" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
local active_session_count
docker_smoke_capture active_session_count "web:password-session" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -qAt \
-U "$DB_USER" -d "$DB_NAME" \
-v smoke_user_id="$SMOKE_LOGIN_USER_ID" <<'SQL'
SELECT count(*)
FROM "UserSession"
WHERE "userId" = :'smoke_user_id'
AND "revokedAt" IS NULL
AND "expiresAt" > now();
SQL
if [[ "$active_session_count" != "1" ]]; then
echo "Expected password login to create exactly one active server session, got ${active_session_count:-0}" >&2
emit_runtime_logs "$CONTAINER_NAME"
exit 1
fi
}
run_migrator() {
local output_variable="$1"
local stage="$2"
docker_smoke_capture "$output_variable" "$stage" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" \
docker run --rm --name "$MIGRATION_CONTAINER_NAME" --network "$NETWORK_NAME" \
-e DIRECT_URL="$MIGRATOR_DATABASE_URL" \
"$IMAGE" migrate
}
expect_migrator_completion() {
local logs="$1"
if ! grep -q '^\[migrator\] prisma migrate deploy' <<<"$logs"; then
echo "One-shot migrator logs are missing the migration banner" >&2
exit 1
fi
if ! grep -q '^\[migrator\] sync permission catalog' <<<"$logs"; then
echo "One-shot migrator logs are missing the permission catalog sync banner" >&2
exit 1
fi
if ! grep -q '"event":"permission-catalog-sync-complete"' <<<"$logs"; then
echo "One-shot migrator logs are missing the completed permission catalog postcondition" >&2
exit 1
fi
}
expect_permission_catalog_contract() {
local contract_status
docker_smoke_capture contract_status "web:permission-catalog-contract" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -qAt \
-U "$DB_USER" -d "$DB_NAME" <<'SQL'
WITH catalog_tables AS (
SELECT
relation.relname,
pg_get_userbyid(relation.relowner) AS owner_name,
relation.relrowsecurity AS rls_enabled,
relation.relforcerowsecurity AS force_rls,
has_table_privilege('hivegrid_rls_definer', format('%I.%I', namespace.nspname, relation.relname), 'SELECT') AS can_select,
has_table_privilege('hivegrid_rls_definer', format('%I.%I', namespace.nspname, relation.relname), 'INSERT,UPDATE,DELETE,TRUNCATE,REFERENCES,TRIGGER') AS has_table_dml,
has_any_column_privilege('hivegrid_rls_definer', format('%I.%I', namespace.nspname, relation.relname), 'INSERT,UPDATE,REFERENCES') AS has_column_dml
FROM pg_class AS relation
JOIN pg_namespace AS namespace ON namespace.oid = relation.relnamespace
WHERE namespace.nspname = 'public'
AND relation.relname IN ('Permission', 'Role', 'RolePermission')
), canonical_roles AS (
SELECT *
FROM "Role"
WHERE "tenantId" IS NULL
AND "name" IN ('SuperAdmin', 'SuperUser', 'Admin', 'Billing Admin', 'User')
)
SELECT (
(SELECT count(*) = 3 AND bool_and(owner_name = 'hivegrid_migrator' AND rls_enabled AND force_rls AND can_select AND NOT has_table_dml AND NOT has_column_dml) FROM catalog_tables)
AND (SELECT count(*) = 5 AND bool_and(NOT "isTemplateOrigin") FROM canonical_roles)
AND EXISTS (
SELECT 1 FROM canonical_roles
WHERE "name" = 'SuperUser'
AND "description" = 'Has all app permissions'
AND "type" = 'app'
AND NOT "assignToNewUsers"
AND "isDefault"
AND "order" = 2
)
AND EXISTS (
SELECT 1 FROM "Permission"
WHERE "name" = 'chat.write'
AND "description" = 'Default permission chat.write'
AND "type" = 'app'
AND "isDefault"
AND "order" > 0
)
AND EXISTS (
SELECT 1
FROM "RolePermission" AS grant_row
JOIN "Role" AS role_row ON role_row."id" = grant_row."roleId"
JOIN "Permission" AS permission_row ON permission_row."id" = grant_row."permissionId"
WHERE role_row."tenantId" IS NULL
AND role_row."name" = 'SuperUser'
AND permission_row."name" = 'chat.write'
)
AND NOT EXISTS (
SELECT 1
FROM "RolePermission" AS grant_row
JOIN "Role" AS role_row ON role_row."id" = grant_row."roleId"
JOIN "Permission" AS permission_row ON permission_row."id" = grant_row."permissionId"
WHERE role_row."tenantId" IS NULL
AND role_row."name" = 'User'
AND permission_row."name" = 'admin.accounts.view'
)
)::text;
SQL
if [[ "$contract_status" != "true" ]]; then
echo "Permission catalog data, FORCE RLS, or definer ACL postcondition failed" >&2
exit 1
fi
}
seed_permission_catalog_sentinel() {
docker_smoke_run "web:seed-permission-sentinel" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -q \
-U "$DB_USER" -d "$DB_NAME" \
-v sentinel_tenant_id="$CATALOG_SENTINEL_TENANT_ID" \
-v sentinel_role_id="$CATALOG_SENTINEL_ROLE_ID" \
-v sentinel_grant_id="$CATALOG_SENTINEL_GRANT_ID" >/dev/null <<'SQL'
INSERT INTO "Tenant" ("id", "updatedAt", "slug", "name", "active")
VALUES (:'sentinel_tenant_id', now(), 'docker-catalog-sentinel', 'Docker catalog sentinel', true);
INSERT INTO "Role" (
"id", "updatedAt", "tenantId", "name", "description", "type",
"assignToNewUsers", "isDefault", "order", "seatCategory", "isTemplateOrigin"
)
VALUES (
:'sentinel_role_id', now(), :'sentinel_tenant_id', 'Admin', 'Tenant-owned byte sentinel', 'app',
true, true, 777, 'office', true
);
INSERT INTO "RolePermission" ("id", "roleId", "permissionId")
SELECT :'sentinel_grant_id', :'sentinel_role_id', "id"
FROM "Permission"
WHERE "name" = 'app.dashboard.view';
SQL
}
permission_catalog_state_snapshot() {
local snapshot
docker_smoke_capture snapshot "web:permission-state-snapshot" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -qAt \
-U "$DB_USER" -d "$DB_NAME" <<'SQL'
SELECT md5(
COALESCE((
SELECT string_agg(concat_ws('|', "id", "name", "description", "type", "isDefault"::text, "order"::text, "updatedAt"::text), E'\n' ORDER BY "name")
FROM "Permission"
WHERE "isDefault"
), '') || E'\n--roles--\n' || COALESCE((
SELECT string_agg(concat_ws('|', "id", "name", "description", "type", "assignToNewUsers"::text, "isDefault"::text, "order"::text, "isTemplateOrigin"::text, "updatedAt"::text), E'\n' ORDER BY "name")
FROM "Role"
WHERE "tenantId" IS NULL
AND "name" IN ('SuperAdmin', 'SuperUser', 'Admin', 'Billing Admin', 'User')
), '') || E'\n--grants--\n' || COALESCE((
SELECT string_agg(concat_ws('|', grant_row."id", grant_row."roleId", grant_row."permissionId"), E'\n' ORDER BY grant_row."roleId", grant_row."permissionId")
FROM "RolePermission" AS grant_row
JOIN "Role" AS role_row ON role_row."id" = grant_row."roleId"
WHERE role_row."tenantId" IS NULL
AND role_row."name" IN ('SuperAdmin', 'SuperUser', 'Admin', 'Billing Admin', 'User')
), '')
);
SQL
printf '%s' "$snapshot"
}
permission_catalog_value_snapshot() {
local snapshot
docker_smoke_capture snapshot "web:permission-value-snapshot" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -qAt \
-U "$DB_USER" -d "$DB_NAME" <<'SQL'
SELECT md5(
COALESCE((
SELECT string_agg(concat_ws('|', "id", "name", "description", "type", "isDefault"::text, "order"::text), E'\n' ORDER BY "name")
FROM "Permission"
WHERE "isDefault"
), '') || E'\n--roles--\n' || COALESCE((
SELECT string_agg(concat_ws('|', "id", "name", "description", "type", "assignToNewUsers"::text, "isDefault"::text, "order"::text, "isTemplateOrigin"::text), E'\n' ORDER BY "name")
FROM "Role"
WHERE "tenantId" IS NULL
AND "name" IN ('SuperAdmin', 'SuperUser', 'Admin', 'Billing Admin', 'User')
), '') || E'\n--grants--\n' || COALESCE((
SELECT string_agg(concat_ws('|', grant_row."id", grant_row."roleId", grant_row."permissionId"), E'\n' ORDER BY grant_row."roleId", grant_row."permissionId")
FROM "RolePermission" AS grant_row
JOIN "Role" AS role_row ON role_row."id" = grant_row."roleId"
WHERE role_row."tenantId" IS NULL
AND role_row."name" IN ('SuperAdmin', 'SuperUser', 'Admin', 'Billing Admin', 'User')
), '')
);
SQL
printf '%s' "$snapshot"
}
tenant_catalog_sentinel_snapshot() {
local snapshot
docker_smoke_capture snapshot "web:tenant-sentinel-snapshot" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -qAt \
-U "$DB_USER" -d "$DB_NAME" \
-v sentinel_role_id="$CATALOG_SENTINEL_ROLE_ID" <<'SQL'
SELECT md5(concat_ws('|',
role_row."id", role_row."updatedAt"::text, role_row."tenantId", role_row."name", role_row."description", role_row."type",
role_row."assignToNewUsers"::text, role_row."isDefault"::text, role_row."order"::text,
role_row."seatCategory"::text, role_row."isTemplateOrigin"::text,
grant_row."id", grant_row."permissionId"
))
FROM "Role" AS role_row
JOIN "RolePermission" AS grant_row ON grant_row."roleId" = role_row."id"
WHERE role_row."id" = :'sentinel_role_id';
SQL
printf '%s' "$snapshot"
}
inject_permission_catalog_drift() {
docker_smoke_run "web:inject-permission-drift" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker exec -i "$DB_CONTAINER_NAME" psql -v ON_ERROR_STOP=1 -q \
-U "$DB_USER" -d "$DB_NAME" \
-v stale_grant_id="$CATALOG_STALE_GRANT_ID" >/dev/null <<'SQL'
UPDATE "Permission"
SET "description" = 'drifted', "type" = 'drifted', "isDefault" = false, "order" = -1
WHERE "name" = 'chat.write';
UPDATE "Role"
SET "description" = 'drifted', "type" = 'admin', "assignToNewUsers" = true, "isDefault" = false, "order" = -1
WHERE "tenantId" IS NULL AND "name" = 'SuperUser';
INSERT INTO "RolePermission" ("id", "roleId", "permissionId")
SELECT :'stale_grant_id', role_row."id", permission_row."id"
FROM "Role" AS role_row
CROSS JOIN "Permission" AS permission_row
WHERE role_row."tenantId" IS NULL
AND role_row."name" = 'User'
AND permission_row."name" = 'admin.accounts.view'
ON CONFLICT ("roleId", "permissionId") DO NOTHING;
SQL
}
docker_smoke_install_cleanup_traps cleanup
cleanup
SMOKE_REVISION="$(resolve_smoke_revision)"
if [[ -z "$SMOKE_REVISION" || "$SMOKE_REVISION" == "<no value>" || "$SMOKE_REVISION" == "unknown" ]]; then
echo "Image ${IMAGE} does not expose a concrete org.opencontainers.image.revision; build with --build-arg APP_REVISION or set DOCKER_WEB_SMOKE_REVISION explicitly" >&2
exit 1
fi
docker network create "$NETWORK_NAME" >/dev/null
docker_smoke_run "web:network-create" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker network create "$NETWORK_NAME" >/dev/null
docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db -p 127.0.0.1::5432 \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
DB_PORT="$(docker port "$DB_CONTAINER_NAME" 5432/tcp | awk -F: 'NR == 1 { print $NF }')"
CONTAINER_DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
docker_smoke_run "web:redis-start" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$REDIS_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias redis redis:7-alpine >/dev/null
for attempt in $(seq 1 30); do
if docker exec "$DB_CONTAINER_NAME" pg_isready -U "$DB_USER" -d "$DB_NAME" >/dev/null 2>&1; then
if docker_smoke_probe "web:redis-ready" docker exec "$REDIS_CONTAINER_NAME" redis-cli ping 2>/dev/null | grep -q PONG; then
break
fi
if [[ "$attempt" == "30" ]]; then
echo "Postgres smoke database did not become ready" >&2
docker logs "$DB_CONTAINER_NAME" >&2 || true
echo "Redis smoke service did not become ready" >&2
emit_runtime_logs "$REDIS_CONTAINER_NAME"
exit 1
fi
sleep 1
done
docker_smoke_run "web:postgres-start" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db -p 127.0.0.1::5432 \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
MIGRATOR_DATABASE_URL="postgresql://hivegrid_migrator:${MIGRATOR_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
APP_DATABASE_URL="postgresql://hivegrid_app:${APP_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
# Probe over TCP, not the unix socket. On first boot the postgres image starts a
# temporary server that listens on the socket ONLY (initdb + init scripts), then
# shuts it down before starting the real one. A socket-based pg_isready reports
# ready during that window, so the very next psql can hit
# "FATAL: the database system is shutting down". The temp server sets
# listen_addresses='', so a TCP probe cannot succeed too early.
if ! docker_smoke_wait_for_postgres "web:postgres-ready" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME"; then
echo "Postgres smoke database did not become ready within the ${DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS}-second budget" >&2
emit_runtime_logs "$DB_CONTAINER_NAME"
exit 1
fi
provision_docker_smoke_rls_roles \
"web:provision-rls-roles" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME" \
"$MIGRATOR_DB_PASSWORD" "$APP_DB_PASSWORD" "$WORKER_DB_PASSWORD" "$AUTHENTIK_JIT_DB_PASSWORD"
MIGRATOR_LOGS=""
run_migrator MIGRATOR_LOGS "web:migrate:initial"
expect_migrator_completion "$MIGRATOR_LOGS"
expect_permission_catalog_contract
seed_permission_catalog_sentinel
TENANT_SENTINEL_SNAPSHOT="$(tenant_catalog_sentinel_snapshot)"
CATALOG_STATE_SNAPSHOT="$(permission_catalog_state_snapshot)"
CATALOG_VALUE_SNAPSHOT="$(permission_catalog_value_snapshot)"
if [[ -z "$TENANT_SENTINEL_SNAPSHOT" || -z "$CATALOG_STATE_SNAPSHOT" || -z "$CATALOG_VALUE_SNAPSHOT" ]]; then
echo "Permission catalog smoke snapshots are incomplete" >&2
exit 1
fi
SECOND_MIGRATOR_LOGS=""
run_migrator SECOND_MIGRATOR_LOGS "web:migrate:idempotency"
expect_migrator_completion "$SECOND_MIGRATOR_LOGS"
expect_permission_catalog_contract
if [[ "$(tenant_catalog_sentinel_snapshot)" != "$TENANT_SENTINEL_SNAPSHOT" ]]; then
echo "Idempotent permission catalog sync mutated a tenant-owned template role" >&2
exit 1
fi
if [[ "$(permission_catalog_state_snapshot)" != "$CATALOG_STATE_SNAPSHOT" ]]; then
echo "Idempotent permission catalog sync changed canonical catalog state" >&2
exit 1
fi
inject_permission_catalog_drift
THIRD_MIGRATOR_LOGS=""
run_migrator THIRD_MIGRATOR_LOGS "web:migrate:drift-repair"
expect_migrator_completion "$THIRD_MIGRATOR_LOGS"
expect_permission_catalog_contract
if [[ "$(tenant_catalog_sentinel_snapshot)" != "$TENANT_SENTINEL_SNAPSHOT" ]]; then
echo "Permission catalog drift repair mutated a tenant-owned template role" >&2
exit 1
fi
if [[ "$(permission_catalog_value_snapshot)" != "$CATALOG_VALUE_SNAPSHOT" ]]; then
echo "Permission catalog drift repair did not restore canonical values and grants" >&2
exit 1
fi
# The feature branch intentionally carries its Prisma and RLS artifacts before
# the reviewed merge migration exists. Apply those artifacts only to this
# disposable, already-migrated smoke database so both runtime surfaces exercise
# the current built-image schema without weakening the production migration
# contract.
apply_image_sql_artifact "/myapp/prisma/rls/portal-legacy-commerce-recut-pre-db-push.sql" "web:sql-artifact:legacy-recut"
docker_smoke_run "web:db-push" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" \
docker run --rm --name "$DB_PUSH_CONTAINER_NAME" --network "$NETWORK_NAME" --entrypoint node \
-e DATABASE_URL="$MIGRATOR_DATABASE_URL" \
"$IMAGE" /myapp/node_modules/prisma/build/index.js db push \
--accept-data-loss \
--config prisma.config.ts
apply_image_sql_artifact "/myapp/prisma/rls/tenant-policy-contract-isolation.sql" "web:sql-artifact:tenant-policy"
apply_image_sql_artifact "/myapp/prisma/rls/portal-policy-contract-isolation.sql" "web:sql-artifact:portal-policy"
apply_image_sql_artifact "/myapp/prisma/rls/portal-domain-capabilities.sql" "web:sql-artifact:portal-domain"
seed_password_login_fixture
publish_args=(-p 127.0.0.1::8080)
if [[ -n "$PORT" ]]; then
publish_args=(-p "${PORT}:8080")
fi
# Migrations and the guarded seed run through the entrypoint boot path
# (MIGRATE_ON_BOOT/SEED_ON_BOOT), exactly like the Coolify staging/production
# web resources — this smoke is the PR-level rehearsal of that boot contract.
docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args[@]}" \
docker_smoke_run "web:core-start" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args[@]}" \
-e NODE_ENV=production \
-e PORT=8080 \
-e APP_NAME=HiveGrid \
@@ -153,66 +746,190 @@ docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" "${publish_args
-e WEB_APP_HOST=app.localhost \
-e ADMIN_APP_HOST=admin.localhost \
-e API_HOST=api.localhost \
-e PORTAL_APP_HOST=portal.localhost \
-e APP_PROTOCOL=http \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
-e WEB_RUNTIME_SURFACE=core \
-e DATABASE_URL="$APP_DATABASE_URL" \
-e DATABASE_RUNTIME_ROLE=hivegrid_app \
-e RLS_RUNTIME_MODE=required \
-e SENTRY_ENVIRONMENT=staging \
-e STAGING_DEMO_LOGIN_ENABLED=true \
-e REDIS_URL='redis://redis:6379/0' \
-e IP_HASH_PEPPER='deploy-smoke-ip-hash-pepper-minimum-32' \
-e AUTH_PASSWORD_HIBP_CHECK=false \
-e SESSION_SECRET='deploy-smoke-session-secret-minimum-32' \
-e CRYPTO_SECRET='deploy-smoke-crypto-secret-minimum-32' \
-e ADMIN_CONNECTION_MASTER_KEY='deploy-smoke-admin-connection-key-minimum-32' \
-e JWT_SECRET='deploy-smoke-jwt-secret-minimum-32' \
-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32' \
-e API_ACCESS_TOKEN='deploy-smoke-api-access-token-minimum-32' \
-e ANALYTICS_TOKEN='deploy-smoke-analytics-token-minimum-32' \
-e WEB_PUSH_VAPID_PUBLIC_KEY="$SMOKE_WEB_PUSH_VAPID_PUBLIC_KEY" \
-e STORAGE_ENDPOINT='https://storage.example.test' \
-e STORAGE_REGION='eu-central-1' \
-e STORAGE_BUCKET='docker-smoke-private-exports' \
-e STORAGE_ACCESS_KEY_ID='docker-smoke-storage-access-key' \
-e STORAGE_SECRET_ACCESS_KEY='docker-smoke-storage-secret-key' \
-e STORAGE_SESSION_TOKEN='docker-smoke-storage-session-token' \
-e STORAGE_FORCE_PATH_STYLE=false \
-e GDPR_EXPORT_SSE_C_KEY_BASE64="$SMOKE_GDPR_EXPORT_SSE_C_KEY_BASE64" \
-e MCP_RESOURCE_URL='http://mcp.localhost:8080' \
-e MCP_AUTHORIZATION_SERVER_URL='http://app.localhost' \
-e SEED_ADMIN_EMAIL='deploy-smoke-admin@example.test' \
-e SEED_ADMIN_PASSWORD='deploy-smoke-password-minimum-32' \
-e MIGRATE_ON_BOOT=true \
-e SEED_ON_BOOT=true \
"$IMAGE" >/dev/null
"$IMAGE" >/dev/null
if [[ -z "$PORT" ]]; then
PORT="$(docker port "$CONTAINER_NAME" 8080/tcp | awk -F: 'NR == 1 { print $NF }')"
CORE_PORT_BINDING=""
docker_smoke_capture CORE_PORT_BINDING "web:core-port" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker port "$CONTAINER_NAME" 8080/tcp
PORT="$(printf '%s\n' "$CORE_PORT_BINDING" | awk -F: 'NR == 1 { print $NF }')"
fi
for attempt in $(seq 1 "$HEALTH_ATTEMPTS"); do
if [[ "$(http_status app.localhost /healthz)" == "200" ]]; then
break
fi
if [[ "$(docker inspect -f '{{.State.Running}}' "$CONTAINER_NAME" 2>/dev/null)" != "true" ]]; then
echo "Web container exited during boot — MIGRATE_ON_BOOT/SEED_ON_BOOT failure aborts the start by design" >&2
docker logs "$CONTAINER_NAME" >&2 || true
exit 1
fi
if [[ "$attempt" == "$HEALTH_ATTEMPTS" ]]; then
echo "Web container did not become healthy on port ${PORT} after ${HEALTH_ATTEMPTS}s" >&2
docker logs "$CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
# Prove the entrypoint boot contract actually ran (not a container that came
# up against a pre-migrated database through some other path).
BOOT_LOGS="$(docker logs "$CONTAINER_NAME" 2>&1)"
if ! grep -q '^\[boot\] prisma migrate deploy' <<<"$BOOT_LOGS"; then
echo "Web container logs are missing the MIGRATE_ON_BOOT migration banner" >&2
docker logs "$CONTAINER_NAME" >&2 || true
exit 1
fi
if ! grep -q '^\[boot\] production seed' <<<"$BOOT_LOGS"; then
echo "Web container logs are missing the SEED_ON_BOOT seed banner" >&2
docker logs "$CONTAINER_NAME" >&2 || true
exit 1
fi
wait_for_runtime_health app.localhost Web
assert_runtime_boot_is_mutation_free Web
expect_status app.localhost /healthz 200
expect_health_revision app.localhost /healthz
expect_status app.localhost /readyz 200
expect_status api.localhost /v1/docs 200
expect_status api.localhost /v1/openapi.json 200
expect_openapi_json api.localhost /v1/openapi.json
expect_password_login_session
expect_status app.localhost /sw.js 200
expect_service_worker_csp app.localhost
expect_service_worker_recovery_bootstrap app.localhost
# The web image must never serve the separately deployed API surface.
expect_status api.localhost /v1/docs 404
expect_status api.localhost /v1/openapi.json 404
expect_status api.localhost /v1/health 404
expect_status app.localhost /app/acme/settings 404
expect_status admin.localhost /settings 404
docker_smoke_run "web:core-cleanup" "$DOCKER_SMOKE_CLEANUP_TIMEOUT_SECONDS" \
docker rm -f "$CORE_CONTAINER_NAME" >/dev/null
CONTAINER_NAME="$ADMIN_CONTAINER_NAME"
PORT="$ADMIN_PORT"
admin_publish_args=(-p 127.0.0.1::8080)
if [[ -n "$PORT" ]]; then
admin_publish_args=(-p "${PORT}:8080")
fi
docker_smoke_run "web:admin-start" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$ADMIN_CONTAINER_NAME" --network "$NETWORK_NAME" "${admin_publish_args[@]}" \
-e NODE_ENV=production \
-e PORT=8080 \
-e APP_NAME=HiveGrid \
-e APP_BASE_DOMAIN=localhost \
-e WEB_APP_HOST=app.localhost \
-e ADMIN_APP_HOST=admin.localhost \
-e API_HOST=api.localhost \
-e PORTAL_APP_HOST=portal.localhost \
-e APP_PROTOCOL=http \
-e WEB_RUNTIME_SURFACE=admin \
-e DATABASE_URL="$APP_DATABASE_URL" \
-e DATABASE_RUNTIME_ROLE=hivegrid_app \
-e RLS_RUNTIME_MODE=required \
-e SENTRY_ENVIRONMENT=staging \
-e REDIS_URL='redis://redis:6379/0' \
-e IP_HASH_PEPPER='deploy-smoke-ip-hash-pepper-minimum-32' \
-e AUTH_PASSWORD_HIBP_CHECK=false \
-e SESSION_SECRET='deploy-smoke-admin-session-secret-minimum-32' \
-e CRYPTO_SECRET='deploy-smoke-crypto-secret-minimum-32' \
-e ADMIN_CONNECTION_MASTER_KEY='deploy-smoke-admin-connection-key-minimum-32' \
-e ADMIN_FALLBACK_LOGIN_ENABLED=false \
-e JWT_SECRET='deploy-smoke-jwt-secret-minimum-32' \
-e AUDIT_CHAIN_SECRET='deploy-smoke-audit-chain-secret-minimum-32' \
-e API_ACCESS_TOKEN='deploy-smoke-api-access-token-minimum-32' \
-e ANALYTICS_TOKEN='deploy-smoke-analytics-token-minimum-32' \
-e WEB_PUSH_VAPID_PUBLIC_KEY="$SMOKE_WEB_PUSH_VAPID_PUBLIC_KEY" \
-e STORAGE_ENDPOINT='https://storage.example.test' \
-e STORAGE_REGION='eu-central-1' \
-e STORAGE_BUCKET='docker-smoke-private-exports' \
-e STORAGE_ACCESS_KEY_ID='docker-smoke-storage-access-key' \
-e STORAGE_SECRET_ACCESS_KEY='docker-smoke-storage-secret-key' \
-e STORAGE_SESSION_TOKEN='docker-smoke-storage-session-token' \
-e STORAGE_FORCE_PATH_STYLE=false \
-e GDPR_EXPORT_SSE_C_KEY_BASE64="$SMOKE_GDPR_EXPORT_SSE_C_KEY_BASE64" \
-e MCP_RESOURCE_URL='http://mcp.localhost:8080' \
-e MCP_AUTHORIZATION_SERVER_URL='http://admin.localhost' \
-e AUTHENTIK_ISSUER_URL='https://auth.example.test/application/o/hivegrid-admin/' \
-e AUTHENTIK_ADMIN_CLIENT_ID='docker-smoke-admin' \
-e AUTHENTIK_ADMIN_CLIENT_SECRET='docker-smoke-authentik-secret-minimum-32' \
-e AUTHENTIK_ADMIN_REDIRECT_URI='https://admin.localhost/auth/admin/callback' \
-e AUTHENTIK_ADMIN_JIT_DATABASE_URL="postgresql://hivegrid_authentik_jit:${AUTHENTIK_JIT_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public" \
"$IMAGE" >/dev/null
if [[ -z "$PORT" ]]; then
ADMIN_PORT_BINDING=""
docker_smoke_capture ADMIN_PORT_BINDING "web:admin-port" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker port "$ADMIN_CONTAINER_NAME" 8080/tcp
PORT="$(printf '%s\n' "$ADMIN_PORT_BINDING" | awk -F: 'NR == 1 { print $NF }')"
fi
wait_for_runtime_health admin.localhost Admin
assert_runtime_boot_is_mutation_free Admin
expect_status admin.localhost /healthz 200
expect_runtime_payload admin.localhost /healthz ok hivegrid-admin admin
expect_status admin.localhost /readyz 200
expect_runtime_payload admin.localhost /readyz ready hivegrid-admin admin
expect_status app.localhost /healthz 404
expect_status portal.localhost /healthz 404
expect_status admin.localhost /settings 302
echo "Docker web runtime smoke passed for ${IMAGE}"
docker_smoke_run "web:admin-cleanup" "$DOCKER_SMOKE_CLEANUP_TIMEOUT_SECONDS" \
docker rm -f "$ADMIN_CONTAINER_NAME" >/dev/null
PORTAL_DATABASE_URL="postgresql://hivegrid_portal:${DOCKER_SMOKE_PORTAL_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
CONTAINER_NAME="$PORTAL_CONTAINER_NAME"
PORT="$PORTAL_PORT"
portal_publish_args=(-p 127.0.0.1::8080)
if [[ -n "$PORT" ]]; then
portal_publish_args=(-p "${PORT}:8080")
fi
docker_smoke_run "web:portal-start" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$PORTAL_CONTAINER_NAME" --network "$NETWORK_NAME" "${portal_publish_args[@]}" \
-e NODE_ENV=production \
-e PORT=8080 \
-e APP_NAME=HiveGrid \
-e APP_BASE_DOMAIN=localhost \
-e PORTAL_APP_HOST=portal.localhost \
-e APP_PROTOCOL=http \
-e WEB_RUNTIME_SURFACE=portal \
-e DATABASE_URL="$PORTAL_DATABASE_URL" \
-e DATABASE_RUNTIME_ROLE=hivegrid_portal \
-e RLS_RUNTIME_MODE=required \
-e SENTRY_ENVIRONMENT=staging \
-e PORTAL_SESSION_SECRET='portal-smoke-session-secret-minimum-32' \
-e AUTH_MAGIC_LINK_ENABLED=true \
-e AUTH_MAGIC_LINK_TOKEN_TTL_MINUTES=15 \
-e CAPTCHA_PROVIDER=mcaptcha \
-e MCAPTCHA_INSTANCE_URL='http://127.0.0.1:9090' \
-e MCAPTCHA_SITEKEY_LOGIN='portal-smoke-login-sitekey' \
-e MCAPTCHA_ACCOUNT_SECRET='portal-smoke-captcha-secret' \
-e REDIS_URL='redis://redis:6379/0' \
-e BULLMQ_REDIS_URL='redis://redis:6379/0' \
-e STORAGE_ENDPOINT='https://storage.example.test' \
-e STORAGE_REGION='eu-central-1' \
-e STORAGE_BUCKET='docker-smoke-private-exports' \
-e STORAGE_ACCESS_KEY_ID='docker-smoke-storage-access-key' \
-e STORAGE_SECRET_ACCESS_KEY='docker-smoke-storage-secret-key' \
-e STORAGE_SESSION_TOKEN='docker-smoke-storage-session-token' \
-e STORAGE_FORCE_PATH_STYLE=false \
-e GDPR_EXPORT_SSE_C_KEY_BASE64="$SMOKE_GDPR_EXPORT_SSE_C_KEY_BASE64" \
-e MCP_RESOURCE_URL='http://mcp.localhost:8080' \
-e MCP_AUTHORIZATION_SERVER_URL='http://portal.localhost' \
"$IMAGE" >/dev/null
if [[ -z "$PORT" ]]; then
PORTAL_PORT_BINDING=""
docker_smoke_capture PORTAL_PORT_BINDING "web:portal-port" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker port "$PORTAL_CONTAINER_NAME" 8080/tcp
PORT="$(printf '%s\n' "$PORTAL_PORT_BINDING" | awk -F: 'NR == 1 { print $NF }')"
fi
wait_for_runtime_health portal.localhost Portal
assert_runtime_boot_is_mutation_free Portal
expect_status portal.localhost /healthz 200
expect_runtime_payload portal.localhost /healthz ok hivegrid-portal portal
expect_status portal.localhost /readyz 200
expect_runtime_payload portal.localhost /readyz ready hivegrid-portal portal
echo "Docker web, admin, and portal runtime smoke passed for ${IMAGE}"
@@ -1,44 +1,115 @@
#!/usr/bin/env bash
set -euo pipefail
DOCKER_SMOKE_RUN_ID="${DOCKER_SMOKE_RUN_ID:-$$}"
if [[ -z "$DOCKER_SMOKE_RUN_ID" || ${#DOCKER_SMOKE_RUN_ID} -gt 80 || ! $DOCKER_SMOKE_RUN_ID =~ ^[A-Za-z0-9_.-]+$ ]]; then
echo "DOCKER_SMOKE_RUN_ID must contain 1-80 Docker-safe characters" >&2
exit 2
fi
# shellcheck source=scripts/lib/docker-rls-role-fixture.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-rls-role-fixture.sh"
# shellcheck source=scripts/lib/docker-runtime-smoke.sh
source "$(dirname "${BASH_SOURCE[0]}")/lib/docker-runtime-smoke.sh"
IMAGE="${1:-hivegrid-worker:smoke}"
CONTAINER_NAME="${DOCKER_WORKER_SMOKE_CONTAINER:-hivegrid-worker-runtime-smoke-$$}"
DB_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_DB_CONTAINER:-hivegrid-worker-runtime-smoke-db-$$}"
REDIS_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_REDIS_CONTAINER:-hivegrid-worker-runtime-smoke-redis-$$}"
NETWORK_NAME="${DOCKER_WORKER_SMOKE_NETWORK:-hivegrid-worker-runtime-smoke-$$}"
MIGRATOR_IMAGE="${DOCKER_SMOKE_MIGRATOR_IMAGE:-hivegrid-web:smoke}"
CONTAINER_NAME="${DOCKER_WORKER_SMOKE_CONTAINER:-hivegrid-worker-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
DB_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_DB_CONTAINER:-hivegrid-worker-runtime-smoke-db-${DOCKER_SMOKE_RUN_ID}}"
REDIS_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_REDIS_CONTAINER:-hivegrid-worker-runtime-smoke-redis-${DOCKER_SMOKE_RUN_ID}}"
MEILI_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_MEILI_CONTAINER:-hivegrid-worker-runtime-smoke-meili-${DOCKER_SMOKE_RUN_ID}}"
MEILI_IMAGE="${DOCKER_WORKER_SMOKE_MEILI_IMAGE:-getmeili/meilisearch:v1.8}"
MEILI_IMAGE_PULL_TIMEOUT_SECONDS="${DOCKER_WORKER_SMOKE_MEILI_IMAGE_PULL_TIMEOUT_SECONDS:-180}"
NETWORK_NAME="${DOCKER_WORKER_SMOKE_NETWORK:-hivegrid-worker-runtime-smoke-${DOCKER_SMOKE_RUN_ID}}"
MIGRATION_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_MIGRATION_CONTAINER:-hivegrid-worker-runtime-smoke-migrate-${DOCKER_SMOKE_RUN_ID}}"
ASSERT_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_ASSERT_CONTAINER:-hivegrid-worker-runtime-smoke-assert-${DOCKER_SMOKE_RUN_ID}}"
DISABLED_HEALTH_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_DISABLED_HEALTH_CONTAINER:-hivegrid-worker-runtime-smoke-disabled-${DOCKER_SMOKE_RUN_ID}}"
ENABLED_HEALTH_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_ENABLED_HEALTH_CONTAINER:-hivegrid-worker-runtime-smoke-enabled-${DOCKER_SMOKE_RUN_ID}}"
MAIL_HEALTH_CONTAINER_NAME="${DOCKER_WORKER_SMOKE_MAIL_HEALTH_CONTAINER:-hivegrid-worker-runtime-smoke-mail-${DOCKER_SMOKE_RUN_ID}}"
SMOKE_REVISION="${DOCKER_WORKER_SMOKE_REVISION:-}"
DB_PASSWORD="hivegrid"
DB_NAME="hivegrid"
DB_USER="hivegrid"
WORKER_DB_PASSWORD="hivegrid-worker-smoke"
APP_DB_PASSWORD="hivegrid-app-smoke"
MIGRATOR_DB_PASSWORD="hivegrid-migrator-smoke"
AUTHENTIK_JIT_DB_PASSWORD="hivegrid-authentik-jit-smoke"
cleanup() {
docker rm -f "$CONTAINER_NAME" >/dev/null 2>&1 || true
docker rm -f "$DB_CONTAINER_NAME" >/dev/null 2>&1 || true
docker rm -f "$REDIS_CONTAINER_NAME" >/dev/null 2>&1 || true
docker network rm "$NETWORK_NAME" >/dev/null 2>&1 || true
docker_smoke_cleanup_container "worker:cleanup-containers" \
"$CONTAINER_NAME" "$MIGRATION_CONTAINER_NAME" "$ASSERT_CONTAINER_NAME" \
"$DISABLED_HEALTH_CONTAINER_NAME" "$ENABLED_HEALTH_CONTAINER_NAME" "$MAIL_HEALTH_CONTAINER_NAME" \
"$DB_CONTAINER_NAME" "$REDIS_CONTAINER_NAME" "$MEILI_CONTAINER_NAME"
docker_smoke_cleanup_network "worker:cleanup-network" "$NETWORK_NAME"
}
resolve_smoke_revision() {
local image_revision
if [[ -n "$SMOKE_REVISION" ]]; then
printf "%s" "$SMOKE_REVISION"
return
fi
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
docker_smoke_capture image_revision "worker:inspect-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$IMAGE"
printf "%s" "$image_revision"
}
trap cleanup EXIT
verify_migrator_revision() {
local migrator_revision
docker_smoke_capture migrator_revision "worker:inspect-migrator-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker image inspect -f '{{ index .Config.Labels "org.opencontainers.image.revision" }}' "$MIGRATOR_IMAGE"
if [[ "$migrator_revision" != "$SMOKE_REVISION" ]]; then
echo "Migrator image ${MIGRATOR_IMAGE} revision ${migrator_revision:-<empty>} does not match worker image revision ${SMOKE_REVISION}" >&2
exit 1
fi
}
docker_smoke_install_cleanup_traps cleanup
cleanup
SMOKE_REVISION="$(resolve_smoke_revision)"
if [[ -z "$SMOKE_REVISION" || "$SMOKE_REVISION" == "<no value>" || "$SMOKE_REVISION" == "unknown" ]]; then
echo "Image ${IMAGE} does not expose a concrete org.opencontainers.image.revision; build with --build-arg APP_REVISION or set DOCKER_WORKER_SMOKE_REVISION explicitly" >&2
exit 1
fi
verify_migrator_revision
worker_env=(
-e NODE_ENV=production
-e APP_NAME=HiveGrid
-e APP_BASE_DOMAIN=localhost
-e DATABASE_RUNTIME_ROLE=hivegrid_worker
-e RLS_RUNTIME_MODE=required
-e AUDIT_CHAIN_SECRET=deploy-smoke-audit-chain-secret-minimum-32
-e ADMIN_CONNECTION_MASTER_KEY=deploy-smoke-admin-connection-key-minimum-32
)
# Obvious non-production fixtures prove that the required general-worker
# provider boundary is wired without storing any live credential in the repo.
product_acquisition_env=(
-e LAGO_API_URL=http://lago.internal.test:3108
-e LAGO_API_KEY=test-lago-runtime-smoke
-e LAGO_TIMEOUT_MS=10000
-e MOLLIE_API_KEY=test-mollie-runtime-smoke
-e MOLLIE_PROFILE_ID=pfl_runtime_smoke
-e BILLING_MOLLIE_WEBHOOK_URL=https://api.hivegrid.test/v1/billing/mollie/webhooks
-e MOLLIE_TIMEOUT_MS=10000
)
# Obvious non-production fixtures keep the general-worker smoke aligned with
# its fail-closed export-retention and tenant-hard-delete contracts. The
# delete-only runtime must not receive the SSE-C key used by writers/readers.
general_hard_delete_env=(
-e EXPORT_RETENTION_QUEUE_ENABLED=true
-e STORAGE_ENDPOINT=https://storage.example.test
-e STORAGE_REGION=eu-central-1
-e STORAGE_BUCKET=docker-smoke-private-exports
-e STORAGE_ACCESS_KEY_ID=docker-smoke-retention-access-key
-e STORAGE_SECRET_ACCESS_KEY=docker-smoke-retention-secret-key
-e STORAGE_FORCE_PATH_STYLE=false
-e MEILI_URL=http://meili:7700
-e MEILI_API_KEY=docker-smoke-tenant-delete-meili-master-key
)
expect_worker_health() {
@@ -55,6 +126,7 @@ if (report.status !== expectedStatus) {
console.error(`Expected worker status ${expectedStatus}, got ${report.status}`);
process.exit(1);
}
if (String(report.workerEnabled) !== expectedEnabled) {
console.error(`Expected workerEnabled ${expectedEnabled}, got ${report.workerEnabled}`);
process.exit(1);
@@ -82,109 +154,254 @@ if (expectedStatus === "ready" && (report.databaseStatus !== "ready" || report.r
' "$output" "$expected_status" "$expected_enabled" "$SMOKE_REVISION" "$expected_group" "$expected_queue"
}
docker network create "$NETWORK_NAME" >/dev/null
expect_worker_deploy_health() {
local output="$1"
local expected_group="$2"
health_output="$(
docker run --rm \
"${worker_env[@]}" \
-e WORKER_ENABLED=false \
"$IMAGE" node apps/worker/dist/health.js
)"
node -e '
const [raw, expectedRevision, expectedGroup] = process.argv.slice(1);
const report = JSON.parse(raw);
if (report.status !== "ready" || report.revision !== expectedRevision || report.workerGroup !== expectedGroup) {
console.error("Worker deployment health did not prove the expected revision and group");
process.exit(1);
}
' "$output" "$SMOKE_REVISION" "$expected_group"
}
docker_smoke_run "worker:create-network" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker network create "$NETWORK_NAME" >/dev/null
health_output=""
docker_smoke_capture health_output "worker:health-disabled" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run --rm --name "$DISABLED_HEALTH_CONTAINER_NAME" \
"${worker_env[@]}" \
-e WORKER_ENABLED=false \
"$IMAGE" node apps/worker/dist/health.js
expect_worker_health "$health_output" disabled false
docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db \
docker_smoke_run "worker:start-db" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$DB_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias db \
-e POSTGRES_USER="$DB_USER" \
-e POSTGRES_PASSWORD="$DB_PASSWORD" \
-e POSTGRES_DB="$DB_NAME" \
postgres:16-alpine >/dev/null
docker run -d --name "$REDIS_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias redis redis:7-alpine >/dev/null
docker_smoke_run "worker:start-redis" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --name "$REDIS_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias redis redis:7-alpine >/dev/null
CONTAINER_DATABASE_URL="postgresql://${DB_USER}:${DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
if ! docker image inspect "$MEILI_IMAGE" >/dev/null 2>&1; then
docker_smoke_run "worker:pull-meili" "$MEILI_IMAGE_PULL_TIMEOUT_SECONDS" docker pull "$MEILI_IMAGE" >/dev/null
fi
docker_smoke_run "worker:start-meili" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run -d --pull=never --name "$MEILI_CONTAINER_NAME" --network "$NETWORK_NAME" --network-alias meili \
-e MEILI_MASTER_KEY=docker-smoke-tenant-delete-meili-master-key \
-e MEILI_ENV=development \
-e MEILI_NO_ANALYTICS=true \
"$MEILI_IMAGE" >/dev/null
MIGRATOR_DATABASE_URL="postgresql://hivegrid_migrator:${MIGRATOR_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
WORKER_DATABASE_URL="postgresql://hivegrid_worker:${WORKER_DB_PASSWORD}@db:5432/${DB_NAME}?schema=public"
CONTAINER_REDIS_URL="redis://redis:6379/0"
for attempt in $(seq 1 30); do
if docker exec "$DB_CONTAINER_NAME" pg_isready -U "$DB_USER" -d "$DB_NAME" >/dev/null 2>&1; then
break
fi
# Probe over TCP, not the unix socket. On first boot the postgres image starts a
# temporary server that listens on the socket ONLY (initdb + init scripts), then
# shuts it down before starting the real one. A socket-based pg_isready reports
# ready during that window, so the very next psql can hit
# "FATAL: the database system is shutting down". The temp server sets
# listen_addresses='', so a TCP probe cannot succeed too early.
if ! docker_smoke_wait_for_postgres "worker:probe-db" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME"; then
echo "Postgres smoke database did not become ready within the ${DOCKER_SMOKE_DATABASE_READY_TIMEOUT_SECONDS}-second budget" >&2
docker_smoke_logs "worker:logs-db" "$DB_CONTAINER_NAME" >&2 || true
exit 1
fi
if [[ "$attempt" == "30" ]]; then
echo "Postgres smoke database did not become ready" >&2
docker logs "$DB_CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
provision_docker_smoke_rls_roles \
"worker:provision-rls-roles" \
"$DB_CONTAINER_NAME" "$DB_USER" "$DB_NAME" \
"$MIGRATOR_DB_PASSWORD" "$APP_DB_PASSWORD" "$WORKER_DB_PASSWORD" "$AUTHENTIK_JIT_DB_PASSWORD"
for attempt in $(seq 1 30); do
if docker exec "$REDIS_CONTAINER_NAME" redis-cli ping >/dev/null 2>&1; then
if docker_smoke_probe "worker:probe-redis" docker exec "$REDIS_CONTAINER_NAME" redis-cli ping >/dev/null 2>&1; then
break
fi
if [[ "$attempt" == "30" ]]; then
echo "Redis smoke broker did not become ready" >&2
docker logs "$REDIS_CONTAINER_NAME" >&2 || true
docker_smoke_logs "worker:logs-redis" "$REDIS_CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
docker run --rm --network "$NETWORK_NAME" \
-e NODE_ENV=production \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
--entrypoint /bin/sh \
"$IMAGE" -lc 'cd /myapp && pnpm exec prisma migrate deploy --config prisma.config.ts' >/dev/null
for attempt in $(seq 1 60); do
if docker_smoke_probe "worker:probe-meili" \
docker exec "$MEILI_CONTAINER_NAME" wget -q -O /dev/null http://127.0.0.1:7700/health; then
break
fi
enabled_health_output="$(
docker run --rm --network "$NETWORK_NAME" \
"${worker_env[@]}" \
-e WORKER_ENABLED=true \
-e WORKER_QUEUE_GROUP=general \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
-e BULLMQ_REDIS_URL="$CONTAINER_REDIS_URL" \
"$IMAGE" node apps/worker/dist/health.js
)"
expect_worker_health "$enabled_health_output" ready true general hivegrid.notifications
if [[ "$attempt" == "60" ]]; then
echo "Meilisearch smoke service did not become ready" >&2
docker_smoke_logs "worker:logs-meili" "$MEILI_CONTAINER_NAME" >&2 || true
exit 1
fi
mail_health_output="$(
docker run --rm --network "$NETWORK_NAME" \
"${worker_env[@]}" \
-e WORKER_ENABLED=true \
-e WORKER_QUEUE_GROUP=mail \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
-e BULLMQ_REDIS_URL="$CONTAINER_REDIS_URL" \
"$IMAGE" node apps/worker/dist/health.js
)"
expect_worker_health "$mail_health_output" ready true mail hivegrid.email
sleep 1
done
docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" \
# The web image owns the reviewed deployment migrations. Reuse that immutable
# closure so the worker smoke needs neither host dependencies nor migration
# tooling in the least-privilege worker runtime.
docker_smoke_run "worker:migrate" "$DOCKER_SMOKE_MIGRATION_TIMEOUT_SECONDS" docker run --rm --name "$MIGRATION_CONTAINER_NAME" --network "$NETWORK_NAME" \
-e DIRECT_URL="$MIGRATOR_DATABASE_URL" \
"$MIGRATOR_IMAGE" migrate
# Runtime workers consume the generated Prisma client but never migrate or
# compile code. Guard the image-size and least-authority boundary directly.
docker_smoke_run "worker:assert-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run --rm --name "$ASSERT_CONTAINER_NAME" --entrypoint node "$IMAGE" -e '
const fs = require("node:fs");
const entries = fs.readdirSync("/myapp/node_modules/.pnpm");
const forbidden = [
/^prisma@/,
/^typescript@/,
/^@prisma\+engines@/,
/^@prisma\+studio-core@/,
/^@prisma\+dev@/,
/^@electric-sql\+pglite(?:@|-)/,
/^better-sqlite3@/,
];
const retained = entries.filter((entry) => forbidden.some((pattern) => pattern.test(entry)));
if (retained.length > 0) {
console.error(`Worker runtime retained build or migration toolchains: ${retained.join(", ")}`);
process.exit(1);
}
' >/dev/null
enabled_health_output=""
docker_smoke_capture enabled_health_output "worker:health-enabled" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run --rm --name "$ENABLED_HEALTH_CONTAINER_NAME" --network "$NETWORK_NAME" \
"${worker_env[@]}" \
"${product_acquisition_env[@]}" \
"${general_hard_delete_env[@]}" \
-e WORKER_ENABLED=true \
-e WORKER_QUEUE_GROUP=general \
-e DATABASE_URL="$CONTAINER_DATABASE_URL" \
-e DATABASE_URL="$WORKER_DATABASE_URL" \
-e BULLMQ_REDIS_URL="$CONTAINER_REDIS_URL" \
"$IMAGE" >/tmp/hivegrid-worker-runtime-smoke.log
"$IMAGE" node apps/worker/dist/health.js
expect_worker_health "$enabled_health_output" ready true general hivegrid.notifications
MISMATCHED_REVISION="$(printf '0%.0s' {1..40})"
if [[ "$MISMATCHED_REVISION" == "$SMOKE_REVISION" ]]; then
MISMATCHED_REVISION="$(printf 'f%.0s' {1..40})"
fi
mail_health_output=""
docker_smoke_capture mail_health_output "worker:health-mail" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" \
docker run --rm --name "$MAIL_HEALTH_CONTAINER_NAME" --network "$NETWORK_NAME" \
"${worker_env[@]}" \
-e WORKER_ENABLED=true \
-e WORKER_QUEUE_GROUP=mail \
-e CRYPTO_SECRET=deploy-smoke-shared-tenant-envelope-secret-minimum-32 \
-e DATABASE_URL="$WORKER_DATABASE_URL" \
-e BULLMQ_REDIS_URL="$CONTAINER_REDIS_URL" \
"$IMAGE" node apps/worker/dist/health.js
expect_worker_health "$mail_health_output" ready true mail hivegrid.email
docker_smoke_run "worker:start-runtime" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker run -d --name "$CONTAINER_NAME" --network "$NETWORK_NAME" \
"${worker_env[@]}" \
"${product_acquisition_env[@]}" \
"${general_hard_delete_env[@]}" \
-e WORKER_ENABLED=true \
-e WORKER_QUEUE_GROUP=general \
-e DATABASE_URL="$WORKER_DATABASE_URL" \
-e BULLMQ_REDIS_URL="$CONTAINER_REDIS_URL" \
-e OUTBOX_DISPATCHER_ENABLED=true \
-e OUTBOX_DISPATCHER_REQUIRED=true \
-e WORKFLOW_TRIGGER_EXECUTOR_MODE=http \
-e WORKFLOW_TRIGGER_EXECUTOR_URL=http://127.0.0.1:9 \
-e API_ACCESS_TOKEN=deploy-smoke-worker-api-token \
-e WORKFLOW_TRIGGER_OUTBOX_ENABLED=true \
-e WORKFLOW_TRIGGER_OUTBOX_CONCURRENCY=5 \
-e WORKFLOW_TRIGGER_OUTBOX_REQUIRED=true \
"$IMAGE" >/dev/null
for attempt in $(seq 1 10); do
if [[ "$(docker inspect -f '{{.State.Running}}' "$CONTAINER_NAME" 2>/dev/null || true)" == "true" ]]; then
running=""
docker_smoke_capture running "worker:inspect-running" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker inspect -f '{{.State.Running}}' "$CONTAINER_NAME" 2>/dev/null || true
if [[ "$running" == "true" ]]; then
break
fi
if [[ "$attempt" == "10" ]]; then
echo "Worker container did not stay running" >&2
docker logs "$CONTAINER_NAME" >&2 || true
docker_smoke_logs "worker:logs-startup" "$CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
running_health_output="$(
running_health_output=""
docker_smoke_capture running_health_output "worker:health-runtime" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node apps/worker/dist/health.js
)"
expect_worker_health "$running_health_output" ready true general hivegrid.notifications
docker_smoke_run "worker:assert-revision-file" "$DOCKER_SMOKE_COMMAND_TIMEOUT_SECONDS" docker exec "$CONTAINER_NAME" sh -eu -c '
path=/myapp/.image-revision
expected_revision="$1"
owner_uid="$(stat -c "%u" "$path")"
mode="$(stat -c "%a" "$path")"
actual_revision="$(cat "$path")"
if [ "$owner_uid" != "0" ] || [ $((0$mode & 022)) -ne 0 ] || [ "$actual_revision" != "$expected_revision" ]; then
echo "Worker immutable image revision file is not root-owned, read-only, and exact" >&2
exit 1
fi
' _ "$SMOKE_REVISION"
deploy_health_output=""
for attempt in $(seq 1 20); do
deploy_health_attempt=""
if docker_smoke_capture deploy_health_attempt "worker:deploy-health" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
bash -c 'docker exec "$@" 2>&1' _ "$CONTAINER_NAME" node apps/worker/dist/deploy-health.js "$SMOKE_REVISION" general 2>/dev/null; then
deploy_health_output="$deploy_health_attempt"
break
fi
if [[ "$attempt" == "20" ]]; then
echo "Worker deployment health did not become ready" >&2
docker_smoke_run "worker:deploy-health-final" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" \
docker exec "$CONTAINER_NAME" node apps/worker/dist/deploy-health.js "$SMOKE_REVISION" general >&2 || true
docker_smoke_run "worker:readiness-diagnostic" "$DOCKER_SMOKE_LOG_TIMEOUT_SECONDS" docker exec "$CONTAINER_NAME" node -e '
fetch(`http://127.0.0.1:${process.env.WORKER_HEALTH_PORT || "9100"}/readyz`)
.then(async (response) => process.stderr.write(`${response.status} ${await response.text()}\n`))
.catch(() => process.stderr.write("Worker readiness endpoint could not be queried\n"));
' >&2 || true
docker_smoke_logs "worker:logs-deploy-health" "$CONTAINER_NAME" >&2 || true
exit 1
fi
sleep 1
done
expect_worker_deploy_health "$deploy_health_output" general
docker_smoke_expect_docker_exec_rejection "worker:reject-spoofed-revision" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
env APP_REVISION="$MISMATCHED_REVISION" \
node apps/worker/dist/deploy-health.js "$MISMATCHED_REVISION" general
docker_smoke_expect_docker_exec_rejection "worker:reject-wrong-group" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
node apps/worker/dist/deploy-health.js "$SMOKE_REVISION" mail
docker_smoke_expect_docker_exec_rejection "worker:reject-disabled" "$DOCKER_SMOKE_PROBE_TIMEOUT_SECONDS" "$CONTAINER_NAME" \
env WORKER_ENABLED=false \
node apps/worker/dist/deploy-health.js "$SMOKE_REVISION" general
WORKER_LOGS=""
if ! WORKER_LOGS="$(docker_smoke_logs "worker:logs-deprecation" "$CONTAINER_NAME" 2>&1)"; then
printf '%s\n' "$WORKER_LOGS" >&2
exit 1
fi
if grep -q '\[DEP0169\]' <<<"$WORKER_LOGS"; then
echo "Worker container used Node's deprecated url.parse() runtime path" >&2
docker_smoke_logs "worker:logs-deprecation-failure" "$CONTAINER_NAME" >&2 || true
exit 1
fi
echo "Docker worker runtime smoke passed for ${IMAGE}"
@@ -1,6 +1,7 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { createRequire } from "node:module";
import assert from "node:assert/strict";
import { execFileSync } from "node:child_process";
import { afterEach, describe, it } from "vitest";
@@ -31,9 +32,9 @@ afterEach(() => {
describe("docs-link-check", () => {
it("passes for valid local Markdown links and anchors", () => {
const rootDir = createFixture({
"README.md": "# Root\nSee [plugins](docs/plugins.md#plugin-boundaries).",
"docs/plugins.md": "# Plugin Boundaries\nSee [feature inventory](feature-inventory.md).",
"docs/feature-inventory.md": "# Feature Inventory\n",
"README.md": "# Root\nSee [plugins](docs/plugins.md#plugin-runtime).",
"docs/plugins.md": "# Plugin Runtime\nSee [runtime](features/plugins.md).",
"docs/features/plugins.md": "# Plugin Feature\n",
});
const result = checkDocsLinks(rootDir, ["README.md", "docs"]);
@@ -104,15 +105,13 @@ describe("docs-link-check", () => {
"README.md": "# Root\nSee [missing](docs/missing.md).",
"AGENTS.md": "# Agents\n",
"SECURITY.md": "# Security\n",
"CHANGELOG.md": "# Changelog\n",
"docs/index.md": "# Docs\n",
"guides/index.md": "# Guides\n",
});
let output = "";
assert.throws(() => {
try {
execFileSync("pnpm", ["exec", "tsx", path.resolve("scripts/docs-link-check.ts"), rootDir], { encoding: "utf8", stdio: "pipe" });
execFileSync(process.execPath, [createRequire(import.meta.url).resolve("tsx/cli"), path.resolve("scripts/docs-link-check.ts"), rootDir], { encoding: "utf8", stdio: "pipe" });
} catch (error) {
if (error && typeof error === "object") {
const failure = error as { stderr?: Buffer | string; stdout?: Buffer | string };
@@ -3,7 +3,7 @@ import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
export const DEFAULT_DOCS_ROOTS = ["README.md", "AGENTS.md", "SECURITY.md", "CHANGELOG.md", "docs", "guides"];
export const DEFAULT_DOCS_ROOTS = ["README.md", "AGENTS.md", "SECURITY.md", "docs"];
const MARKDOWN_LINK_PATTERN = /!?\[([^\]\n]*(?:\][^\]\n]*)*)\]\(([^)\n]+)\)/g;
const HEADING_PATTERN = /^#{1,6}\s+(.+)$/gm;
@@ -77,7 +77,13 @@ docker run --rm -d \
"$PG_IMAGE" >/dev/null
deadline=$(( $(date +%s) + 30 ))
until docker exec "$DRILL_NAME" pg_isready -U "$DRILL_USER" -d "$DRILL_DB" >/dev/null 2>&1; do
# Probe over TCP, not the unix socket. On first boot the postgres image starts a
# temporary server that listens on the socket ONLY (initdb + init scripts), then
# shuts it down before starting the real one. A socket-based pg_isready reports
# ready during that window, so the very next psql can hit
# "FATAL: the database system is shutting down". The temp server sets
# listen_addresses='', so a TCP probe cannot succeed too early.
until docker exec "$DRILL_NAME" pg_isready -h 127.0.0.1 -U "$DRILL_USER" -d "$DRILL_DB" >/dev/null 2>&1; do
if [ "$(date +%s)" -gt "$deadline" ]; then
echo "FAIL postgres did not become ready within 30s" >&2
exit 1
@@ -90,7 +96,6 @@ echo "PHASE 1/4 applying forward migration chain"
DATABASE_URL="$DRILL_DATABASE_URL" pnpm --filter @hivegrid/db prisma:generate >/dev/null
DATABASE_URL="$DRILL_DATABASE_URL" pnpm exec prisma migrate deploy --schema prisma/schema/schema.prisma
forward_count=$(DATABASE_URL="$DRILL_DATABASE_URL" pnpm exec prisma migrate status --schema prisma/schema/schema.prisma 2>&1 | grep -c "Following migration have been applied" || true)
echo "PASS forward migration chain applied"
if [ "$RUN_SEED" = "1" ]; then
@@ -0,0 +1,53 @@
// @vitest-environment node
import { describe, expect, it, vi } from "vitest";
import { pauseForOperatorCheckpoint } from "../tests/e2e/utils/operator-checkpoint";
function checkpointContext(headless?: boolean) {
return {
project: { use: { headless } },
annotations: [] as Array<{ type: string; description?: string }>,
};
}
describe("P26c operator checkpoint", () => {
it("is a no-op unless explicitly enabled", async () => {
const page = { pause: vi.fn() };
const testInfo = checkpointContext();
await expect(pauseForOperatorCheckpoint(page, testInfo, "domain-ownership-txt", {})).resolves.toBe(false);
await expect(pauseForOperatorCheckpoint(page, testInfo, "domain-ownership-txt", { E2E_OPERATOR_CHECKPOINTS: "0" })).resolves.toBe(false);
expect(page.pause).not.toHaveBeenCalled();
expect(testInfo.annotations).toEqual([]);
});
it("pauses only in an explicitly enabled local headed run", async () => {
const page = { pause: vi.fn().mockResolvedValue(undefined) };
const testInfo = checkpointContext(false);
await expect(pauseForOperatorCheckpoint(page, testInfo, "starter-addon-checkout", { E2E_OPERATOR_CHECKPOINTS: "1" })).resolves.toBe(true);
expect(page.pause).toHaveBeenCalledOnce();
expect(testInfo.annotations).toEqual([{ type: "operator-checkpoint", description: "starter-addon-checkout" }]);
});
it("fails closed for CI, headless runs, and invalid values", async () => {
const page = { pause: vi.fn() };
await expect(
pauseForOperatorCheckpoint(page, checkpointContext(false), "domain-setup-checkout", {
E2E_OPERATOR_CHECKPOINTS: "1",
CI: "1",
})
).rejects.toThrow("forbidden in CI");
await expect(pauseForOperatorCheckpoint(page, checkpointContext(true), "domain-setup-checkout", { E2E_OPERATOR_CHECKPOINTS: "1" })).rejects.toThrow(
"requires a headed Playwright run"
);
await expect(pauseForOperatorCheckpoint(page, checkpointContext(undefined), "domain-setup-checkout", { E2E_OPERATOR_CHECKPOINTS: "1" })).rejects.toThrow(
"requires a headed Playwright run"
);
await expect(pauseForOperatorCheckpoint(page, checkpointContext(false), "domain-setup-checkout", { E2E_OPERATOR_CHECKPOINTS: "yes" })).rejects.toThrow(
"must be unset, 0, or 1"
);
expect(page.pause).not.toHaveBeenCalled();
});
});
@@ -0,0 +1,21 @@
import { createDbClient } from "@hivegrid/db/client.server";
import { LOCAL_ADMIN_EMAIL, ensureLocalCredentials } from "~/utils/db/seed/localCredentials.server";
import { assertLocalCredentialsEnvironment } from "~/utils/db/seed/localCredentialsEnvironment.server";
async function main() {
const databaseUrl = assertLocalCredentialsEnvironment(process.env);
const client = createDbClient({ connectionString: databaseUrl.toString() });
try {
const result = await ensureLocalCredentials({ client, env: process.env });
process.stdout.write(`Local credentials ready: ${LOCAL_ADMIN_EMAIL}; normalized password identities: ${result.normalizedPasswordIdentityCount}.\n`);
} finally {
await client.$disconnect();
}
}
main().catch((error: unknown) => {
const message = error instanceof Error ? error.message : "Unknown local credential error";
process.stderr.write(`Local credential setup failed: ${message}\n`);
process.exitCode = 1;
});
@@ -0,0 +1,341 @@
#!/usr/bin/env node
import { readFile, writeFile, mkdir } from "node:fs/promises";
import { dirname, resolve } from "node:path";
const EXTERNAL_SCOPES = Object.freeze(["adresse-extern", "archiv-extern", "termin-extern", "vorgang-extern", "aktivitaet-extern"]);
const CAPABILITY_BY_TAG = Object.freeze({
Adresse: "address",
Aktivitaet: "activity",
Aktivitaetenverwaltung: "activity",
ArchivExternal: "archive",
Monteursteuerung: "schedule",
Projekt: "project",
Projektampel: "project",
Termin: "schedule",
VorgangAnzeige: "project",
VorgangInfo: "project",
});
const MUTATION_PATH_PATTERN = /\/(?:Add|Delete|Import|Publish|Remove|Reset|Save)[^/]*$/u;
const SUPPORTED_METHODS = new Set(["delete", "get", "post", "put", "patch"]);
const CONTRACT_OUTPUT = "packages/integrations/src/kwp/contract/kwp-scoped-openapi.json";
const CATALOG_OUTPUT = "packages/integrations/src/kwp/contract/catalog.generated.ts";
const SCOPE_DOC_OUTPUT = "docs/integrations/KWP-API-SCOPE.md";
const [inputArg, contractOutputArg, scopeDocOutputArg, catalogOutputArg] = process.argv.slice(2);
if (!inputArg) {
process.stderr.write("Usage: node scripts/generate-kwp-scoped-contract.mjs <tenant-openapi.json> [contract-output] [scope-doc-output] [catalog-output]\n");
process.exitCode = 1;
} else {
await generate({
inputPath: resolve(inputArg),
contractOutputPath: resolve(contractOutputArg ?? CONTRACT_OUTPUT),
scopeDocOutputPath: resolve(scopeDocOutputArg ?? SCOPE_DOC_OUTPUT),
catalogOutputPath: resolve(catalogOutputArg ?? CATALOG_OUTPUT),
});
}
async function generate({ inputPath, contractOutputPath, scopeDocOutputPath, catalogOutputPath }) {
const source = JSON.parse(await readFile(inputPath, "utf8"));
assertOpenApi(source);
const allOperations = listOperations(source);
const scopedOperations = allOperations
.filter((operation) => operation.scopes.some((scope) => EXTERNAL_SCOPES.includes(scope)))
.map((operation) => ({
...operation,
capability: requireCapability(operation.tag),
mode: MUTATION_PATH_PATTERN.test(operation.path) ? "mutation" : "read",
}))
.sort(compareOperations);
assertInventory(allOperations, scopedOperations);
const duplicatePaths = new Set(
scopedOperations
.filter((operation, index, operations) => operations.some((candidate, candidateIndex) => candidateIndex !== index && candidate.path === operation.path))
.map((operation) => operation.path)
);
const paths = {};
for (const operation of scopedOperations) {
const operationId = buildOperationId(operation, duplicatePaths);
const operationContract = stripDocumentationMetadata(structuredClone(operation.contract));
operationContract.operationId = operationId;
operationContract["x-hivegrid-capability"] = operation.capability;
operationContract["x-hivegrid-mode"] = operation.mode;
paths[operation.path] ??= {};
paths[operation.path][operation.method] = operationContract;
}
const schemaNames = collectReferencedSchemaNames(paths, source.components.schemas);
const schemas = Object.fromEntries(
[...schemaNames].sort((left, right) => left.localeCompare(right)).map((name) => [name, stripDocumentationMetadata(source.components.schemas[name])])
);
const inventory = {
sourceOperationCount: allOperations.length,
scopedOperationCount: scopedOperations.length,
readOperationCount: scopedOperations.filter((operation) => operation.mode === "read").length,
mutationOperationCount: scopedOperations.filter((operation) => operation.mode === "mutation").length,
excludedOperationCount: allOperations.length - scopedOperations.length,
externalScopes: EXTERNAL_SCOPES,
capabilities: Object.fromEntries(
[...new Set(scopedOperations.map((operation) => operation.capability))].sort().map((capability) => [
capability,
{
total: scopedOperations.filter((operation) => operation.capability === capability).length,
read: scopedOperations.filter((operation) => operation.capability === capability && operation.mode === "read").length,
mutation: scopedOperations.filter((operation) => operation.capability === capability && operation.mode === "mutation").length,
},
])
),
};
const scopedContract = {
openapi: source.openapi,
info: {
title: "KWP Api, licensed scope",
version: source.info.version,
},
paths: sortObject(paths),
components: { schemas },
"x-hivegrid-inventory": inventory,
};
await mkdir(dirname(contractOutputPath), { recursive: true });
await writeFile(contractOutputPath, `${JSON.stringify(scopedContract, null, 2)}\n`);
await mkdir(dirname(scopeDocOutputPath), { recursive: true });
await writeFile(scopeDocOutputPath, renderScopeDocument(scopedOperations, inventory, inputPath));
await mkdir(dirname(catalogOutputPath), { recursive: true });
await writeFile(catalogOutputPath, renderTypeScriptCatalog(scopedOperations, duplicatePaths, inventory));
process.stdout.write(
`Generated ${scopedOperations.length} KWP scoped operations (${inventory.readOperationCount} read, ${inventory.mutationOperationCount} mutation).\n`
);
}
function assertOpenApi(value) {
if (
!value ||
typeof value !== "object" ||
typeof value.openapi !== "string" ||
!value.info ||
typeof value.info.version !== "string" ||
!value.paths ||
typeof value.paths !== "object" ||
!value.components?.schemas ||
typeof value.components.schemas !== "object"
) {
throw new Error("The input is not the expected KWP OpenAPI document");
}
}
function listOperations(source) {
const operations = [];
for (const [path, pathItem] of Object.entries(source.paths)) {
for (const [method, contract] of Object.entries(pathItem)) {
if (!SUPPORTED_METHODS.has(method) || !contract || typeof contract !== "object") continue;
const tag = Array.isArray(contract.tags) ? contract.tags[0] : undefined;
if (typeof tag !== "string" || tag.length === 0) {
throw new Error(`KWP operation ${method.toUpperCase()} ${path} has no tag`);
}
operations.push({
method,
path,
tag,
summary: typeof contract.summary === "string" ? contract.summary : "",
scopes: readSecurityScopes(contract.security),
contract,
});
}
}
return operations;
}
function readSecurityScopes(security) {
if (!Array.isArray(security)) return [];
return [
...new Set(
security.flatMap((entry) =>
entry && typeof entry === "object" && Array.isArray(entry.oauth2) ? entry.oauth2.filter((scope) => typeof scope === "string") : []
)
),
];
}
function requireCapability(tag) {
const capability = CAPABILITY_BY_TAG[tag];
if (!capability) throw new Error(`Scoped KWP tag ${tag} is not assigned to a capability`);
return capability;
}
function assertInventory(allOperations, scopedOperations) {
const readCount = scopedOperations.filter((operation) => operation.mode === "read").length;
const mutationCount = scopedOperations.length - readCount;
if (allOperations.length !== 554 || scopedOperations.length !== 113 || readCount !== 77 || mutationCount !== 36) {
throw new Error(`KWP inventory drifted: total=${allOperations.length}, scoped=${scopedOperations.length}, read=${readCount}, mutation=${mutationCount}`);
}
}
function buildOperationId(operation, duplicatePaths) {
const base = `${toIdentifier(operation.tag, false)}${toIdentifier(operation.path.split("/").at(-1), true)}`;
return duplicatePaths.has(operation.path) ? `${base}${toIdentifier(operation.method, true)}` : base;
}
function toIdentifier(value, upperFirst) {
const words = String(value ?? "").match(/[A-Za-z0-9]+/gu) ?? [];
const joined = words
.map((word, index) => {
const normalized = word[0].toUpperCase() + word.slice(1);
if (index === 0 && !upperFirst) return normalized[0].toLowerCase() + normalized.slice(1);
return normalized;
})
.join("");
if (!joined) throw new Error(`Cannot derive an operation identifier from ${value}`);
return joined;
}
function collectReferencedSchemaNames(value, allSchemas) {
const found = new Set();
const pending = [...findRefs(value)];
while (pending.length > 0) {
const ref = pending.pop();
const prefix = "#/components/schemas/";
if (!ref.startsWith(prefix)) {
throw new Error(`Unsupported KWP contract reference ${ref}`);
}
const name = decodeURIComponent(ref.slice(prefix.length));
if (found.has(name)) continue;
const schema = allSchemas[name];
if (!schema) throw new Error(`Missing KWP schema ${name}`);
found.add(name);
pending.push(...findRefs(schema));
}
return found;
}
function findRefs(value) {
if (Array.isArray(value)) return value.flatMap(findRefs);
if (!value || typeof value !== "object") return [];
return Object.entries(value).flatMap(([key, nested]) => (key === "$ref" && typeof nested === "string" ? [nested] : findRefs(nested)));
}
function stripDocumentationMetadata(value) {
if (Array.isArray(value)) return value.map(stripDocumentationMetadata);
if (!value || typeof value !== "object") return value;
return Object.fromEntries(
Object.entries(value)
.filter(([key]) => key !== "description")
.map(([key, nested]) => [key, stripDocumentationMetadata(nested)])
);
}
function compareOperations(left, right) {
return (
left.capability.localeCompare(right.capability) ||
left.tag.localeCompare(right.tag) ||
left.path.localeCompare(right.path) ||
left.method.localeCompare(right.method)
);
}
function sortObject(value) {
return Object.fromEntries(
Object.entries(value)
.sort(([left], [right]) => left.localeCompare(right))
.map(([key, nested]) => [key, nested && typeof nested === "object" && !Array.isArray(nested) ? sortObject(nested) : nested])
);
}
function renderScopeDocument(operations, inventory) {
const capabilityRows = Object.entries(inventory.capabilities)
.map(([capability, counts]) => `| ${capability} | ${counts.total} | ${counts.read} | ${counts.mutation} |`)
.join("\n");
const operationRows = operations
.map((operation) => {
const id = buildOperationId(
operation,
new Set(
operations
.filter((candidate, index, all) => all.some((other, otherIndex) => otherIndex !== index && other.path === candidate.path))
.map((candidate) => candidate.path)
)
);
return `| \`${id}\` | ${operation.capability} | ${operation.mode} | \`${operation.method.toUpperCase()}\` | \`${operation.path}\` | ${escapeTableText(operation.summary)} |`;
})
.join("\n");
return `# KWP API: lizenzierter HiveGrid-Scope
> Generiert aus der am 2026-07-24 secretsicher gelesenen Tenant-OpenAPI. Die kundenspezifische
> Roh-Spezifikation, Server-URL und Credentials werden nicht eingecheckt.
## Inventur
- OpenAPI-Operationen gesamt: **${inventory.sourceOperationCount}**
- Über die fünf HiveGrid-\`*-extern\`-Scopes erreichbar: **${inventory.scopedOperationCount}**
- Semantisch lesend und runtime-allowlisted: **${inventory.readOperationCount}**
- Mutierend, nur Contract/Fixture und runtime-gesperrt: **${inventory.mutationOperationCount}**
- Außerhalb des lizenzierten HiveGrid-Scopes: **${inventory.excludedOperationCount}**
| Capability | Gesamt | Read | Mutation |
|---|---:|---:|---:|
${capabilityRows}
Die OpenAPI-Security-Arrays nennen mehrere alternative KWP-Produkte und die fünf externen Scopes, obwohl
die OAuth-Flow-Scope-Liste diese externen Namen nicht aufführt. HiveGrid klassifiziert eine Operation nur
dann als scoped, wenn mindestens einer der fünf tatsächlich angeforderten externen Scopes am Endpoint steht.
## Sicherheitsvertrag
- Fachcode übergibt nur eine feste Operation-ID plus deren typisierten Input, niemals URL, Pfad, Token,
Mandant oder Kundenkürzel.
- \`Search\`, \`Load\`, \`Count\`, \`Get\` und \`Check\` können trotz \`POST\` read-only sein.
- \`Save\`, \`Add\`, \`Delete\`, \`Remove\`, \`Import\`, \`Publish\` und \`Reset\` sind Mutation.
- Mutation wird vor Rate-Budget, Relay-Auflösung und HTTP blockiert.
- Der Scoped-Contract enthält nur rekursiv benötigte Schemas und keine tenant-spezifische Server-URL.
## Operationen
| ID | Capability | Modus | Methode | Pfad | KWP-Zusammenfassung |
|---|---|---|---|---|---|
${operationRows}
`;
}
function renderTypeScriptCatalog(operations, duplicatePaths, inventory) {
const entries = operations
.map((operation) => {
const value = {
id: buildOperationId(operation, duplicatePaths),
capability: operation.capability,
mode: operation.mode,
method: operation.method.toUpperCase(),
path: operation.path,
};
return ` ${JSON.stringify(value)},`;
})
.join("\n");
return `// Generated by scripts/generate-kwp-scoped-contract.mjs. Do not edit manually.
export const KWP_SCOPED_OPERATION_INVENTORY = Object.freeze({
sourceOperationCount: ${inventory.sourceOperationCount},
scopedOperationCount: ${inventory.scopedOperationCount},
readOperationCount: ${inventory.readOperationCount},
mutationOperationCount: ${inventory.mutationOperationCount},
excludedOperationCount: ${inventory.excludedOperationCount},
} as const);
export const KWP_SCOPED_OPERATIONS = Object.freeze([
${entries}
] as const);
export type KwpScopedOperation = (typeof KWP_SCOPED_OPERATIONS)[number];
export type KwpScopedOperationId = KwpScopedOperation["id"];
export type KwpReadOperationId = Extract<KwpScopedOperation, { readonly mode: "read" }>["id"];
export type KwpMutationOperationId = Extract<KwpScopedOperation, { readonly mode: "mutation" }>["id"];
export type KwpCapability = KwpScopedOperation["capability"];
`;
}
function escapeTableText(value) {
return value.replaceAll("|", "\\|").replaceAll(/\s+/gu, " ").trim();
}
@@ -1,7 +1,7 @@
#!/usr/bin/env node
// Generates a lightweight SBOM-style dependency manifest by shelling out to
// `pnpm list -r --json --depth=Infinity` and writing the result to
// `sbom-pnpm.json` in the repo root.
// Generates a lightweight SBOM-style dependency manifest. Docker builds point
// it at the already-pruned runtime node_modules tree so the document describes
// files that actually ship, rather than the full development workspace.
//
// Why pnpm-list instead of @cyclonedx/cyclonedx-npm:
// - cyclonedx-npm is opinionated about lockfile shape and tends to mis-handle
@@ -18,10 +18,14 @@ import { spawnSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import process from "node:process";
import { fileURLToPath } from "node:url";
import { fileURLToPath, pathToFileURL } from "node:url";
const HERE = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.resolve(HERE, "..");
const DOCUMENT_ROOT = process.env.SBOM_ROOT_PATH ? path.resolve(process.env.SBOM_ROOT_PATH) : ROOT;
const RUNTIME_NODE_MODULES_PATH = process.env.SBOM_NODE_MODULES_PATH
? path.resolve(process.env.SBOM_NODE_MODULES_PATH)
: undefined;
const OUTPUT_PATH = process.env.SBOM_OUTPUT_PATH
? path.resolve(process.env.SBOM_OUTPUT_PATH)
: path.join(ROOT, "sbom-pnpm.json");
@@ -53,31 +57,92 @@ function parseTree(raw) {
}
}
function repoVersion() {
function repoVersion(root = DOCUMENT_ROOT) {
try {
const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
const pkg = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8"));
return { name: pkg.name ?? null, version: pkg.version ?? null };
} catch {
return { name: null, version: null };
}
}
function packageDirectories(packageRoot) {
if (!fs.existsSync(packageRoot)) return [];
const directories = [];
for (const entry of fs.readdirSync(packageRoot, { withFileTypes: true })) {
if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
if (entry.name.startsWith("@")) {
const scopeRoot = path.join(packageRoot, entry.name);
if (!fs.existsSync(scopeRoot)) continue;
for (const scopedEntry of fs.readdirSync(scopeRoot, { withFileTypes: true })) {
if (scopedEntry.isDirectory() || scopedEntry.isSymbolicLink()) {
directories.push(path.join(scopeRoot, scopedEntry.name));
}
}
} else {
directories.push(path.join(packageRoot, entry.name));
}
}
return directories;
}
export function collectInstalledRuntimePackages(nodeModulesPath) {
const virtualStore = path.join(nodeModulesPath, ".pnpm");
if (!fs.existsSync(virtualStore)) {
throw new Error(`runtime pnpm virtual store not found: ${virtualStore}`);
}
const packages = new Map();
for (const entry of fs.readdirSync(virtualStore, { withFileTypes: true })) {
if (!entry.isDirectory() || entry.name === "node_modules") continue;
const packageRoot = path.join(virtualStore, entry.name, "node_modules");
for (const directory of packageDirectories(packageRoot)) {
const manifestPath = path.join(directory, "package.json");
if (!fs.existsSync(manifestPath)) continue;
try {
const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
if (typeof manifest.name !== "string" || typeof manifest.version !== "string") continue;
const key = `${manifest.name}@${manifest.version}`;
packages.set(key, {
name: manifest.name,
version: manifest.version,
license: typeof manifest.license === "string" ? manifest.license : null,
});
} catch {
// A malformed third-party manifest is omitted here and will remain
// visible to the separate fail-closed license inventory gate.
}
}
}
return [...packages.values()].sort((left, right) => `${left.name}@${left.version}`.localeCompare(`${right.name}@${right.version}`));
}
function generatedAt() {
const sourceDateEpoch = process.env.SOURCE_DATE_EPOCH;
if (!sourceDateEpoch || !/^\d+$/.test(sourceDateEpoch)) return null;
return new Date(Number(sourceDateEpoch) * 1000).toISOString();
}
function main() {
const raw = runPnpmList();
const tree = parseTree(raw);
const runtimePackages = RUNTIME_NODE_MODULES_PATH ? collectInstalledRuntimePackages(RUNTIME_NODE_MODULES_PATH) : undefined;
const tree = runtimePackages ? undefined : parseTree(runPnpmList());
const repo = repoVersion();
const document = {
schema: "hivegrid.sbom-pnpm/v1",
generatedAt: new Date().toISOString(),
schema: "hivegrid.sbom-pnpm/v2",
generatedAt: generatedAt(),
generator: "scripts/generate-sbom.mjs",
source: "pnpm list -r --json --depth=Infinity",
source: runtimePackages ? "installed pruned pnpm runtime tree" : "pnpm list -r --json --depth=Infinity",
target: process.env.SBOM_TARGET ?? null,
repo,
workspaces: tree,
...(runtimePackages ? { packageCount: runtimePackages.length, packages: runtimePackages } : { workspaces: tree }),
};
fs.mkdirSync(path.dirname(OUTPUT_PATH), { recursive: true });
fs.writeFileSync(OUTPUT_PATH, JSON.stringify(document, null, 2));
// eslint-disable-next-line no-console
console.log(`SBOM written: ${OUTPUT_PATH} (${tree.length} workspace entries)`);
console.log(
`SBOM written: ${OUTPUT_PATH} (${runtimePackages ? `${runtimePackages.length} runtime packages` : `${tree.length} workspace entries`})`,
);
}
main();
if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
main();
}
@@ -0,0 +1,41 @@
// @vitest-environment node
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, test } from "vitest";
import { collectInstalledRuntimePackages } from "./generate-sbom.mjs";
const temporaryDirectories = [];
afterEach(() => {
for (const directory of temporaryDirectories.splice(0)) {
fs.rmSync(directory, { recursive: true, force: true });
}
});
describe("runtime SBOM inventory", () => {
test("reports exact package versions present in the pruned pnpm virtual store", () => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "hivegrid-sbom-"));
temporaryDirectories.push(root);
const nodeModules = path.join(root, "node_modules");
const alpha = path.join(nodeModules, ".pnpm", "alpha@1.2.3", "node_modules", "alpha");
const beta = path.join(nodeModules, ".pnpm", "@scope+beta@4.5.6", "node_modules", "@scope", "beta");
fs.mkdirSync(alpha, { recursive: true });
fs.mkdirSync(beta, { recursive: true });
fs.writeFileSync(path.join(alpha, "package.json"), JSON.stringify({ name: "alpha", version: "1.2.3", license: "MIT" }));
fs.writeFileSync(path.join(beta, "package.json"), JSON.stringify({ name: "@scope/beta", version: "4.5.6", license: "Apache-2.0" }));
expect(collectInstalledRuntimePackages(nodeModules)).toEqual([
{ name: "@scope/beta", version: "4.5.6", license: "Apache-2.0" },
{ name: "alpha", version: "1.2.3", license: "MIT" },
]);
});
test("fails when the supplied runtime tree is not a pnpm deployment", () => {
const root = fs.mkdtempSync(path.join(os.tmpdir(), "hivegrid-sbom-missing-"));
temporaryDirectories.push(root);
expect(() => collectInstalledRuntimePackages(path.join(root, "node_modules"))).toThrow("virtual store not found");
});
});
@@ -0,0 +1,94 @@
#!/usr/bin/env tsx
/* eslint-disable no-console */
import { readFileSync } from "node:fs";
import path from "node:path";
import { performance } from "node:perf_hooks";
import { spawnSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import { i18nNamespaces } from "../packages/i18n/src/index.ts";
type Measurement = {
readonly locales: readonly string[];
readonly loadMs: number;
readonly rssDeltaMb: number;
readonly sourceMb: number;
};
const baselineLocales = ["de", "en"] as const;
const fullLocales = ["de", "en", "pl", "ru", "uk", "hu"] as const;
const maxAdditionalLoadMs = 250;
const maxAdditionalRssMb = 30;
const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
const childArgument = process.argv.find((argument) => argument.startsWith("--measure="));
if (childArgument) {
measureChild(childArgument.slice("--measure=".length).split(","));
} else {
const baseline = medianMeasurement(baselineLocales);
const full = medianMeasurement(fullLocales);
const additionalLoadMs = round(Math.max(0, full.loadMs - baseline.loadMs));
const additionalRssMb = round(Math.max(0, full.rssDeltaMb - baseline.rssDeltaMb));
const result = {
baseline,
full,
delta: { loadMs: additionalLoadMs, rssMb: additionalRssMb },
thresholds: { loadMs: maxAdditionalLoadMs, rssMb: maxAdditionalRssMb },
};
console.log(JSON.stringify(result, null, 2));
if (additionalLoadMs > maxAdditionalLoadMs || additionalRssMb > maxAdditionalRssMb) {
console.error("FAIL i18n catalog performance: switch to locale-scoped cached loading before release.");
process.exit(1);
}
console.log("PASS i18n catalog performance");
}
function measureChild(locales: readonly string[]): never {
global.gc?.();
const rssBefore = process.memoryUsage().rss;
const startedAt = performance.now();
let sourceBytes = 0;
const resources: Record<string, Record<string, unknown>> = {};
for (const locale of locales.flatMap((candidate) => [candidate, `${candidate}-formal`])) {
resources[locale] = {};
for (const namespace of i18nNamespaces) {
const source = readFileSync(path.join(root, "apps/web/public/locales", locale, `${namespace}.json`), "utf8");
sourceBytes += Buffer.byteLength(source);
resources[locale]![namespace] = JSON.parse(source) as unknown;
}
}
const loadMs = performance.now() - startedAt;
global.gc?.();
const rssAfter = process.memoryUsage().rss;
if (Object.keys(resources).length === 0) throw new Error("No i18n resources loaded.");
const result: Measurement = {
locales,
loadMs: round(loadMs),
rssDeltaMb: round((rssAfter - rssBefore) / 1024 / 1024),
sourceMb: round(sourceBytes / 1024 / 1024),
};
process.stdout.write(JSON.stringify(result));
process.exit(0);
}
function medianMeasurement(locales: readonly string[]): Measurement {
const samples = Array.from({ length: 3 }, () => runMeasurement(locales)).sort((left, right) => left.loadMs - right.loadMs);
return samples[1]!;
}
function runMeasurement(locales: readonly string[]): Measurement {
const result = spawnSync(
process.execPath,
["--expose-gc", "--import", "tsx", fileURLToPath(import.meta.url), `--measure=${locales.join(",")}`],
{ cwd: root, encoding: "utf8" }
);
if (result.status !== 0) throw new Error(result.stderr || `i18n catalog measurement exited with ${result.status}`);
return JSON.parse(result.stdout) as Measurement;
}
function round(value: number): number {
return Math.round(value * 100) / 100;
}
@@ -170,6 +170,34 @@ describe("i18n parity guard", () => {
expect(report).toContain("keys:\n - common.save");
});
test("fails when high-confidence German UI text leaks into the English catalog", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { leads: { status: { new: "Neu" } } });
await writeTranslations(root, "en", { leads: { status: { new: "Neu" } } });
const result = checkFixtureParity(root);
const report = formatI18nParityReport(result);
expect(result.ok).toBe(false);
expect(result.issues).toContainEqual({
type: "language-leak",
locale: "en",
namespace: "translations",
filePath: path.join(root, "apps", "web", "public", "locales", "en", "translations.json"),
findings: [{ key: "leads.status.new", words: ["Neu"] }],
});
expect(report).toContain("German UI text in English catalog [en/translations]");
expect(report).toContain("leads.status.new [Neu]");
});
test("does not flag lower-case technical identifiers in English examples", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { audit: { example: "z. B. kontakt.created" } });
await writeTranslations(root, "en", { audit: { example: "e.g. kontakt.created" } });
expect(checkFixtureParity(root).ok).toBe(true);
});
test("fails when an unconfigured locale directory is present", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { common: { save: "Speichern" } });
@@ -241,6 +269,153 @@ describe("i18n parity guard", () => {
expect(result.ok).toBe(true);
});
test("extracts semantic translation keys from view-model and registry fields", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", {
registry: {
breadcrumb: "Archiv",
empty: "Keine Einträge",
health: "Verbunden",
status: "Bereit",
},
});
await writeTranslations(root, "en", {
registry: {
breadcrumb: "Archive",
empty: "No entries",
health: "Connected",
status: "Ready",
},
});
await writeSource(
root,
"packages/view-models/src/registry.ts",
[
"export const vm = {",
' breadcrumbKey: "registry.breadcrumb",',
' emptyHeadlineKey: "registry.empty",',
' healthMessageKey: "registry.health",',
' statusLabelKey: "registry.status",',
"};",
].join("\n"),
);
expect(checkFixtureParity(root).ok).toBe(true);
});
test("fails for missing semantic registry keys that would otherwise render raw", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { common: { save: "Speichern" } });
await writeTranslations(root, "en", { common: { save: "Save" } });
await writeSource(root, "apps/web/app/services/registry.ts", 'export const result = { errorKey: "registry.errors.typo" };\n');
const result = checkFixtureParity(root);
expect(result.ok).toBe(false);
expect(result.issues).toContainEqual({
type: "missing-source-key",
key: "registry.errors.typo",
namespace: null,
fallback: "no-fallback",
files: ["apps/web/app/services/registry.ts"],
});
});
test("scans feature-specific view-model key fields beyond generic labels", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { common: { save: "Speichern" } });
await writeTranslations(root, "en", { common: { save: "Save" } });
await writeSource(
root,
"packages/view-models/src/feature.vm.ts",
[
"export const vm = {",
' anonymousHintKey: "feature.hints.anonymous",',
' candidatesEmptyKey: "feature.candidates.empty",',
' dropzoneHeadlineKey: "feature.dropzone.headline",',
' noMailboxKey: "feature.mailbox.missing",',
' usersLoadingKey: "feature.users.loading",',
"};",
].join("\n"),
);
const missingKeys = checkFixtureParity(root).issues
.filter((issue) => issue.type === "missing-source-key")
.map((issue) => issue.key)
.sort();
expect(missingKeys).toEqual([
"feature.candidates.empty",
"feature.dropzone.headline",
"feature.hints.anonymous",
"feature.mailbox.missing",
"feature.users.loading",
]);
});
test("does not treat stable protocol registry identifiers as translation keys", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { common: { save: "Speichern" } });
await writeTranslations(root, "en", { common: { save: "Save" } });
await writeSource(
root,
"apps/web/app/services/protocol-registry.ts",
[
'export const feature = { featureFlagKey: "tenant.subscription.active" };',
'export const trigger = { triggerKey: "lead.qualified" };',
'export const template = { templateKey: "shk.order.v1" };',
].join("\n"),
);
expect(checkFixtureParity(root).ok).toBe(true);
});
test("does not treat local variables named like translation fields as translation keys", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { common: { save: "Speichern" } });
await writeTranslations(root, "en", { common: { save: "Save" } });
await writeSource(root, "apps/web/app/services/registry.ts", 'export const value = () => { const translationKey = "configTranslationKeys"; return translationKey; };\n');
expect(checkFixtureParity(root).ok).toBe(true);
});
test("accepts dynamic translation key families backed by catalog entries", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { workflow: { status: { active: "Aktiv", paused: "Pausiert" } } });
await writeTranslations(root, "en", { workflow: { status: { active: "Active", paused: "Paused" } } });
await writeSource(root, "apps/web/app/components/Status.tsx", "export function Status({ t, status }) { return t(`workflow.status.${status}`); }\n");
expect(checkFixtureParity(root).ok).toBe(true);
});
test("fails for dynamic translation key families with a misspelled catalog prefix", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { forms: { editor: { operators: { equals: "Ist gleich" } } } });
await writeTranslations(root, "en", { forms: { editor: { operators: { equals: "Equals" } } } });
await writeSource(root, "apps/web/app/components/Operator.tsx", "export function Operator({ t, op }) { return t(`forms.builder.operators.${op}`); }\n");
const result = checkFixtureParity(root);
const report = formatI18nParityReport(result);
expect(result.ok).toBe(false);
expect(result.issues).toContainEqual({
type: "missing-source-key",
key: "forms.builder.operators.*",
namespace: null,
fallback: "no-fallback",
files: ["apps/web/app/components/Operator.tsx"],
});
expect(report).toContain("missing source translation key family (no-fallback): forms.builder.operators.*");
});
test("handles expressions with quoted fallbacks inside dynamic key families", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { dialog: { confirm: { leave: { title: "Verlassen?" } } } });
await writeTranslations(root, "en", { dialog: { confirm: { leave: { title: "Leave?" } } } });
await writeSource(root, "apps/web/app/components/Dialog.tsx", 'export function Dialog({ t, action }) { return t(`dialog.confirm.${action ?? "leave"}.title`); }\n');
expect(checkFixtureParity(root).ok).toBe(true);
});
test("fails when static package source keys are missing from the reference locale", async () => {
const { root } = await makeFixture();
await writeTranslations(root, "de", { common: { save: "Speichern" } });
@@ -3,7 +3,7 @@
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import path from "node:path";
import { defaultLocale, i18nNamespaces, supportedLocales } from "../packages/i18n/src/index.ts";
import { catalogReadyLocales, defaultLocale, i18nNamespaces } from "../packages/i18n/src/index.ts";
export type JsonObject = Record<string, unknown>;
@@ -62,6 +62,13 @@ export type LocaleParityIssue =
namespace: string;
filePath: string;
keys: string[];
}
| {
type: "language-leak";
locale: string;
namespace: string;
filePath: string;
findings: Array<{ key: string; words: string[] }>;
};
export type LocaleKeySummary = {
@@ -93,6 +100,7 @@ type SourceTranslationKey = {
key: string;
namespace: string | null;
fallback: MissingSourceKeyFallback;
family: boolean;
};
const DEFAULT_SOURCE_ROOTS = ["apps/web/app", "packages"] as const;
@@ -101,6 +109,183 @@ const TEST_FILE_PATTERN = /\.(test|spec)\.(ts|tsx)$/;
const IGNORED_SOURCE_DIRS = new Set(["node_modules", "dist", "build", "coverage", ".cache", "generated"]);
const DEFAULT_NAMESPACE = "translations";
// High-confidence German UI vocabulary that must not appear in the English
// catalog. The match is intentionally case-sensitive: German UI labels and
// sentence starts are capitalized, while lower-case technical identifiers such
// as `kontakt.created` can legitimately appear in examples and audit filters.
// Keep this an explicit vocabulary instead of guessing language from all text;
// product names and established English/German loanwords stay false-positive
// free.
const GERMAN_UI_WORDS = [
"Abbrechen",
"Aktualisieren",
"Alle",
"Anmelden",
"Archiviert",
"Aufgabe",
"Aufgaben",
"Ausgewählt",
"Auswahl",
"Bearbeiten",
"Benutzer",
"Bereit",
"Bestätigen",
"Bitte",
"Datei",
"Dateien",
"Diese",
"Dieser",
"Dieses",
"Einstellungen",
"Erstellen",
"Fehlgeschlagen",
"Firma",
"Hinzufügen",
"Kein",
"Keine",
"Kontakt",
"Kontakte",
"Konto",
"Löschen",
"Neu",
"Neue",
"Neuer",
"Neues",
"Öffnen",
"Projekt",
"Projekte",
"Prüfe",
"Schließen",
"Senden",
"Speichern",
"Stornieren",
"Suchen",
"Telefonnummer",
"Unbekannt",
"Verantwortlicher",
"Verfügbar",
"Verknüpfung",
"Wähle",
"Zurück",
"Zustellung",
] as const;
const GERMAN_UI_WORD_PATTERN = new RegExp(`(?<![\\p{L}\\p{N}_])(?:${GERMAN_UI_WORDS.join("|")})(?![\\p{L}\\p{N}_])`, "gu");
// View-models and server registries often pass translation keys to the UI
// instead of calling `t()` at the declaration site. Keep this list explicit:
// names such as `featureFlagKey`, `triggerKey` or `idempotencyKey` are stable
// protocol identifiers and must not be mistaken for translation keys.
const TRANSLATION_KEY_FIELDS = [
"actionErrorKey",
"actionKey",
"actionLabelKey",
"actorKindLabelKey",
"anonymousHintKey",
"badgeLabelKey",
"blockedReasonKey",
"bodyKey",
"breadcrumbKey",
"buttonKey",
"captionKey",
"candidatesEmptyKey",
"candidatesLoadingKey",
"commentEmptyKey",
"complaintMessageKey",
"composerPlaceholderKey",
"conflictHintKey",
"conflictsEmptyKey",
"ctaKey",
"descriptionKey",
"designBlockedByKey",
"detailKey",
"disabledReasonKey",
"discoverHeadlineKey",
"dmModeKey",
"dmReadOnlyKey",
"dropzoneBodyKey",
"dropzoneHeadlineKey",
"emptyBodyKey",
"emptyCandidatesKey",
"emptyDescriptionKey",
"emptyHeadlineKey",
"emptyItemsBodyKey",
"emptyItemsHeadlineKey",
"emptyKey",
"emptyMembersKey",
"emptyRepliesBodyKey",
"emptyRepliesHeadlineKey",
"emptyTitleKey",
"environmentNoticeKey",
"errorKey",
"errorMessageKey",
"eyebrowKey",
"expiryKey",
"failureI18nKey",
"failureReasonKey",
"feedbackKey",
"groupModeKey",
"groupsEmptyKey",
"healthMessageKey",
"headlineKey",
"heicNoticeKey",
"helpDescriptionKey",
"helpKey",
"helpTextKey",
"helpTitleKey",
"hintKey",
"i18nKey",
"infoKey",
"infoTooltipKey",
"kindLabelKey",
"labelKey",
"lastErrorMessageKey",
"loadOlderLabelKey",
"manualGuestsHeadlineKey",
"membersEmptyKey",
"membersLoadingKey",
"messageKey",
"nameKey",
"newMessagesLabelKey",
"noAllowedModesKey",
"noMailboxBodyKey",
"noMailboxHeadlineKey",
"noMailboxKey",
"noMatchesKey",
"noPackageHintKey",
"noResultsBodyKey",
"noResultsHeadlineKey",
"noResultsKey",
"noResultsTitleKey",
"notConfiguredKey",
"overageNoticeKey",
"paymentStatusLabelKey",
"placeholderKey",
"priorityLabelKey",
"projectManagedExternallyKey",
"reasonKey",
"roleLabelKey",
"searchPlaceholderKey",
"sectionLabelKey",
"sourceLabelKey",
"stateLabelKey",
"statusLabelKey",
"submitKey",
"submittedHintKey",
"subtitleKey",
"successKey",
"successMessageKey",
"summaryKey",
"textKey",
"titleKey",
"tombstoneKey",
"translationKey",
"typeLabelKey",
"unreadEmptyKey",
"usersEmptyKey",
"usersLoadingKey",
] as const;
const TRANSLATION_KEY_FIELD_PATTERN = TRANSLATION_KEY_FIELDS.join("|");
function isJsonObject(value: unknown): value is JsonObject {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
@@ -123,7 +308,7 @@ export function collectLeafKeys(value: unknown, prefix = ""): string[] {
export function checkI18nParity(options: I18nParityOptions = {}): I18nParityResult {
const cwd = options.cwd ?? process.cwd();
const localesRoot = options.localesRoot ?? resolveLocalesRoot(cwd);
const locales = [...(options.locales ?? supportedLocales)];
const locales = [...(options.locales ?? catalogReadyLocales)];
const namespaces = [...(options.namespaces ?? i18nNamespaces)];
const configuredReferenceLocale = options.referenceLocale ?? defaultLocale;
const referenceLocale = locales.includes(configuredReferenceLocale) ? configuredReferenceLocale : locales[0] ?? configuredReferenceLocale;
@@ -183,6 +368,10 @@ export function checkI18nParity(options: I18nParityOptions = {}): I18nParityResu
if (emptyTranslationKeys.length > 0) {
issues.push({ type: "empty-translation", locale, namespace, filePath, keys: emptyTranslationKeys });
}
if (locale === "en") {
const findings = collectGermanLanguageLeaks(parsed);
if (findings.length > 0) issues.push({ type: "language-leak", locale, namespace, filePath, findings });
}
localeKeySets.set(namespace, new Set(leafKeys));
summaries.push({ locale, namespace, filePath, keyCount: leafKeys.length });
}
@@ -224,7 +413,7 @@ export function checkI18nParity(options: I18nParityOptions = {}): I18nParityResu
for (const [sourceKey, files] of collectStaticSourceTranslationKeys(cwd, options.sourceRoots ?? DEFAULT_SOURCE_ROOTS, namespaces)) {
if (!hasSourceTranslationKey(referenceNamespaces, sourceKey, namespaces)) {
issues.push({ type: "missing-source-key", ...sourceKey, files });
issues.push({ type: "missing-source-key", key: sourceKey.key, namespace: sourceKey.namespace, fallback: sourceKey.fallback, files });
}
}
}
@@ -241,7 +430,7 @@ export function checkI18nParity(options: I18nParityOptions = {}): I18nParityResu
function hasSourceTranslationKey(referenceNamespaces: Map<string, Set<string>>, sourceKey: SourceTranslationKey, namespaces: readonly string[]) {
if (sourceKey.namespace) {
return hasTranslationKey(referenceNamespaces.get(sourceKey.namespace) ?? new Set<string>(), sourceKey.key);
return hasTranslationKey(referenceNamespaces.get(sourceKey.namespace) ?? new Set<string>(), sourceKey.key, sourceKey.family);
}
// Laufzeit-Semantik (i18next): der Namespace wird mit ":" getrennt (nsSeparator), NICHT mit ".".
@@ -250,10 +439,14 @@ function hasSourceTranslationKey(referenceNamespaces: Map<string, Set<string>>,
// Key deshalb nur als vollständigen Key in den (effektiven) Namespaces. KEIN "erstes Punkt-Segment
// als Namespace"-Fallback: der würde einen Punkt-statt-Doppelpunkt-Fehler (im UI ein nackter Key)
// stillschweigend als gültig durchwinken -- genau die Lücke, die den Theme-Settings-Bug verdeckte.
return namespaces.some((namespace) => hasTranslationKey(referenceNamespaces.get(namespace) ?? new Set<string>(), sourceKey.key));
return namespaces.some((namespace) => hasTranslationKey(referenceNamespaces.get(namespace) ?? new Set<string>(), sourceKey.key, sourceKey.family));
}
function hasTranslationKey(keys: Set<string>, key: string) {
function hasTranslationKey(keys: Set<string>, key: string, family = false) {
if (family) {
const pattern = new RegExp(`^${escapeRegExp(key).replaceAll("\\*", ".+")}$`, "u");
return [...keys].some((candidate) => pattern.test(candidate));
}
return keys.has(key) || keys.has(`${key}_one`) || keys.has(`${key}_other`);
}
@@ -267,6 +460,18 @@ function collectEmptyTranslationKeys(value: unknown, prefix = ""): string[] {
.flatMap((key) => collectEmptyTranslationKeys(value[key], prefix ? `${prefix}.${key}` : key));
}
function collectGermanLanguageLeaks(value: unknown, prefix = ""): Array<{ key: string; words: string[] }> {
if (!isJsonObject(value)) {
if (typeof value !== "string" || !prefix) return [];
const words = [...new Set([...value.matchAll(GERMAN_UI_WORD_PATTERN)].map((match) => match[0]))];
return words.length > 0 ? [{ key: prefix, words }] : [];
}
return Object.keys(value)
.sort((left, right) => left.localeCompare(right))
.flatMap((key) => collectGermanLanguageLeaks(value[key], prefix ? `${prefix}.${key}` : key));
}
function collectStaticSourceTranslationKeys(cwd: string, sourceRoots: readonly string[], namespaces: readonly string[]) {
const keys = new Map<string, { sourceKey: SourceTranslationKey; files: string[] }>();
@@ -278,7 +483,7 @@ function collectStaticSourceTranslationKeys(cwd: string, sourceRoots: readonly s
const relativePath = slash(path.relative(cwd, filePath));
const source = readFileSync(filePath, "utf8");
for (const sourceKey of extractStaticTranslationKeys(source, namespaces)) {
const id = `${sourceKey.namespace ?? "*"}:${sourceKey.key}:${sourceKey.fallback}`;
const id = `${sourceKey.namespace ?? "*"}:${sourceKey.key}:${sourceKey.fallback}:${sourceKey.family ? "family" : "exact"}`;
const entry = keys.get(id) ?? { sourceKey, files: [] };
entry.files.push(relativePath);
keys.set(id, entry);
@@ -317,8 +522,15 @@ function extractStaticTranslationKeys(source: string, namespaces: readonly strin
if (rawKey.endsWith(".")) return;
const parsed = parseTranslationKey(rawKey, namespace, namespaceSet);
const key = applyKeyPrefix(parsed.key, rawKey, keyPrefix);
const sourceKey = { key, namespace: parsed.namespace, fallback };
keys.set(`${sourceKey.namespace ?? "*"}:${sourceKey.key}:${sourceKey.fallback}`, sourceKey);
const sourceKey = { key, namespace: parsed.namespace, fallback, family: false };
keys.set(`${sourceKey.namespace ?? "*"}:${sourceKey.key}:${sourceKey.fallback}:exact`, sourceKey);
};
const addFamily = (rawPattern: string, fallback: MissingSourceKeyFallback, namespace: string | null = inferredNamespace, keyPrefix: string | null = inferredKeyPrefix) => {
const parsed = parseTranslationKey(rawPattern, namespace, namespaceSet);
const key = applyKeyPrefix(parsed.key, rawPattern, keyPrefix);
const sourceKey = { key, namespace: parsed.namespace, fallback, family: true };
keys.set(`${sourceKey.namespace ?? "*"}:${sourceKey.key}:${sourceKey.fallback}:family`, sourceKey);
};
for (const match of source.matchAll(/\bt\(\s*["']([A-Za-z0-9_.:-]+)["']([^)]*)\)/g)) {
@@ -328,6 +540,14 @@ function extractStaticTranslationKeys(source: string, namespaces: readonly strin
const keyPrefix = extractOptionKeyPrefix(tail) ?? inferredKeyPrefix;
addKey(rawKey, hasDefaultValueFallback(tail) || localFallbackKeys.has(rawKey) ? "fallback" : "no-fallback", namespace, keyPrefix);
}
for (const match of source.matchAll(/\bt\(\s*`((?:\\.|[^`])*(?:\$\{)(?:\\.|[^`])*)`([^)]*)\)/g)) {
const rawPattern = dynamicTemplateToKeyFamily(match[1]);
if (!rawPattern) continue;
const tail = match[2] ?? "";
const namespace = extractOptionNamespace(tail, namespaceSet) ?? inferredNamespace;
const keyPrefix = extractOptionKeyPrefix(tail) ?? inferredKeyPrefix;
addFamily(rawPattern, hasDefaultValueFallback(tail) ? "fallback" : "no-fallback", namespace, keyPrefix);
}
for (const match of source.matchAll(/\bt\(\s*\(?\s*\$[A-Za-z0-9_]*\s*\)?\s*=>\s*\$[A-Za-z0-9_]*((?:\.[A-Za-z_$][\w$]*)+)([^)]*)\)/g)) {
const rawKey = match[1].slice(1);
const tail = match[2] ?? "";
@@ -338,19 +558,77 @@ function extractStaticTranslationKeys(source: string, namespaces: readonly strin
const index = match.index ?? 0;
addKey(match[1], hasNearbyLiteralFallback(source, index) ? "fallback" : "no-fallback", extractNearbyNamespace(source, index, namespaceSet), extractNearbyKeyPrefix(source, index));
}
for (const match of source.matchAll(/\b(?:labelKey|titleKey|descriptionKey|messageKey)\s*:\s*["']([A-Za-z0-9_.:-]+)["']/g)) {
for (const match of source.matchAll(new RegExp(`\\b(?:${TRANSLATION_KEY_FIELD_PATTERN})\\s*:\\s*["']([A-Za-z0-9_.:-]+)["']`, "g"))) {
addKey(match[1], hasNearbyLiteralFallback(source, match.index ?? 0) ? "fallback" : "no-fallback", null);
}
for (const match of source.matchAll(/\bi18nKey\s*=\s*["']([A-Za-z0-9_.:-]+)["']/g)) {
const index = match.index ?? 0;
addKey(match[1], "no-fallback", extractNearbyNamespace(source, index, namespaceSet), extractNearbyKeyPrefix(source, index));
}
for (const match of source.matchAll(/\b(?:labelKey|titleKey|descriptionKey|messageKey)\s*=\s*["']([A-Za-z0-9_.:-]+)["']/g)) {
for (const match of source.matchAll(new RegExp(`\\b(?:${TRANSLATION_KEY_FIELD_PATTERN})[ \\t]*=[ \\t]*["']([A-Za-z0-9_.:-]+)["']`, "g"))) {
const linePrefix = source.slice(source.lastIndexOf("\n", match.index ?? 0) + 1, match.index ?? 0);
if (/\b(?:const|let|var)\s+$/u.test(linePrefix)) continue;
addKey(match[1], "no-fallback", null);
}
return [...keys.values()].sort((left, right) => `${left.namespace ?? "*"}:${left.key}`.localeCompare(`${right.namespace ?? "*"}:${right.key}`));
}
function dynamicTemplateToKeyFamily(template: string): string | null {
let pattern = "";
let cursor = 0;
let interpolationCount = 0;
while (cursor < template.length) {
const interpolationStart = template.indexOf("${", cursor);
if (interpolationStart < 0) {
pattern += template.slice(cursor);
break;
}
pattern += template.slice(cursor, interpolationStart);
const interpolationEnd = findInterpolationEnd(template, interpolationStart + 2);
if (interpolationEnd < 0) return null;
pattern += "*";
interpolationCount += 1;
cursor = interpolationEnd + 1;
}
const literalPart = pattern.replaceAll("*", "").replaceAll(/[.:-]/g, "");
return interpolationCount > 0 && /[A-Za-z0-9]/u.test(literalPart) ? pattern.replaceAll(/\*+/g, "*") : null;
}
function findInterpolationEnd(template: string, expressionStart: number): number {
let depth = 1;
let quote: "\"" | "'" | null = null;
let escaped = false;
for (let index = expressionStart; index < template.length; index += 1) {
const char = template[index];
if (quote) {
if (escaped) {
escaped = false;
} else if (char === "\\") {
escaped = true;
} else if (char === quote) {
quote = null;
}
continue;
}
if (char === "\"" || char === "'") {
quote = char;
continue;
}
if (char === "{") depth += 1;
if (char === "}") depth -= 1;
if (depth === 0) return index;
}
return -1;
}
function escapeRegExp(value: string) {
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
}
function parseTranslationKey(rawKey: string, namespace: string | null, namespaces: Set<string>) {
const separatorIndex = rawKey.indexOf(":");
if (separatorIndex > 0) {
@@ -478,10 +756,17 @@ function formatIssue(issue: LocaleParityIssue): string {
if (issue.type === "empty-translation") {
return [`- empty translation values [${issue.locale}/${issue.namespace}]: ${issue.filePath}`, formatKeyList("keys", issue.keys)].join("\n");
}
if (issue.type === "language-leak") {
return [
`- German UI text in English catalog [${issue.locale}/${issue.namespace}]: ${issue.filePath}`,
...issue.findings.map((finding) => ` - ${finding.key} [${finding.words.join(", ")}]`),
].join("\n");
}
if (issue.type === "unexpected-locale-dir") return `- unexpected locale directory [${issue.locale}]: ${issue.directoryPath}`;
if (issue.type === "missing-source-key") {
const namespace = issue.namespace ? `${issue.namespace}:` : "";
return [`- missing source translation key (${issue.fallback}): ${namespace}${issue.key}`, formatKeyList("files", issue.files)].join("\n");
const kind = issue.key.includes("*") ? "key family" : "key";
return [`- missing source translation ${kind} (${issue.fallback}): ${namespace}${issue.key}`, formatKeyList("files", issue.files)].join("\n");
}
return [
Loaded 100 of 5955 files, more files were not shown because too many files have changed in this diff. Show more