Reorganize repo structure and standards references
This commit is contained in:
1 parent
3cb93a81be
commit
be2054274d
5885 files changed
+2588
-195
No files matched your search
@@ -0,0 +1,66 @@
|
||||
/**
|
||||
* Snapshot-event audit log. Spec doesn't mandate a DB-write (the source
|
||||
* system's AuditEvent table is reachable but requires Prisma which we keep
|
||||
* out of the CLI); instead this module produces a structured, line-oriented
|
||||
* audit record that operators redirect to a file or syslog.
|
||||
*
|
||||
* The `none` profile is the only one that requires the super-admin guardrail
|
||||
* at the command layer; the audit entry is always written regardless of
|
||||
* profile so that every snapshot leaves a trail.
|
||||
*/
|
||||
import { appendFile } from "node:fs/promises";
|
||||
|
||||
export type SnapshotProfile = "full-anonymized" | "minimal-anonymized" | "none";
|
||||
|
||||
export interface SnapshotAuditEntry {
|
||||
readonly event: "TENANT_SNAPSHOT_CREATED";
|
||||
readonly snapshotId: string;
|
||||
readonly sourceTenantId: string;
|
||||
readonly profile: SnapshotProfile;
|
||||
readonly actorUserId: string | null;
|
||||
readonly host: string | null;
|
||||
readonly createdAt: string;
|
||||
readonly outputTarget: string;
|
||||
/** Whether the super-admin escape hatch was invoked for `none`. */
|
||||
readonly superAdminConfirmed: boolean;
|
||||
}
|
||||
|
||||
export interface WriteSnapshotAuditOptions {
|
||||
readonly entry: SnapshotAuditEntry;
|
||||
/** Optional file path to append the JSON line to. */
|
||||
readonly filePath?: string;
|
||||
/** Sink for the human-readable line (defaults to process.stdout). */
|
||||
readonly stdout?: NodeJS.WritableStream;
|
||||
}
|
||||
|
||||
/**
|
||||
* Append a structured audit entry to an optional file and emit a one-line
|
||||
* human summary on stdout. Returns the serialized JSON.
|
||||
*/
|
||||
export async function writeSnapshotAudit(opts: WriteSnapshotAuditOptions): Promise<string> {
|
||||
const json = JSON.stringify(opts.entry);
|
||||
const line = `[audit] ${opts.entry.event} snapshot=${opts.entry.snapshotId} tenant=${opts.entry.sourceTenantId} profile=${opts.entry.profile} actor=${opts.entry.actorUserId ?? "?"} target=${opts.entry.outputTarget}\n`;
|
||||
const out = opts.stdout ?? process.stdout;
|
||||
out.write(line);
|
||||
if (opts.filePath) {
|
||||
await appendFile(opts.filePath, `${json}\n`);
|
||||
}
|
||||
return json;
|
||||
}
|
||||
|
||||
/**
|
||||
* Validate that running the `none` profile is authorized. Throws if not.
|
||||
*/
|
||||
export function assertSuperAdminForNoneProfile(
|
||||
profile: SnapshotProfile,
|
||||
confirmed: boolean,
|
||||
): void {
|
||||
if (profile !== "none") return;
|
||||
if (!confirmed) {
|
||||
throw new Error(
|
||||
"Refusing to run --profile=none without --i-am-the-super-admin. " +
|
||||
"Raw exports of tenant data require an explicit super-admin confirmation and leave " +
|
||||
"a permanent audit trail. See docs/ops/tenant-snapshot.md.",
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user