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,415 @@
/**
* 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"
| "stripe-customer-id"
| "stripe-subscription-id"
| "stripe-payment-method-id"
| "stripe-id-generic"
| "url-rewrite"
| "avatar-url"
| "redact"
| "sha256-prefix"
| "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<Record<string, Readonly<Record<string, FieldStrategy>>>>;
/**
* 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: "truncate-32",
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: "truncate-32",
},
Log: {
error: "redact",
url: "url-rewrite",
},
Campaign: {
fromEmail: "email",
fromName: "full-name",
replyToEmail: "email",
},
EmailSender: {
fromEmail: "email",
fromName: "full-name",
apiKey: "redact",
domain: "url-rewrite",
},
TenantInboundAddress: {
address: "email",
forwardTo: "email",
},
OutboundEmail: {
fromEmail: "email",
fromName: "full-name",
toEmail: "email",
replyToEmail: "email",
subject: "truncate-32",
htmlBody: "redact",
textBody: "redact",
},
TenantSubscription: {
stripeCustomerId: "stripe-customer-id",
stripeSubscriptionId: "stripe-subscription-id",
},
TenantProductConfiguration: {
stripeAccountId: "stripe-id-generic",
},
Credit: {
stripeInvoiceId: "stripe-id-generic",
},
WorkflowCredential: {
secret: "redact",
apiKey: "redact",
accessToken: "redact",
refreshToken: "redact",
},
Workflow: {
webhookSecret: "redact",
},
WorkflowExecution: {
contextJson: "redact",
errorMessage: "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: "truncate-32",
message: "redact",
fromEmail: "email",
fromUrl: "url-rewrite",
},
Portal: {
customDomain: "url-rewrite",
},
PortalUser: {
email: "email",
firstName: "first-name",
lastName: "last-name",
},
NotificationDelivery: {
payload: "redact",
email: "email",
},
UserNotificationPreference: {
email: "email",
phone: "phone",
},
Site: {
customDomain: "url-rewrite",
},
TenantSettingsRow: {
settings: "redact",
},
KnowledgeBase: {
description: "redact",
},
/**
* 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<string, Record<string, FieldStrategy>> = {};
for (const [model, fields] of Object.entries(FULL_ANONYMIZED_PROFILE)) {
const next: Record<string, FieldStrategy> = {};
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<Record<ProfileName, AnonymizationProfile>> = {
"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<string, unknown>,
ctx: AnonymizationContext,
): Record<string, unknown> {
const mapping = profile[modelName];
if (!mapping) return { ...row };
const out: Record<string, unknown> = { ...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 "stripe-customer-id":
return `cus_anon${seededHex(value, ctx, 8)}`;
case "stripe-subscription-id":
return `sub_anon${seededHex(value, ctx, 8)}`;
case "stripe-payment-method-id":
return `pm_anon${seededHex(value, ctx, 8)}`;
case "stripe-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 "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<T>(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}`;
}