/** * PII anonymization engine for tenant snapshots. * * Three profiles are supported: * - `full-anonymized` default; replaces every known PII field with a * synthetic value derived from a per-snapshot salt. * - `minimal-anonymized` keeps display names but scrubs strictly-regulated * PII (email, phone, address, IP, payment ids). * - `none` raw passthrough; gated behind a super-admin flag at * the snapshot-command layer (NEVER use without an * explicit audit trail — see docs/ops/tenant-snapshot.md). * * Determinism: every anonymizer is seeded by `sha256(salt + originalValue)`. * The same original value within the same snapshot always maps to the same * anonymized value, preserving foreign-key integrity (e.g. an email used as * a join key in another row stays consistent across rows). */ import { createHash } from "node:crypto"; export type FieldStrategy = | "keep" | "null" | "email" | "first-name" | "last-name" | "full-name" | "phone" | "address-street" | "address-city" | "address-country" | "zip-code" | "ip-address" | "billing-customer-id" | "billing-subscription-id" | "payment-method-id" | "payment-id-generic" | "url-rewrite" | "avatar-url" | "redact" | "sha256-prefix" | "sha256-hex" | "truncate-32"; export type ProfileName = "full-anonymized" | "minimal-anonymized" | "none"; /** Map from model name → { field → strategy }. Fields not listed are passed through unchanged. */ export type AnonymizationProfile = Readonly>>>; /** * The full-anonymized profile. This is the source-of-truth PII map; the * minimal profile is derived from it by relaxing display-name strategies. */ export const FULL_ANONYMIZED_PROFILE: AnonymizationProfile = { TenantUserInvitation: { email: "email", firstName: "first-name", lastName: "last-name", }, TenantIpAddress: { ip: "ip-address", fromUrl: "url-rewrite", }, WorkspaceAuthProvider: { clientId: "redact", certificateFingerprint: "redact", issuer: "url-rewrite", authorizationUrl: "url-rewrite", tokenUrl: "url-rewrite", jwksUrl: "url-rewrite", ssoUrl: "url-rewrite", }, ImpersonationAudit: { reason: "redact", metadata: "redact", }, ApiKey: { name: "sha256-prefix", description: "redact", hash: "sha256-prefix", prefix: "sha256-prefix", }, ApiKeyLog: { ip: "ip-address", params: "redact", }, AuditEvent: { actorIp: "ip-address", metadata: "redact", }, Event: { // Schema field is `data` (free-form string used by callers for any // event-shaped payload). Catches plaintext emails and identifiers // that callers stuff in for debugging. data: "redact", description: "redact", }, EventWebhookAttempt: { endpoint: "url-rewrite", message: "redact", body: "redact", }, Log: { error: "redact", url: "url-rewrite", }, Campaign: { fromEmail: "email", fromName: "full-name", replyToEmail: "email", subject: "redact", htmlBody: "redact", textBody: "redact", }, EmailSender: { fromEmail: "email", fromName: "full-name", apiKey: "redact", domain: "url-rewrite", }, TenantInboundAddress: { address: "email", forwardTo: "email", }, Email: { messageId: "sha256-prefix", subject: "redact", fromEmail: "email", fromName: "full-name", toEmail: "email", toName: "full-name", textBody: "redact", htmlBody: "redact", }, EmailCc: { toEmail: "email", toName: "full-name", }, EmailAttachment: { name: "sha256-prefix", content: "redact", publicUrl: "url-rewrite", }, OutboundEmail: { email: "email", fromEmail: "email", fromName: "full-name", toEmail: "email", replyToEmail: "email", subject: "redact", htmlBody: "redact", textBody: "redact", }, OutboundEmailClick: { link: "url-rewrite", }, EmailSequenceStepDelivery: { providerMessageId: "sha256-prefix", errorMessage: "redact", }, TenantSubscription: { billingProviderCustomerId: "billing-customer-id", billingProviderSubscriptionId: "billing-subscription-id", }, TenantProductConfiguration: { paymentProviderAccountId: "payment-id-generic", }, Credit: { providerInvoiceId: "payment-id-generic", }, WorkflowCredential: { secret: "redact", apiKey: "redact", accessToken: "redact", refreshToken: "redact", value: "redact", }, Workflow: { webhookSecret: "redact", }, WorkflowExecution: { contextJson: "redact", errorMessage: "redact", input: "redact", output: "redact", error: "redact", }, WorkflowBlock: { description: "redact", input: "redact", }, WorkflowBlockCondition: { value: "redact", }, WorkflowBlockToBlock: { condition: "redact", }, WorkflowInputExample: { input: "redact", }, WorkflowBlockExecution: { input: "redact", output: "redact", error: "redact", }, DataConnection: { accessToken: "redact", refreshToken: "redact", secret: "redact", config: "redact", }, App: { secret: "redact", }, ImportJob: { inputUrl: "url-rewrite", errorMessage: "redact", }, ExportJob: { resultUrl: "url-rewrite", errorMessage: "redact", }, Feedback: { message: "redact", }, SupportTicket: { // Schema fields are `subject` and `message`, not `title`/`description` // (the previous map referenced nonexistent fields — see B7 verify). subject: "redact", message: "redact", fromEmail: "email", fromUrl: "url-rewrite", }, Portal: { domain: "url-rewrite", }, PortalUser: { email: "email", emailNormalized: "email", firstName: "first-name", lastName: "last-name", passwordHash: "null", privacyNoticeAcknowledgedAt: "null", privacyNoticeAcknowledgedUrl: "null", }, PortalSession: { tokenHash: "sha256-prefix", ipAddressHash: "sha256-prefix", }, PortalToken: { tokenHash: "sha256-hex", requestedIpHash: "sha256-hex", }, PortalPage: { attributes: "redact", }, NotificationDelivery: { payload: "redact", email: "email", }, UserNotificationPreference: { email: "email", phone: "phone", }, Site: { customDomain: "url-rewrite", }, TenantSettingsRow: { settings: "redact", }, KnowledgeBase: { description: "redact", }, KnowledgeBaseCategory: { description: "redact", }, KnowledgeBaseCategorySection: { description: "redact", }, KnowledgeBaseArticle: { description: "redact", contentDraft: "redact", contentPublished: "redact", contentPublishedAsText: "redact", }, KnowledgeBaseViews: { userAnalyticsId: "sha256-prefix", }, KnowledgeBaseArticleViews: { userAnalyticsId: "sha256-prefix", }, KnowledgeBaseArticleUpvotes: { userAnalyticsId: "sha256-prefix", }, KnowledgeBaseArticleDownvotes: { userAnalyticsId: "sha256-prefix", }, AnalyticsUniqueVisitor: { cookie: "sha256-prefix", httpReferrer: "url-rewrite", city: "redact", fromUrl: "url-rewrite", }, AnalyticsPageView: { url: "url-rewrite", }, AnalyticsEvent: { label: "redact", value: "redact", url: "url-rewrite", }, OnboardingSessionAction: { value: "redact", }, PluginUserConfig: { configJson: "redact", }, TenantSubscriptionProduct: { billingProviderSubscriptionId: "billing-subscription-id", lagoSubscriptionId: "payment-id-generic", fromCheckoutSessionId: "payment-id-generic", }, /** * Global rows extracted alongside the tenant slice. These rows are * referenced by tenant-scoped FKs and otherwise break restore into an * empty target DB. See models.ts::GLOBAL_REFERENCED_MODELS. * * Every PII column on `User` must be scrubbed. `passwordHash`, * `verifyToken`, MFA secrets and OAuth subject ids are sensitive * credentials, not PII-with-utility — set them to null/redacted so * the restored user can never be logged into via the original creds. * `id` is intentionally NOT touched: tenant-scoped FK columns must * keep pointing at the same id after restore. */ User: { email: "email", firstName: "first-name", lastName: "last-name", phone: "phone", avatar: "avatar-url", passwordHash: "null", verifyToken: "null", totpSecretEncrypted: "null", totpPendingSecretEncrypted: "null", mfaRecoveryCodeHashes: "null", deletionRequestId: "null", }, }; /** * The minimal profile keeps display names (firstName/lastName) but still * scrubs DSGVO-relevant identifiers, payment ids, raw IPs and secrets. */ export const MINIMAL_ANONYMIZED_PROFILE: AnonymizationProfile = (() => { const out: Record> = {}; for (const [model, fields] of Object.entries(FULL_ANONYMIZED_PROFILE)) { const next: Record = {}; for (const [field, strategy] of Object.entries(fields)) { if (strategy === "first-name" || strategy === "last-name" || strategy === "full-name") { next[field] = "keep"; } else { next[field] = strategy; } } out[model] = next; } return out; })(); export const NONE_PROFILE: AnonymizationProfile = {}; export const PROFILES: Readonly> = { "full-anonymized": FULL_ANONYMIZED_PROFILE, "minimal-anonymized": MINIMAL_ANONYMIZED_PROFILE, none: NONE_PROFILE, }; export function isProfileName(value: string): value is ProfileName { return value === "full-anonymized" || value === "minimal-anonymized" || value === "none"; } export interface AnonymizationContext { /** Per-snapshot salt. Combined with `originalValue` to seed the transform. */ readonly salt: string; /** Name of the profile being applied; included in errors for debuggability. */ readonly profileName: ProfileName; } const FIRST_NAMES = [ "Alex", "Sam", "Jordan", "Taylor", "Morgan", "Casey", "Avery", "Riley", "Quinn", "Reese", "Skyler", "Drew", "Elliot", "Hayden", "Jamie", "Kai", "Logan", "Parker", "Robin", "Sage", "Tatum", "River", "Phoenix", "Rowan", ]; const LAST_NAMES = [ "Smith", "Johnson", "Lee", "Patel", "Garcia", "Mueller", "Schmidt", "Nguyen", "Kim", "Davis", "Brown", "Wilson", "Mendez", "Rossi", "Andersen", "Becker", ]; const STREET_NAMES = ["Main", "Oak", "Pine", "Maple", "Elm", "Cedar", "Birch", "Willow", "Cherry", "Hauptstrasse", "Bahnhofstrasse"]; const CITIES = ["Springfield", "Riverton", "Oakville", "Lakeside", "Hillview", "Mapleton", "Pinehurst", "Bergstadt", "Seedorf"]; const COUNTRIES = ["AT", "DE", "CH", "NL", "PT", "IE", "FI", "SE"]; /** * Apply an anonymization profile to a row from the named model. Returns a * shallow copy with anonymized field values. Unknown fields and fields not in * the profile are passed through unchanged. */ export function anonymizeRow( profile: AnonymizationProfile, modelName: string, row: Record, ctx: AnonymizationContext ): Record { const mapping = profile[modelName]; if (!mapping) return { ...row }; const out: Record = { ...row }; for (const [field, strategy] of Object.entries(mapping)) { if (!(field in out)) continue; const original = out[field]; if (original === null || original === undefined) continue; out[field] = applyStrategy(strategy, original, ctx); } return out; } /** Apply a single field strategy. Exported for unit tests. */ export function applyStrategy(strategy: FieldStrategy, value: unknown, ctx: AnonymizationContext): unknown { switch (strategy) { case "keep": return value; case "null": return null; case "redact": return "[REDACTED]"; case "email": return anonEmail(value, ctx); case "first-name": return pick(FIRST_NAMES, value, ctx); case "last-name": return pick(LAST_NAMES, value, ctx); case "full-name": return `${pick(FIRST_NAMES, value, ctx)} ${pick(LAST_NAMES, value, ctx)}`; case "phone": return null; case "address-street": { const street = pick(STREET_NAMES, value, ctx); const num = seededInt(value, ctx, 1, 999); return `${num} ${street} St`; } case "address-city": return pick(CITIES, value, ctx); case "address-country": return pick(COUNTRIES, value, ctx); case "zip-code": return anonZip(value, ctx); case "ip-address": return anonIp(value, ctx); case "billing-customer-id": return `cus_anon${seededHex(value, ctx, 8)}`; case "billing-subscription-id": return `sub_anon${seededHex(value, ctx, 8)}`; case "payment-method-id": return `pm_anon${seededHex(value, ctx, 8)}`; case "payment-id-generic": return `anon_${seededHex(value, ctx, 12)}`; case "url-rewrite": return `https://anonymized.test/${seededHex(value, ctx, 10)}`; case "avatar-url": return `https://anonymized.test/avatar/${seededHex(value, ctx, 8)}.png`; case "sha256-prefix": return `anon-${seedHex(stringify(value), ctx).slice(0, 16)}`; case "sha256-hex": return seedHex(stringify(value), ctx); case "truncate-32": { const s = stringify(value); return s.length > 32 ? `${s.slice(0, 29)}...` : s; } default: { const exhaustive: never = strategy; throw new Error(`Unknown anonymization strategy: ${String(exhaustive)}`); } } } function stringify(value: unknown): string { if (typeof value === "string") return value; if (value === null || value === undefined) return ""; if (typeof value === "object") return JSON.stringify(value); return String(value); } function seedHex(originalValue: string, ctx: AnonymizationContext): string { return createHash("sha256").update(`${ctx.salt}::${originalValue}`).digest("hex"); } function seededInt(value: unknown, ctx: AnonymizationContext, min: number, max: number): number { const hex = seedHex(stringify(value), ctx).slice(0, 12); const n = Number.parseInt(hex, 16); const range = max - min + 1; return min + (n % range); } function seededHex(value: unknown, ctx: AnonymizationContext, length: number): string { return seedHex(stringify(value), ctx).slice(0, length); } function pick(arr: readonly T[], value: unknown, ctx: AnonymizationContext): T { const idx = seededInt(value, ctx, 0, arr.length - 1); return arr[idx]; } function anonEmail(value: unknown, ctx: AnonymizationContext): string { const local = seededHex(value, ctx, 12); return `user-${local}@anonymized.test`; } function anonIp(value: unknown, ctx: AnonymizationContext): string { const oct4 = seededInt(value, ctx, 0, 254); return `127.0.0.${oct4}`; } function anonZip(value: unknown, ctx: AnonymizationContext): string { const s = stringify(value); const prefix = s.slice(0, 2).padEnd(2, "0"); const rest = String(seededInt(value, ctx, 0, 999)).padStart(3, "0"); return `${prefix}${rest}`; }