Reorganize repo structure and standards references

This commit is contained in:
david committed 2026-06-29 05:03:42 +02:00
1 parent 3cb93a81be
commit be2054274d
5885 files changed
+2588 -195

No files matched your search

@@ -0,0 +1,80 @@
import { describe, expect, it } from "vitest";
import { anonymizeIp, buildUserPseudonymizationUpdate, pseudonymize } from "./pseudonymize.js";
describe("pseudonymize()", () => {
it("is deterministic for the same userId", () => {
const a = pseudonymize("user-1");
const b = pseudonymize("user-1");
expect(a).toEqual(b);
});
it("produces distinct pseudonyms for distinct userIds", () => {
const a = pseudonymize("user-1");
const b = pseudonymize("user-2");
expect(a.pseudoEmail).not.toBe(b.pseudoEmail);
expect(a.pseudoId).not.toBe(b.pseudoId);
});
it("emits a synthetic email under the .invalid TLD by default", () => {
const result = pseudonymize("user-1");
expect(result.pseudoEmail).toMatch(/^deleted-user-[a-f0-9]{16}@pseudonymized\.invalid$/);
});
it("strips PII fields (phone, avatar) to null", () => {
const result = pseudonymize("user-1");
expect(result.pseudoPhone).toBeNull();
expect(result.pseudoAvatar).toBeNull();
});
it("changes the hash when a pepper is supplied", () => {
const plain = pseudonymize("user-1");
const peppered = pseudonymize("user-1", { pepper: "deployment-X" });
expect(plain.pseudoEmail).not.toBe(peppered.pseudoEmail);
});
it("respects a custom email domain", () => {
const result = pseudonymize("user-1", { emailDomain: "anon.example" });
expect(result.pseudoEmail).toMatch(/^deleted-user-[a-f0-9]{16}@anon\.example$/);
});
it("rejects an empty userId", () => {
expect(() => pseudonymize("")).toThrow(/non-empty string/);
});
});
describe("anonymizeIp()", () => {
it("masks the last octet of an IPv4 address", () => {
expect(anonymizeIp("203.0.113.42")).toBe("203.0.113.0");
});
it("returns null for invalid IPv4 (octet out of range)", () => {
expect(anonymizeIp("999.0.0.1")).toBeNull();
});
it("masks the interface identifier of an IPv6 address (/48)", () => {
expect(anonymizeIp("2001:0db8:85a3:0000:0000:8a2e:0370:7334")).toBe("2001:0db8:85a3:::::0");
});
it("returns null for empty or non-string inputs", () => {
expect(anonymizeIp("")).toBeNull();
expect(anonymizeIp(null)).toBeNull();
expect(anonymizeIp(undefined)).toBeNull();
});
});
describe("buildUserPseudonymizationUpdate()", () => {
it("produces a prisma User.update payload with the terminal flags set", () => {
const update = buildUserPseudonymizationUpdate("user-1");
expect(update.pseudonymized).toBe(true);
expect(update.pseudonymizedAt).toBeInstanceOf(Date);
expect(update.pendingDeletion).toBe(false);
expect(update.scheduledDeletionAt).toBeNull();
expect(update.email).toMatch(/^deleted-user-[a-f0-9]{16}@pseudonymized\.invalid$/);
expect(update.firstName).toBe("Anonymized");
expect(update.lastName).toMatch(/^User-[a-f0-9]{8}$/);
expect(update.passwordHash).toMatch(/^\$2a\$10\$pseudonymized-[a-f0-9]{12}$/);
expect(update.avatar).toBeNull();
expect(update.phone).toBeNull();
});
});
@@ -0,0 +1,142 @@
import { createHash } from "node:crypto";
/**
* Phase 10 Task #68 — DSGVO deterministic pseudonymization helper.
*
* Given a `userId`, derives a deterministic pseudonym set that can be
* substituted into retention-bound rows (AuditEvents, support tickets,
* etc.) without losing referential coherence — the same userId always
* maps to the same pseudonym, so historical reports keep grouping the
* user's activity together while the original PII is gone.
*
* Determinism property:
* pseudonymize("u1").pseudoEmail === pseudonymize("u1").pseudoEmail
*
* No external secret is mixed in: re-identification is intentionally
* *not* possible from the pseudonym alone — that is the whole point of
* pseudonymization under Art. 4(5) DSGVO. The optional `pepper` argument
* exists for cases where the operator wants per-deployment salting; a
* caller that omits it gets the stable global hash.
*/
const PSEUDO_PREFIX = "deleted-user";
export interface PseudonymizedIdentity {
/** Stable pseudonym hash (first 16 hex chars of SHA-256(userId|pepper)). */
pseudoId: string;
/** Replacement email — deterministic and obviously synthetic. */
pseudoEmail: string;
/** Replacement first name — fixed string, no PII. */
pseudoFirstName: string;
/** Replacement last name — short hash suffix to keep rows distinguishable. */
pseudoLastName: string;
/** Replacement phone — empty by design (Art. 17). */
pseudoPhone: null;
/** Replacement avatar — empty by design. */
pseudoAvatar: null;
}
export interface PseudonymizeOptions {
/**
* Optional per-deployment salt. When set the hash changes across
* deployments which is desirable for tenant isolation, but for the
* test-fixture scenarios we expose deterministic output without it.
*/
pepper?: string;
/** Override domain for the synthetic email (default: `pseudonymized.invalid`). */
emailDomain?: string;
}
const DEFAULT_EMAIL_DOMAIN = "pseudonymized.invalid";
/**
* Compute a deterministic pseudonym for `userId`. Caller supplies the
* userId; everything else is derived.
*/
export function pseudonymize(userId: string, options: PseudonymizeOptions = {}): PseudonymizedIdentity {
if (typeof userId !== "string" || userId.length === 0) {
throw new Error("pseudonymize(): userId must be a non-empty string");
}
const pepper = options.pepper ?? "";
const digest = createHash("sha256").update(userId).update(pepper).digest("hex");
const pseudoId = digest.slice(0, 16);
const domain = (options.emailDomain ?? DEFAULT_EMAIL_DOMAIN).replace(/^@/, "");
return {
pseudoId,
pseudoEmail: `${PSEUDO_PREFIX}-${pseudoId}@${domain}`,
pseudoFirstName: "Anonymized",
pseudoLastName: `User-${pseudoId.slice(0, 8)}`,
pseudoPhone: null,
pseudoAvatar: null,
};
}
/**
* IP-anonymisation helper used when pseudonymising AuditEvent.actorIp.
* Strips the last octet for IPv4 (/24) and the last 80 bits for IPv6
* (/48 standard for GeoIP-safe anonymisation per BSI / ENISA guidance).
*
* Returns `null` when the input is not a recognisable IP string so the
* caller can store NULL instead of a malformed value.
*/
export function anonymizeIp(input: string | null | undefined): string | null {
if (typeof input !== "string") return null;
const trimmed = input.trim();
if (!trimmed) return null;
// IPv4: 4 dot-separated octets, each 0-255.
const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.\d{1,3}$/.exec(trimmed);
if (ipv4) {
const [, a, b, c] = ipv4;
if ([a, b, c].every((octet) => Number(octet) >= 0 && Number(octet) <= 255)) {
return `${a}.${b}.${c}.0`;
}
return null;
}
// IPv6 — keep the first three hextets (/48) which preserves the
// routing prefix but drops the interface identifier and the subnet.
// Accept shorthand `::` notation by expanding via `URL`.
if (trimmed.includes(":")) {
const parts = trimmed.split(":");
if (parts.length < 2) return null;
return [parts[0] ?? "0", parts[1] ?? "0", parts[2] ?? "0", "", "", "", "", "0"].join(":");
}
return null;
}
/**
* Build the prisma `User.update` payload that flips the row into the
* pseudonymized terminal state. Centralised here so callers (worker job,
* admin override, CLI) emit the same field set.
*/
export function buildUserPseudonymizationUpdate(userId: string, options: PseudonymizeOptions = {}): {
email: string;
firstName: string;
lastName: string;
avatar: string | null;
phone: string | null;
passwordHash: string;
pseudonymized: true;
pseudonymizedAt: Date;
pendingDeletion: false;
scheduledDeletionAt: null;
} {
const id = pseudonymize(userId, options);
return {
email: id.pseudoEmail,
firstName: id.pseudoFirstName,
lastName: id.pseudoLastName,
avatar: id.pseudoAvatar,
phone: id.pseudoPhone,
// Replace the password with a non-recoverable bcrypt-shaped placeholder.
// The terminal `$2a$` prefix keeps callers that probe the hash format
// happy without ever resolving to a real password.
passwordHash: `$2a$10$pseudonymized-${id.pseudoId.slice(0, 12)}`,
pseudonymized: true,
pseudonymizedAt: new Date(),
pendingDeletion: false,
scheduledDeletionAt: null,
};
}
@@ -0,0 +1,82 @@
import { readFileSync, readdirSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { describe, expect, it } from "vitest";
import { USER_FK_MAP, USER_FK_MAP_BY_STRATEGY, findUserFkEntry } from "./user-fk-map.js";
const __dirname = dirname(fileURLToPath(import.meta.url));
const SCHEMA_DIR = resolve(__dirname, "../../../../prisma/schema");
type GrepEntry = { model: string; column: string; source: string };
/**
* Re-implements the grep that informs the static USER_FK_MAP. The test
* fails whenever a new prisma model adds a `fields: [xxx], references:
* [id]` reference to `User` without updating the map.
*/
function grepUserFks(): GrepEntry[] {
const files = readdirSync(SCHEMA_DIR).filter((f) => f.endsWith(".prisma"));
const out: GrepEntry[] = [];
for (const file of files) {
const text = readFileSync(join(SCHEMA_DIR, file), "utf8");
let currentModel: string | null = null;
for (const line of text.split("\n")) {
const modelMatch = /^model\s+(\w+)\s*\{/.exec(line);
if (modelMatch) {
currentModel = modelMatch[1] ?? null;
continue;
}
if (!line.includes("references: [id]")) continue;
if (!/\bUser\??\s/.test(line)) continue;
const fieldsMatch = /fields:\s*\[(\w+)\]/.exec(line);
if (!fieldsMatch || !currentModel) continue;
out.push({ model: currentModel, column: fieldsMatch[1] ?? "", source: file });
}
}
return out;
}
describe("USER_FK_MAP", () => {
it("covers every User foreign-key relation declared in prisma/schema", () => {
const greppedEntries = grepUserFks();
expect(greppedEntries.length).toBeGreaterThan(0);
for (const entry of greppedEntries) {
const match = findUserFkEntry(entry.model, entry.column);
expect(match, `missing user-fk-map entry for ${entry.model}.${entry.column}`).toBeDefined();
expect(match!.source).toBe(entry.source);
}
});
it("uses only the three documented strategies", () => {
const valid = new Set(["hard-delete", "pseudonymize", "retain-tombstone"]);
for (const entry of USER_FK_MAP) {
expect(valid.has(entry.strategy)).toBe(true);
}
});
it("partitions every entry into exactly one strategy bucket", () => {
const total =
USER_FK_MAP_BY_STRATEGY.hardDelete.length +
USER_FK_MAP_BY_STRATEGY.pseudonymize.length +
USER_FK_MAP_BY_STRATEGY.retainTombstone.length;
expect(total).toBe(USER_FK_MAP.length);
});
it("retains AuditEvent.actorId via pseudonymization (SOC2-CC6.1 audit-trail integrity)", () => {
const auditEntry = findUserFkEntry("AuditEvent", "actorId");
expect(auditEntry).toBeDefined();
expect(auditEntry!.strategy).toBe("pseudonymize");
});
it("entries are alphabetically sorted by model+column for review-friendly diffs", () => {
const sorted = [...USER_FK_MAP].slice().sort((a, b) => {
const byModel = a.model.localeCompare(b.model);
return byModel !== 0 ? byModel : a.column.localeCompare(b.column);
});
// Order-preserved equality check — same length, same elements, same order.
expect(USER_FK_MAP.map((e) => `${e.model}.${e.column}`)).toEqual(sorted.map((e) => `${e.model}.${e.column}`));
});
});
@@ -0,0 +1,125 @@
/**
* Phase 10 Task #68 — DSGVO bulk-ops user-FK map.
*
* Enumerates every Prisma model that holds a foreign key (or a logical
* reference) to `User.id`. Each entry declares an explicit cascade
* strategy used by the deletion pipeline (`dsgvo-deletion.ts`) and the
* export pipeline (`dsgvo-export.ts`).
*
* Strategies:
*
* • `hard-delete` — delete rows when the user is deleted. Used
* for join tables, ephemeral data and rows
* with no retention requirement.
*
* • `pseudonymize` — keep the row but null/replace the user FK
* with the deterministic pseudonym. Used for
* retention-bound rows such as AuditEvents,
* help-desk tickets and historical analytics
* where regulatory or business intent
* requires the record to survive deletion.
*
* • `retain-tombstone` — keep the row but set the FK to NULL
* (existing schema-level `onDelete: SetNull`
* handles the column update). Used when the
* row outlives the user but no audit reference
* is required.
*
* The companion test (`user-fk-map.test.ts`) asserts that the grep over
* `prisma/schema/*.prisma` finds exactly the relations enumerated here.
* If a future migration adds a new User-FK without updating this map,
* the test fails and the cascade silently leaking PII is blocked at
* CI time.
*/
export type DsgvoCascadeStrategy = "hard-delete" | "pseudonymize" | "retain-tombstone";
export interface UserFkMapEntry {
/** Prisma model name (matches `model X { ... }`). */
model: string;
/** Foreign-key column on `model` that references `User.id`. */
column: string;
/** Cascade strategy applied by the deletion worker. */
strategy: DsgvoCascadeStrategy;
/** Schema source file (debug/audit aid). */
source: string;
/** Whether this table is included in the personal-data export bundle. */
includeInExport: boolean;
}
/**
* Sorted alphabetically by `model` + `column` so diffs against future
* additions stay reviewable.
*/
export const USER_FK_MAP: ReadonlyArray<UserFkMapEntry> = Object.freeze([
{ model: "AdminUser", column: "userId", strategy: "hard-delete", source: "accounts.prisma", includeInExport: true },
{ model: "AnalyticsUniqueVisitor", column: "userId", strategy: "pseudonymize", source: "analytics.prisma", includeInExport: false },
{ model: "ApiKey", column: "createdByUserId", strategy: "hard-delete", source: "core.prisma", includeInExport: true },
{ model: "App", column: "installedByUserId", strategy: "retain-tombstone", source: "appsEngine.prisma", includeInExport: true },
{ model: "AppSyncRun", column: "createdByUserId", strategy: "retain-tombstone", source: "appsEngine.prisma", includeInExport: false },
// AuditEvent has no FK relation in the schema (actorId is a free
// string column) — we list it here as a *logical* reference. The
// pseudonymization strategy is mandatory: SOC2-CC6.1 requires the
// audit trail to survive user deletion, only its PII fields are
// rewritten.
{ model: "AuditEvent", column: "actorId", strategy: "pseudonymize", source: "core.prisma", includeInExport: true },
{ model: "Credit", column: "userId", strategy: "pseudonymize", source: "subscriptions.prisma", includeInExport: true },
{ model: "DeviceToken", column: "userId", strategy: "hard-delete", source: "notifications.prisma", includeInExport: false },
{ model: "EmailRead", column: "userId", strategy: "hard-delete", source: "email.prisma", includeInExport: true },
{ model: "EntityView", column: "createdByUserId", strategy: "hard-delete", source: "entityBuilder.prisma", includeInExport: true },
{ model: "EntityView", column: "userId", strategy: "hard-delete", source: "entityBuilder.prisma", includeInExport: true },
{ model: "Event", column: "userId", strategy: "pseudonymize", source: "core.prisma", includeInExport: true },
{ model: "Feedback", column: "userId", strategy: "pseudonymize", source: "helpDesk.prisma", includeInExport: true },
{ model: "FormulaLog", column: "userId", strategy: "pseudonymize", source: "entityBuilder.prisma", includeInExport: false },
{ model: "Group", column: "createdByUserId", strategy: "retain-tombstone", source: "permissions.prisma", includeInExport: true },
{ model: "GroupUser", column: "userId", strategy: "hard-delete", source: "permissions.prisma", includeInExport: true },
{ model: "ImpersonationAudit", column: "actorUserId", strategy: "pseudonymize", source: "accounts.prisma", includeInExport: true },
{ model: "ImpersonationAudit", column: "targetUserId", strategy: "pseudonymize", source: "accounts.prisma", includeInExport: true },
{ model: "KnowledgeBaseArticle", column: "createdByUserId", strategy: "pseudonymize", source: "knowledgeBase.prisma", includeInExport: true },
{ model: "Log", column: "userId", strategy: "pseudonymize", source: "core.prisma", includeInExport: true },
{ model: "MagicLinkToken", column: "userId", strategy: "hard-delete", source: "accounts.prisma", includeInExport: false },
{ model: "MetricLog", column: "userId", strategy: "pseudonymize", source: "core.prisma", includeInExport: false },
{ model: "NotificationDelivery", column: "userId", strategy: "pseudonymize", source: "notifications.prisma", includeInExport: true },
{ model: "OnboardingSession", column: "userId", strategy: "hard-delete", source: "onboarding.prisma", includeInExport: true },
{ model: "Portal", column: "createdByUserId", strategy: "retain-tombstone", source: "portals.prisma", includeInExport: true },
{ model: "Row", column: "createdByUserId", strategy: "pseudonymize", source: "entityBuilder.prisma", includeInExport: true },
{ model: "RowComment", column: "createdByUserId", strategy: "pseudonymize", source: "entityBuilder.prisma", includeInExport: true },
{ model: "RowCommentReaction", column: "createdByUserId", strategy: "hard-delete", source: "entityBuilder.prisma", includeInExport: true },
{ model: "RowPermission", column: "userId", strategy: "hard-delete", source: "entityBuilder.prisma", includeInExport: true },
{ model: "RowTask", column: "assignedToUserId", strategy: "retain-tombstone", source: "entityBuilder.prisma", includeInExport: true },
{ model: "RowTask", column: "completedByUserId", strategy: "retain-tombstone", source: "entityBuilder.prisma", includeInExport: true },
{ model: "RowTask", column: "createdByUserId", strategy: "pseudonymize", source: "entityBuilder.prisma", includeInExport: true },
{ model: "Site", column: "createdByUserId", strategy: "retain-tombstone", source: "sites.prisma", includeInExport: true },
{ model: "SupportTicket", column: "userId", strategy: "pseudonymize", source: "helpDesk.prisma", includeInExport: true },
{ model: "TenantIpAddress", column: "userId", strategy: "hard-delete", source: "accounts.prisma", includeInExport: true },
{ model: "TenantUser", column: "userId", strategy: "hard-delete", source: "accounts.prisma", includeInExport: true },
{ model: "TenantUserInvitation", column: "acceptedByUserId", strategy: "retain-tombstone", source: "accounts.prisma", includeInExport: true },
{ model: "TenantUserInvitation", column: "createdUserId", strategy: "retain-tombstone", source: "accounts.prisma", includeInExport: true },
{ model: "TenantUserInvitation", column: "fromUserId", strategy: "retain-tombstone", source: "accounts.prisma", includeInExport: true },
{ model: "TenantUserInvitation", column: "revokedByUserId", strategy: "retain-tombstone", source: "accounts.prisma", includeInExport: true },
// Auth session/device artifacts (R-P2b). They already declare
// `onDelete: Cascade`, so hard-delete is the matching DSGVO strategy; not user
// content, so excluded from export.
{ model: "TrustedDevice", column: "userId", strategy: "hard-delete", source: "auth.prisma", includeInExport: false },
{ model: "UserNotificationPreference", column: "userId", strategy: "hard-delete", source: "notifications.prisma", includeInExport: true },
{ model: "UserRole", column: "userId", strategy: "hard-delete", source: "permissions.prisma", includeInExport: true },
{ model: "UserSession", column: "userId", strategy: "hard-delete", source: "auth.prisma", includeInExport: false },
{ model: "Workflow", column: "createdByUserId", strategy: "retain-tombstone", source: "workflows.prisma", includeInExport: true },
{ model: "WorkflowCredential", column: "userId", strategy: "retain-tombstone", source: "workflows.prisma", includeInExport: true },
{ model: "WorkflowExecution", column: "createdByUserId", strategy: "pseudonymize", source: "workflows.prisma", includeInExport: false },
{ model: "WorkflowVariable", column: "userId", strategy: "retain-tombstone", source: "workflows.prisma", includeInExport: true },
]);
export const USER_FK_MAP_BY_STRATEGY = Object.freeze({
hardDelete: USER_FK_MAP.filter((e) => e.strategy === "hard-delete"),
pseudonymize: USER_FK_MAP.filter((e) => e.strategy === "pseudonymize"),
retainTombstone: USER_FK_MAP.filter((e) => e.strategy === "retain-tombstone"),
});
export function getUserFkEntriesForExport(): readonly UserFkMapEntry[] {
return USER_FK_MAP.filter((entry) => entry.includeInExport);
}
export function findUserFkEntry(model: string, column: string): UserFkMapEntry | undefined {
return USER_FK_MAP.find((entry) => entry.model === model && entry.column === column);
}