Update hivegrid-cloud reference to latest main
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
1 parent
e98d38e716
commit
7b21524c86
3781 files changed
+373484
-225607
No files matched your search
+173
@@ -0,0 +1,173 @@
|
||||
/**
|
||||
* AK-P19 — Platform-Admin operator-action audit gate (DoD #7).
|
||||
*
|
||||
* Sensitive operator actions on `admin.hivegrid.de` (tenant status change,
|
||||
* manual tenant creation, trial extension, tenant notes, subscription
|
||||
* override, impersonation) must be (a) backed by a mandatory free-text
|
||||
* `reason`, (b) for destructive actions confirmed by re-typing a
|
||||
* confirm-phrase, and (c) recorded into the cross-tenant audit log.
|
||||
*
|
||||
* Per the AK-P19 plan this REUSES the existing AuditEvent Querschnitt
|
||||
* (`@hivegrid/db/audit-events.server`, hash chain owned by AK-P3) rather
|
||||
* than building a parallel `AdminAuditLog` table: admin actions are
|
||||
* AuditEvent rows with `tenantId = null` + `actorType = "admin"`. This is
|
||||
* the same emit path that `modules/admin-sso/audit.server` already uses
|
||||
* for the login/MFA events — here generalized to operator operations.
|
||||
*
|
||||
* The validation + payload-shaping below are pure functions so they unit
|
||||
* test without a database; only `recordAdminAction` touches the writer.
|
||||
*/
|
||||
import { createAuditEvent, type AuditEventInput, type AuditOutcome } from "@hivegrid/db/audit-events.server";
|
||||
import type { Prisma } from "@hivegrid/db/prisma-browser";
|
||||
|
||||
/**
|
||||
* Closed taxonomy of audited platform-operator actions. Closed union so a
|
||||
* typo at a call site is a TS error, not a silently-unaudited action. The
|
||||
* value is suffixed onto `admin.` to form the AuditEvent `action`.
|
||||
*/
|
||||
export const ADMIN_OPERATOR_ACTIONS = [
|
||||
"tenant.created",
|
||||
"tenant.statusChanged",
|
||||
"tenant.trialExtended",
|
||||
"tenant.note.created",
|
||||
"tenant.note.deleted",
|
||||
"subscription.overridden",
|
||||
"subscription.featureToggled",
|
||||
"subscription.syncRequested",
|
||||
"impersonation.started",
|
||||
"queue.paused",
|
||||
"queue.resumed",
|
||||
"queue.jobRetried",
|
||||
"support.replied",
|
||||
"support.noteAdded",
|
||||
"support.statusChanged",
|
||||
"support.assigned",
|
||||
] as const;
|
||||
|
||||
export type AdminOperatorAction = (typeof ADMIN_OPERATOR_ACTIONS)[number];
|
||||
|
||||
/** Minimum trimmed length of a reason before it is considered meaningful. */
|
||||
export const ADMIN_REASON_MIN_LENGTH = 5;
|
||||
|
||||
export type AdminActionInputErrorCode = "REASON_REQUIRED" | "REASON_TOO_SHORT" | "CONFIRM_PHRASE_MISMATCH";
|
||||
|
||||
/**
|
||||
* Input-validation failure for an operator action. Carries a stable `code`
|
||||
* and an i18n key so the route maps it onto an M002-catalog message — no
|
||||
* hard-coded UI text leaves this layer (Klartext-Diagnostik A.1).
|
||||
*/
|
||||
export class AdminActionInputError extends Error {
|
||||
override readonly name = "AdminActionInputError";
|
||||
readonly code: AdminActionInputErrorCode;
|
||||
readonly i18nKey: string;
|
||||
constructor(code: AdminActionInputErrorCode) {
|
||||
super(code);
|
||||
this.code = code;
|
||||
this.i18nKey = ADMIN_ACTION_ERROR_I18N_KEYS[code];
|
||||
}
|
||||
}
|
||||
|
||||
const ADMIN_ACTION_ERROR_I18N_KEYS: Record<AdminActionInputErrorCode, string> = {
|
||||
REASON_REQUIRED: "admin.audit.errors.reasonRequired",
|
||||
REASON_TOO_SHORT: "admin.audit.errors.reasonTooShort",
|
||||
CONFIRM_PHRASE_MISMATCH: "admin.audit.errors.confirmPhraseMismatch",
|
||||
};
|
||||
|
||||
export type ReasonValidationResult =
|
||||
| { readonly ok: true; readonly value: string }
|
||||
| { readonly ok: false; readonly code: Extract<AdminActionInputErrorCode, "REASON_REQUIRED" | "REASON_TOO_SHORT"> };
|
||||
|
||||
/**
|
||||
* Validates a mandatory operator reason. Pure — returns a discriminated
|
||||
* result instead of throwing so callers can branch without try/catch.
|
||||
*/
|
||||
export function validateAdminActionReason(reason: string | null | undefined): ReasonValidationResult {
|
||||
const trimmed = (reason ?? "").trim();
|
||||
if (trimmed.length === 0) return { ok: false, code: "REASON_REQUIRED" };
|
||||
if (trimmed.length < ADMIN_REASON_MIN_LENGTH) return { ok: false, code: "REASON_TOO_SHORT" };
|
||||
return { ok: true, value: trimmed };
|
||||
}
|
||||
|
||||
/** Throwing variant for imperative call sites; returns the trimmed reason. */
|
||||
export function assertAdminActionReason(reason: string | null | undefined): string {
|
||||
const result = validateAdminActionReason(reason);
|
||||
if (!result.ok) throw new AdminActionInputError(result.code);
|
||||
return result.value;
|
||||
}
|
||||
|
||||
/**
|
||||
* Exact (trimmed) match of a destructive-action confirm-phrase, e.g. the
|
||||
* operator re-typing the tenant slug before a status change. Case- and
|
||||
* whitespace-sensitive beyond the outer trim so "Acme " != "acme".
|
||||
*/
|
||||
export function confirmPhraseMatches(expected: string, provided: string | null | undefined): boolean {
|
||||
return expected.trim().length > 0 && (provided ?? "").trim() === expected.trim();
|
||||
}
|
||||
|
||||
/** Throwing variant: enforces the confirm-phrase or raises a catalog error. */
|
||||
export function assertConfirmPhrase(expected: string, provided: string | null | undefined): void {
|
||||
if (!confirmPhraseMatches(expected, provided)) throw new AdminActionInputError("CONFIRM_PHRASE_MISMATCH");
|
||||
}
|
||||
|
||||
export type AdminActionAuditContext = {
|
||||
readonly action: AdminOperatorAction;
|
||||
readonly actorUserId: string | null;
|
||||
readonly actorEmail?: string | null;
|
||||
readonly targetKind: string;
|
||||
readonly targetId: string | null;
|
||||
readonly reason: string;
|
||||
/** Optional structured before/after diff stored in audit metadata. */
|
||||
readonly before?: Record<string, unknown> | null;
|
||||
readonly after?: Record<string, unknown> | null;
|
||||
readonly outcome?: AuditOutcome;
|
||||
readonly request?: Request;
|
||||
/** Extra non-sensitive metadata to merge (redacted by the audit layer). */
|
||||
readonly extraMeta?: Record<string, unknown>;
|
||||
};
|
||||
|
||||
function clientMeta(request: Request | undefined): { ip: string | null; userAgent: string | null } {
|
||||
if (!request) return { ip: null, userAgent: null };
|
||||
const fwd = request.headers.get("x-forwarded-for") ?? "";
|
||||
const ip = fwd.split(",")[0]?.trim() || request.headers.get("x-real-ip") || null;
|
||||
const userAgent = request.headers.get("user-agent") || null;
|
||||
return { ip, userAgent };
|
||||
}
|
||||
|
||||
/**
|
||||
* Shapes the {@link AuditEventInput} for an operator action. Pure: no DB,
|
||||
* no clock. `tenantId` is always null (cross-tenant platform log) and the
|
||||
* actor is always `admin`. The reason + diff land in metadata.
|
||||
*/
|
||||
export function buildAdminActionAuditInput(context: AdminActionAuditContext): AuditEventInput {
|
||||
const { ip, userAgent } = clientMeta(context.request);
|
||||
return {
|
||||
tenantId: null,
|
||||
actorType: "admin",
|
||||
actorId: context.actorUserId,
|
||||
actorEmail: context.actorEmail ?? null,
|
||||
actorIp: ip,
|
||||
actorUserAgent: userAgent,
|
||||
action: `admin.${context.action}`,
|
||||
targetType: context.targetKind,
|
||||
targetId: context.targetId,
|
||||
sourceModule: "admin",
|
||||
outcome: context.outcome ?? "success",
|
||||
dataSensitivity: "confidential",
|
||||
regulatoryScope: ["soc2"],
|
||||
metadata: {
|
||||
reason: context.reason,
|
||||
before: context.before ?? null,
|
||||
after: context.after ?? null,
|
||||
...context.extraMeta,
|
||||
} as unknown as Prisma.InputJsonValue,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* Records an operator action into the cross-tenant audit log. Errors
|
||||
* propagate (unlike the best-effort SSO logger): a sensitive operator
|
||||
* action that cannot be audited should surface, not silently succeed.
|
||||
*/
|
||||
export async function recordAdminAction(context: AdminActionAuditContext): Promise<void> {
|
||||
await createAuditEvent(buildAdminActionAuditInput(context));
|
||||
}
|
||||
Reference in new issue
Block a user