Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
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 {
|
||||
|
||||
Reference in new issue
Block a user