Refresh HiveGrid Cloud reference snapshot

This commit is contained in:
david committed 2026-08-03 15:31:14 +02:00
1 parent 5e99e14772
commit 7f88026f79
5955 files changed
+1177325 -188362

No files matched your search

@@ -15,6 +15,18 @@ import { createHash, createHmac } from "node:crypto";
*/
export const AUDIT_CHAIN_SECRET_ENV = "AUDIT_CHAIN_SECRET";
export const AUDIT_CHAIN_SECRET_MIN_BYTES = 32;
export const AUDIT_HASH_V2_PREFIX = "v2:";
export type AuditHashVersion = "legacy-v1" | "hmac-v2";
export class AuditChainSecretError extends Error {
override readonly name = "AuditChainSecretError";
constructor() {
super(`${AUDIT_CHAIN_SECRET_ENV} must contain at least ${AUDIT_CHAIN_SECRET_MIN_BYTES} UTF-8 bytes in production.`);
}
}
export type AuditHashPayload = {
/** Stable identifier of the event (`AuditEvent.id`). */
@@ -46,11 +58,12 @@ export type ComputeAuditHashArgs = {
payload: AuditHashPayload;
/**
* Optional explicit secret. When omitted the helper reads
* `process.env.AUDIT_CHAIN_SECRET`; when neither is set the helper falls
* back to plain SHA-256 (still tamper-evident for read-only attackers but
* not forgery-resistant).
* `process.env.AUDIT_CHAIN_SECRET`. Production requires at least 32 bytes;
* only development and tests may fall back to plain SHA-256.
*/
secret?: string | null;
/** New persisted events use hmac-v2; legacy-v1 remains verifier-only compatibility. */
version?: AuditHashVersion;
};
/**
@@ -84,30 +97,50 @@ function sortValue(value: unknown): unknown {
*
* - When `AUDIT_CHAIN_SECRET` is set (env or explicit), uses
* HMAC-SHA-256(secret, previousHash || canonicalPayload).
* - Otherwise falls back to plain SHA-256(previousHash || canonicalPayload).
* - Outside production only, otherwise falls back to plain SHA-256.
*/
export function computeAuditHash(args: ComputeAuditHashArgs): string {
const canonical = canonicalizeAuditPayload(args.payload);
const input = `${args.previousHash ?? ""}\n${canonical}`;
const secret = resolveSecret(args.secret);
const secret = resolveAuditChainSecret(args.secret);
const version = args.version ?? "legacy-v1";
let digest: string;
if (secret) {
return createHmac("sha256", secret).update(input, "utf8").digest("hex");
digest = createHmac("sha256", secret).update(input, "utf8").digest("hex");
} else {
digest = createHash("sha256").update(input, "utf8").digest("hex");
}
return createHash("sha256").update(input, "utf8").digest("hex");
return version === "hmac-v2" ? `${AUDIT_HASH_V2_PREFIX}${digest}` : digest;
}
function resolveSecret(explicit: string | null | undefined): string | null {
if (typeof explicit === "string" && explicit.length > 0) {
return explicit;
export function resolveAuditChainSecret(
explicit: string | null | undefined,
env: Readonly<Record<string, string | undefined>> = process.env,
): string | null {
const candidate = explicit === undefined ? env[AUDIT_CHAIN_SECRET_ENV] : explicit;
const secret = typeof candidate === "string" && candidate.length > 0 ? candidate : null;
if (env.NODE_ENV === "production" && (!secret || Buffer.byteLength(secret, "utf8") < AUDIT_CHAIN_SECRET_MIN_BYTES)) {
throw new AuditChainSecretError();
}
if (explicit === null) {
return null;
return secret;
}
export function isAuditProductionRuntime(
env: Readonly<Record<string, string | undefined>> = process.env,
): boolean {
return env.NODE_ENV === "production";
}
/** Checkpoints are always HMAC-authenticated, including in development and tests. */
export function requireAuditChainSecret(
explicit: string | null | undefined,
env: Readonly<Record<string, string | undefined>> = process.env,
): string {
const secret = resolveAuditChainSecret(explicit, env);
if (!secret || Buffer.byteLength(secret, "utf8") < AUDIT_CHAIN_SECRET_MIN_BYTES) {
throw new AuditChainSecretError();
}
const fromEnv = process.env[AUDIT_CHAIN_SECRET_ENV];
if (typeof fromEnv === "string" && fromEnv.length > 0) {
return fromEnv;
}
return null;
return secret;
}
export type AuditChainEvent = AuditHashPayload & {
@@ -141,10 +174,10 @@ export type VerifyAuditChainResult = {
*/
export function verifyAuditChain(
events: ReadonlyArray<AuditChainEvent>,
options: { secret?: string | null } = {}
options: { secret?: string | null; initialPreviousHash?: string | null } = {}
): VerifyAuditChainResult {
let inspected = 0;
let lastHash: string | null = null;
let lastHash: string | null = options.initialPreviousHash ?? null;
for (const event of events) {
if (event.eventHash === null) {
// Pre-chain history: still update lastHash to null sentinel.
@@ -166,11 +199,25 @@ export function verifyAuditChain(
},
};
}
const recomputed = computeAuditHash({
const isV2 = event.eventHash.startsWith(AUDIT_HASH_V2_PREFIX);
let recomputed = computeAuditHash({
previousHash: event.previousHash,
payload: stripChainFields(event),
payload: isV2 ? stripChainFields(event) : toLegacyHashPayload(event),
secret: options.secret,
version: isV2 ? "hmac-v2" : "legacy-v1",
});
// Two unversioned formats existed before v2: production writers used
// id/createdAt sentinels, while an early verifier/test contract hashed the
// stored values. Accept both for historical rows; all new writes are v2.
if (!isV2 && recomputed !== event.eventHash) {
const legacyStoredFieldsHash = computeAuditHash({
previousHash: event.previousHash,
payload: stripChainFields(event),
secret: options.secret,
version: "legacy-v1",
});
if (legacyStoredFieldsHash === event.eventHash) recomputed = legacyStoredFieldsHash;
}
if (recomputed !== event.eventHash) {
return {
ok: false,
@@ -190,6 +237,10 @@ export function verifyAuditChain(
return { ok: true, inspected, firstBreak: null };
}
function toLegacyHashPayload(event: AuditChainEvent): AuditHashPayload {
return { ...stripChainFields(event), id: "", createdAt: "" };
}
function stripChainFields(event: AuditChainEvent): AuditHashPayload {
// `previousHash` and `eventHash` are NOT part of the payload digest.
return {