@panguard-ai/panguard-guard 1.7.0 → 1.7.2

package/dist/audit/audit-key.js

@@ -0,0 +1,132 @@
+/**
+ * Audit HMAC key management.
+ *
+ * The audit chain is signed with a per-machine HMAC key. We resolve it in two
+ * tiers, generate-once + reuse:
+ *   1. Keychain-first: the security-hardening credential store (service
+ *      'panguard-audit'). On macOS/Linux/Windows this is the OS-protected store
+ *      where available; otherwise it falls back to an AES-256-GCM encrypted file
+ *      under ~/.panguard/credentials, keyed by machine entropy.
+ *   2. Plain-file fallback: ~/.panguard/audit-key (randomBytes(32), dir 0700,
+ *      file 0600) for environments where the credential store is unavailable.
+ *
+ * Mirrors the get-or-create discipline of threat-cloud/client-id.ts.
+ *
+ * @module @panguard-ai/panguard-guard/audit/audit-key
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { createLogger } from '@panguard-ai/core';
+import { EncryptedFileCredentialStore } from '@panguard-ai/security-hardening';
+const logger = createLogger('panguard-guard:audit-key');
+/** Credential-store service name for the audit key. */
+const AUDIT_SERVICE = 'panguard-audit';
+/** Credential-store account name. */
+const AUDIT_ACCOUNT = 'hmac-key';
+/** Key size in bytes (256-bit HMAC key). */
+const KEY_BYTES = 32;
+/** Directory holding panguard local secrets. */
+const PANGUARD_DIR = join(homedir(), '.panguard');
+/** Credential-store directory used by the keychain-first tier. */
+const CRED_STORE_DIR = join(PANGUARD_DIR, 'credentials');
+/**
+ * Plain-file fallback path. Same-user-readable: an attacker running as THIS user
+ * can read this key and recompute a consistent chain. This is tamper EVIDENCE,
+ * not tamper PREVENTION — remote anchoring (publish chain head to Threat Cloud)
+ * is the enterprise upgrade that closes the same-user gap. See SECURITY.md.
+ */
+const FALLBACK_KEY_PATH = join(PANGUARD_DIR, 'audit-key');
+/** Cached key so repeated calls in one process don't re-read disk. */
+let cachedKey = null;
+/**
+ * Get (or generate-once and persist) the audit HMAC key.
+ *
+ * Never throws: if the keychain tier is unavailable it falls through to the
+ * file fallback; if even the file cannot be persisted, an in-memory key is
+ * returned so audit signing still works for the life of the process.
+ */
+export async function getAuditKey() {
+    if (cachedKey)
+        return cachedKey;
+    // Tier 1: keychain-first via the credential store.
+    const fromStore = await tryReadFromStore();
+    if (fromStore) {
+        cachedKey = fromStore;
+        return fromStore;
+    }
+    // Tier 2: plain-file fallback (0700 dir / 0600 file).
+    const fromFile = tryReadFromFile();
+    if (fromFile) {
+        cachedKey = fromFile;
+        return fromFile;
+    }
+    // Generate once. Try to persist to the store first, then the file.
+    const fresh = randomBytes(KEY_BYTES);
+    const persistedToStore = await tryWriteToStore(fresh);
+    if (!persistedToStore) {
+        tryWriteToFile(fresh);
+    }
+    cachedKey = fresh;
+    return fresh;
+}
+/** Read the key from the credential store, or null if absent/unavailable. */
+async function tryReadFromStore() {
+    try {
+        const store = new EncryptedFileCredentialStore(CRED_STORE_DIR);
+        const hex = await store.get(AUDIT_SERVICE, AUDIT_ACCOUNT);
+        if (hex && /^[0-9a-f]+$/i.test(hex) && hex.length === KEY_BYTES * 2) {
+            return Buffer.from(hex, 'hex');
+        }
+    }
+    catch (err) {
+        logger.warn(`Audit key store read unavailable: ${errMsg(err)}`);
+    }
+    return null;
+}
+/** Persist the key to the credential store. Returns true on success. */
+async function tryWriteToStore(key) {
+    try {
+        const store = new EncryptedFileCredentialStore(CRED_STORE_DIR);
+        await store.set(AUDIT_SERVICE, AUDIT_ACCOUNT, key.toString('hex'));
+        return true;
+    }
+    catch (err) {
+        logger.warn(`Audit key store write unavailable: ${errMsg(err)}`);
+        return false;
+    }
+}
+/** Read the key from the plain-file fallback, or null if absent/invalid. */
+function tryReadFromFile() {
+    try {
+        if (!existsSync(FALLBACK_KEY_PATH))
+            return null;
+        const hex = readFileSync(FALLBACK_KEY_PATH, 'utf-8').trim();
+        if (hex && /^[0-9a-f]+$/i.test(hex) && hex.length === KEY_BYTES * 2) {
+            return Buffer.from(hex, 'hex');
+        }
+    }
+    catch (err) {
+        logger.warn(`Audit key file read failed: ${errMsg(err)}`);
+    }
+    return null;
+}
+/** Persist the key to the plain-file fallback (0700 dir / 0600 file). */
+function tryWriteToFile(key) {
+    try {
+        mkdirSync(PANGUARD_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(FALLBACK_KEY_PATH, key.toString('hex'), { mode: 0o600 });
+    }
+    catch (err) {
+        logger.warn(`Audit key file persist failed (using in-memory key): ${errMsg(err)}`);
+    }
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Reset the in-process cache. Test-only seam. */
+export function __resetAuditKeyCacheForTests() {
+    cachedKey = null;
+}
+//# sourceMappingURL=audit-key.js.map

package/dist/audit/audit-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-key.js","sourceRoot":"","sources":["../../src/audit/audit-key.ts"],"names":[],"mappings":"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"}

package/dist/audit/hash-chain.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Tamper-evident hash chain primitives (pure, node:crypto only).
+ *
+ * Every durable audit record is linked to its predecessor by a SHA-256 hash,
+ * forming an append-only chain. Any edit, deletion, reorder, or insertion
+ * breaks the chain at the point of tampering and is detectable by verifyChain().
+ *
+ * SCOPE — tamper EVIDENCE, not tamper PREVENTION. The optional HMAC binds the
+ * chain to a local key; an attacker who can READ that key can recompute a
+ * consistent chain. This module makes tampering DETECTABLE, never IMPOSSIBLE.
+ * Closing the same-user-key gap requires remote anchoring (see audit-chain.ts).
+ *
+ * @module @panguard-ai/panguard-guard/audit/hash-chain
+ */
+/** SHA-256 hex digest length. */
+export declare const HASH_HEX_LENGTH = 64;
+/** Genesis predecessor hash: 64 zeros. The first record in a chain links here. */
+export declare const GENESIS_HASH: string;
+/**
+ * A single chained record. The payload is the original log line (verbatim);
+ * seq/ts/prevHash/hash/hmac are the chain envelope. hash and hmac are EXCLUDED
+ * from the hashed material (a record cannot hash over its own hash).
+ */
+export interface ChainedRecord<T = unknown> {
+    /** Monotonic sequence, strictly incrementing from 0. */
+    readonly seq: number;
+    /** ISO timestamp when the record was chained. */
+    readonly ts: string;
+    /** The original, unmodified log payload. */
+    readonly payload: T;
+    /** Hash of the predecessor record (GENESIS_HASH for seq 0 or post-rotation genesis). */
+    readonly prevHash: string;
+    /** This record's hash (over prevHash, seq, ts, canonical payload). */
+    readonly hash: string;
+    /** Optional HMAC of `hash` under the local audit key. */
+    readonly hmac?: string;
+}
+/** Why a chain failed verification (or 'ok'). */
+export type VerifyReason = 'ok' | 'hash-break' | 'seq-gap' | 'bad-hmac' | 'truncated' | 'empty' | 'unchained-legacy';
+/** Result of verifyChain over an ordered list of records. */
+export interface VerifyResult {
+    /** True only when every chained record verified end-to-end. */
+    readonly ok: boolean;
+    /** Number of chained records that verified successfully. */
+    readonly verifiedCount: number;
+    /** Index (into the input array) of the first bad record, or -1 if none. */
+    readonly firstBadIndex: number;
+    /** Machine-readable reason. */
+    readonly reason: VerifyReason;
+}
+/**
+ * Deterministic JSON serialization with RECURSIVELY sorted object keys.
+ *
+ * Two semantically equal objects (same data, different key order, nested at any
+ * depth) serialize to the same string, so the hash is stable regardless of how
+ * the producer happened to order its keys. Arrays keep their order (order is
+ * semantically meaningful for arrays).
+ *
+ * CRITICAL: we first normalize through JSON (parse(stringify(value))) so values
+ * with a custom toJSON (Date, Buffer, etc.) and `undefined` fields are reduced to
+ * their PLAIN JSON form — exactly what a reader sees after JSON.parse. Without
+ * this, a Date in the payload would hash as `{}` at write time but as its ISO
+ * string at read time, silently breaking the chain. Normalizing guarantees
+ * write/read parity (the read side is already JSON-parsed).
+ */
+export declare function canonicalize(value: unknown): string;
+/**
+ * Compute the chain hash for a record.
+ * hash = sha256( prevHash + '\n' + seq + '\n' + ts + '\n' + canonicalize(payload) )
+ *
+ * The newline delimiters make the field boundaries unambiguous so distinct
+ * field combinations cannot collide via concatenation.
+ */
+export declare function computeHash(prevHash: string, seq: number, ts: string, payload: unknown): string;
+/**
+ * Sign a record hash with the local audit key.
+ * hmac = HMAC-SHA256(key, hash) hex.
+ */
+export declare function signHmac(hash: string, key: Buffer): string;
+/**
+ * Verify an ordered list of records.
+ *
+ * Pre-existing un-chained legacy lines (no hash field) at the FRONT are treated
+ * as an un-verifiable prefix: verification starts at the first chained record
+ * and reports reason 'unchained-legacy' (verifiedCount counts the chained suffix
+ * only). This stops an upgrade from flagging the whole file as tampered.
+ *
+ * Walk rules over the chained suffix:
+ *  - seq must strictly increment from the first chained record's seq baseline
+ *    (else 'seq-gap'),
+ *  - recompute hash and compare (else 'hash-break'),
+ *  - prevHash of each record must equal the previous record's hash (else 'hash-break'),
+ *  - if a key is supplied, recompute the HMAC and timing-safe compare (else 'bad-hmac').
+ */
+export declare function verifyChain(records: readonly unknown[], key?: Buffer): VerifyResult;
+//# sourceMappingURL=hash-chain.d.ts.map

package/dist/audit/hash-chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-chain.d.ts","sourceRoot":"","sources":["../../src/audit/hash-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,iCAAiC;AACjC,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,kFAAkF;AAClF,eAAO,MAAM,YAAY,QAA8B,CAAC;AAExD;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,wFAAwF;IACxF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,iDAAiD;AACjD,MAAM,MAAM,YAAY,GACpB,IAAI,GACJ,YAAY,GACZ,SAAS,GACT,UAAU,GACV,WAAW,GACX,OAAO,GACP,kBAAkB,CAAC;AAEvB,6DAA6D;AAC7D,MAAM,WAAW,YAAY;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,4DAA4D;IAC5D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,+BAA+B;IAC/B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;CAC/B;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAOnD;AAsBD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,OAAO,GACf,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAE1D;AAuBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,SAAS,OAAO,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,CAmEnF"}

package/dist/audit/hash-chain.js

@@ -0,0 +1,176 @@
+/**
+ * Tamper-evident hash chain primitives (pure, node:crypto only).
+ *
+ * Every durable audit record is linked to its predecessor by a SHA-256 hash,
+ * forming an append-only chain. Any edit, deletion, reorder, or insertion
+ * breaks the chain at the point of tampering and is detectable by verifyChain().
+ *
+ * SCOPE — tamper EVIDENCE, not tamper PREVENTION. The optional HMAC binds the
+ * chain to a local key; an attacker who can READ that key can recompute a
+ * consistent chain. This module makes tampering DETECTABLE, never IMPOSSIBLE.
+ * Closing the same-user-key gap requires remote anchoring (see audit-chain.ts).
+ *
+ * @module @panguard-ai/panguard-guard/audit/hash-chain
+ */
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+/** SHA-256 hex digest length. */
+export const HASH_HEX_LENGTH = 64;
+/** Genesis predecessor hash: 64 zeros. The first record in a chain links here. */
+export const GENESIS_HASH = '0'.repeat(HASH_HEX_LENGTH);
+/**
+ * Deterministic JSON serialization with RECURSIVELY sorted object keys.
+ *
+ * Two semantically equal objects (same data, different key order, nested at any
+ * depth) serialize to the same string, so the hash is stable regardless of how
+ * the producer happened to order its keys. Arrays keep their order (order is
+ * semantically meaningful for arrays).
+ *
+ * CRITICAL: we first normalize through JSON (parse(stringify(value))) so values
+ * with a custom toJSON (Date, Buffer, etc.) and `undefined` fields are reduced to
+ * their PLAIN JSON form — exactly what a reader sees after JSON.parse. Without
+ * this, a Date in the payload would hash as `{}` at write time but as its ISO
+ * string at read time, silently breaking the chain. Normalizing guarantees
+ * write/read parity (the read side is already JSON-parsed).
+ */
+export function canonicalize(value) {
+    // toJSONString handles undefined at the top level (JSON.stringify(undefined)
+    // is the string "undefined"'s absence — guard it).
+    const json = JSON.stringify(value);
+    if (json === undefined)
+        return JSON.stringify(null);
+    const normalized = JSON.parse(json);
+    return JSON.stringify(sortDeep(normalized));
+}
+/**
+ * Recursively rebuild a (already JSON-normalized) value with object keys sorted.
+ * Primitives pass through. Arrays recurse element-wise (order preserved). Objects
+ * are rebuilt key-sorted.
+ */
+function sortDeep(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => sortDeep(item));
+    }
+    if (value !== null && typeof value === 'object') {
+        const obj = value;
+        const sorted = {};
+        for (const key of Object.keys(obj).sort()) {
+            sorted[key] = sortDeep(obj[key]);
+        }
+        return sorted;
+    }
+    return value;
+}
+/**
+ * Compute the chain hash for a record.
+ * hash = sha256( prevHash + '\n' + seq + '\n' + ts + '\n' + canonicalize(payload) )
+ *
+ * The newline delimiters make the field boundaries unambiguous so distinct
+ * field combinations cannot collide via concatenation.
+ */
+export function computeHash(prevHash, seq, ts, payload) {
+    return createHash('sha256')
+        .update(`${prevHash}\n${seq}\n${ts}\n${canonicalize(payload)}`)
+        .digest('hex');
+}
+/**
+ * Sign a record hash with the local audit key.
+ * hmac = HMAC-SHA256(key, hash) hex.
+ */
+export function signHmac(hash, key) {
+    return createHmac('sha256', key).update(hash).digest('hex');
+}
+/** Constant-time hex-string compare. Length mismatch returns false (never throws). */
+function timingSafeEqualHex(a, b) {
+    if (a.length !== b.length)
+        return false;
+    try {
+        return timingSafeEqual(Buffer.from(a, 'hex'), Buffer.from(b, 'hex'));
+    }
+    catch {
+        return false;
+    }
+}
+/** True if a record carries the chain envelope (a chained record, not a legacy line). */
+function isChained(rec) {
+    if (rec === null || typeof rec !== 'object')
+        return false;
+    const r = rec;
+    return (typeof r['hash'] === 'string' &&
+        typeof r['prevHash'] === 'string' &&
+        typeof r['seq'] === 'number');
+}
+/**
+ * Verify an ordered list of records.
+ *
+ * Pre-existing un-chained legacy lines (no hash field) at the FRONT are treated
+ * as an un-verifiable prefix: verification starts at the first chained record
+ * and reports reason 'unchained-legacy' (verifiedCount counts the chained suffix
+ * only). This stops an upgrade from flagging the whole file as tampered.
+ *
+ * Walk rules over the chained suffix:
+ *  - seq must strictly increment from the first chained record's seq baseline
+ *    (else 'seq-gap'),
+ *  - recompute hash and compare (else 'hash-break'),
+ *  - prevHash of each record must equal the previous record's hash (else 'hash-break'),
+ *  - if a key is supplied, recompute the HMAC and timing-safe compare (else 'bad-hmac').
+ */
+export function verifyChain(records, key) {
+    if (records.length === 0) {
+        return { ok: false, verifiedCount: 0, firstBadIndex: -1, reason: 'empty' };
+    }
+    // Find where the chained suffix begins. A legacy prefix is tolerated.
+    const firstChainedIndex = records.findIndex((r) => isChained(r));
+    if (firstChainedIndex === -1) {
+        // Entire file is legacy / un-chained — nothing verifiable, but not "tampered".
+        return {
+            ok: false,
+            verifiedCount: 0,
+            firstBadIndex: -1,
+            reason: 'unchained-legacy',
+        };
+    }
+    const hasLegacyPrefix = firstChainedIndex > 0;
+    let verifiedCount = 0;
+    let expectedPrevHash = GENESIS_HASH;
+    let expectedSeq = records[firstChainedIndex].seq;
+    // The first chained record's seq is the baseline; subsequent records must
+    // increment by exactly 1. (A post-rotation genesis can start at any seq, but
+    // within a single readAll() the suffix is contiguous.)
+    for (let i = firstChainedIndex; i < records.length; i++) {
+        const rec = records[i];
+        if (!isChained(rec)) {
+            // A legacy line appearing AFTER chained records means the suffix was
+            // disturbed (e.g. a chained line replaced with a raw one) — hash-break.
+            return { ok: false, verifiedCount, firstBadIndex: i, reason: 'hash-break' };
+        }
+        if (rec.seq !== expectedSeq) {
+            return { ok: false, verifiedCount, firstBadIndex: i, reason: 'seq-gap' };
+        }
+        if (rec.prevHash !== expectedPrevHash) {
+            return { ok: false, verifiedCount, firstBadIndex: i, reason: 'hash-break' };
+        }
+        const recomputed = computeHash(rec.prevHash, rec.seq, rec.ts, rec.payload);
+        if (!timingSafeEqualHex(recomputed, rec.hash)) {
+            return { ok: false, verifiedCount, firstBadIndex: i, reason: 'hash-break' };
+        }
+        if (key) {
+            if (typeof rec.hmac !== 'string') {
+                return { ok: false, verifiedCount, firstBadIndex: i, reason: 'bad-hmac' };
+            }
+            const recomputedHmac = signHmac(rec.hash, key);
+            if (!timingSafeEqualHex(recomputedHmac, rec.hmac)) {
+                return { ok: false, verifiedCount, firstBadIndex: i, reason: 'bad-hmac' };
+            }
+        }
+        verifiedCount++;
+        expectedPrevHash = rec.hash;
+        expectedSeq = rec.seq + 1;
+    }
+    return {
+        ok: !hasLegacyPrefix,
+        verifiedCount,
+        firstBadIndex: -1,
+        reason: hasLegacyPrefix ? 'unchained-legacy' : 'ok',
+    };
+}
+//# sourceMappingURL=hash-chain.js.map

package/dist/audit/hash-chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-chain.js","sourceRoot":"","sources":["../../src/audit/hash-chain.ts"],"names":[],"mappings":"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"}

package/dist/audit/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Tamper-evident audit subsystem.
+ *
+ * - hash-chain: pure SHA-256 chain + HMAC primitives and verifyChain.
+ * - audit-chain: durable, append-only, rotation-spanning JSONL chain.
+ * - audit-key: keychain-first / file-fallback HMAC key management.
+ * - attribution: forensic actor/decisionId/rule enrichment.
+ *
+ * @module @panguard-ai/panguard-guard/audit
+ */
+export { GENESIS_HASH, HASH_HEX_LENGTH, canonicalize, computeHash, signHmac, verifyChain, type ChainedRecord, type VerifyReason, type VerifyResult, } from './hash-chain.js';
+export { AuditChain, type AuditChainOptions, type ChainHead, type AnchorHook, } from './audit-chain.js';
+export { getAuditKey, __resetAuditKeyCacheForTests } from './audit-key.js';
+export { buildActor, newDecisionId, anonymizeActorForExport, type Actor, type AgentAttribution, type RuleRef, } from './attribution.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,UAAU,EACV,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,UAAU,EACV,aAAa,EACb,uBAAuB,EACvB,KAAK,KAAK,EACV,KAAK,gBAAgB,EACrB,KAAK,OAAO,GACb,MAAM,kBAAkB,CAAC"}

package/dist/audit/index.js

@@ -0,0 +1,15 @@
+/**
+ * Tamper-evident audit subsystem.
+ *
+ * - hash-chain: pure SHA-256 chain + HMAC primitives and verifyChain.
+ * - audit-chain: durable, append-only, rotation-spanning JSONL chain.
+ * - audit-key: keychain-first / file-fallback HMAC key management.
+ * - attribution: forensic actor/decisionId/rule enrichment.
+ *
+ * @module @panguard-ai/panguard-guard/audit
+ */
+export { GENESIS_HASH, HASH_HEX_LENGTH, canonicalize, computeHash, signHmac, verifyChain, } from './hash-chain.js';
+export { AuditChain, } from './audit-chain.js';
+export { getAuditKey, __resetAuditKeyCacheForTests } from './audit-key.js';
+export { buildActor, newDecisionId, anonymizeActorForExport, } from './attribution.js';
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EACL,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,WAAW,GAIZ,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,UAAU,GAIX,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,WAAW,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAE3E,OAAO,EACL,UAAU,EACV,aAAa,EACb,uBAAuB,GAIxB,MAAM,kBAAkB,CAAC"}

package/dist/cli/index.js

@@ -209,6 +209,33 @@ async function commandStart(dataDir, verbose = false, managerUrl, noTelemetry =
             // Never let TC provisioning block or crash startup.
         }
     }
+    // S5: verify config integrity + self-state before the engine starts. On a genuine
+    // first run, establish the seal. On tamper / self-removal, start anyway but warn
+    // LOUDLY — never silently honor a weakened config as if PROTECTED (the S2 invariant).
+    try {
+        const { verifyConfigIntegrity, checkSelfState, sealConfigManifest, wasInitialized } = await import('../integrity.js');
+        const cfgRecord = config;
+        let verdict = verifyConfigIntegrity(cfgRecord, dataDir);
+        const selfState = checkSelfState(dataDir);
+        if (verdict.status === 'unsealed' && !wasInitialized(dataDir)) {
+            sealConfigManifest(cfgRecord, [], dataDir); // true first run — establish trust
+            verdict = { status: 'sealed', findings: [], checkedAt: verdict.checkedAt };
+        }
+        if (verdict.status !== 'sealed' || !selfState.ok) {
+            process.stderr.write(`\n[panguard-guard] INTEGRITY: ${verdict.status.toUpperCase()} — protection state may have been changed outside the guard.\n`);
+            // Field NAME only, never the value — config can hold secrets.
+            for (const f of verdict.findings) {
+                process.stderr.write(`  - config.${f.field} changed (${f.severity})\n`);
+            }
+            for (const f of selfState.findings) {
+                process.stderr.write(`  - ${f.kind} ${f.reason}${f.label ? ` (${f.label})` : ''}\n`);
+            }
+            process.stderr.write('  Run "pga doctor" to review. If you made this change, re-run "pga up" to re-seal.\n\n');
+        }
+    }
+    catch {
+        /* integrity is best-effort — never block daemon startup (consistent with TC provisioning) */
+    }
     const engine = await GuardEngine.create(config);
     const shutdown = async () => {
         console.log(`\n  ${symbols.info} Shutting down PanguardGuard...`);