204 lines
6.6 KiB
TypeScript
204 lines
6.6 KiB
TypeScript
/**
|
|
* F-003 — Per-tenant hash chain over PluginCapabilityUse rows.
|
|
*
|
|
* Each row carries:
|
|
* - `prevHash` : the `rowHash` of the immediately preceding row in
|
|
* this tenant's chain (or NULL for the genesis row).
|
|
* - `rowHash` : SHA-256(prevHash || canonical(row)).
|
|
*
|
|
* The chain is per-tenant (not global) so a noisy tenant doesn't
|
|
* serialise every other tenant's insert path. The worker handler
|
|
* computes the chain inside `pluginCapabilityUseChain.stamp(...)` and
|
|
* persists both columns; the verifier in `verifyPluginCapabilityUseChain`
|
|
* walks an ordered slice and reports any break.
|
|
*
|
|
* Tampering detection is deterministic: any modification to a row
|
|
* changes its `rowHash`, which changes every subsequent `prevHash`,
|
|
* which changes every subsequent `rowHash` — the verifier sees a
|
|
* cascade of breaks starting at the modified row. A *deleted* row
|
|
* leaves the next row's `prevHash` referencing a hash that no longer
|
|
* exists in the chain head, which the verifier flags as `prev_mismatch`.
|
|
*
|
|
* The canonical form is a stable string built from a fixed field list
|
|
* (deterministic ordering). New columns added later must be appended to
|
|
* the field list, never inserted in the middle — that would invalidate
|
|
* every existing hash.
|
|
*/
|
|
|
|
import { createHash } from "node:crypto";
|
|
|
|
/**
|
|
* The fields included in the canonical form, in the EXACT order they
|
|
* are hashed. Appending new fields at the end is forward-compatible;
|
|
* reordering or inserting in the middle is a CHAIN-BREAKING change and
|
|
* must be paired with a re-stamping migration.
|
|
*/
|
|
export const CHAIN_FIELDS = [
|
|
"id",
|
|
"pluginInvocationId",
|
|
"tenantId",
|
|
"pluginId",
|
|
"capability",
|
|
"payloadHash",
|
|
"outcome",
|
|
"errorCode",
|
|
"durationMs",
|
|
"timestamp",
|
|
] as const;
|
|
|
|
export type PluginCapabilityUseChainRow = {
|
|
readonly id: string;
|
|
readonly pluginInvocationId: string;
|
|
readonly tenantId: string;
|
|
readonly pluginId: string;
|
|
readonly capability: string;
|
|
readonly payloadHash?: string | null;
|
|
readonly outcome: string;
|
|
readonly errorCode?: string | null;
|
|
readonly durationMs?: number | null;
|
|
/** ISO-8601 string at canonicalisation time. */
|
|
readonly timestamp: string;
|
|
};
|
|
|
|
const NULL_MARKER = " |