@panguard-ai/panguard-guard 1.7.1 → 1.7.3

package/dist/audit/attribution.js

@@ -0,0 +1,69 @@
+/**
+ * Forensic attribution for audit records.
+ *
+ * Every durable audit payload is enriched with a stable `actor` block (who/where
+ * the record was produced) plus a `decisionId` and lifted `rule` identity, so an
+ * auditor can answer "who did this, on what host, under which rule" from the log
+ * alone.
+ *
+ * The FULL actor (including OS username) is kept in the LOCAL durable log. The
+ * EXPORT path anonymizes the username before forwarding to an external auditor
+ * (see anonymizeActorForExport).
+ *
+ * @module @panguard-ai/panguard-guard/audit/attribution
+ */
+import { hostname, userInfo } from 'node:os';
+import { createHash, randomUUID } from 'node:crypto';
+/**
+ * Build the local (full) actor block for the current process. Pass agent identity
+ * when the record originates from a guarded agent session.
+ */
+export function buildActor(agent) {
+    return {
+        user: safeUsername(),
+        host: safeHostname(),
+        pid: process.pid,
+        ...(agent ? { agent } : {}),
+    };
+}
+/** Generate a fresh decision id. */
+export function newDecisionId() {
+    return `dec-${randomUUID()}`;
+}
+/**
+ * Anonymize an actor for EXPORT: replace the username with a stable salted hash
+ * so an auditor can correlate same-user records without learning the username,
+ * and never leak a real OS username into a forwarded document. Host/pid/agent
+ * are retained (operationally useful, not personally identifying in the same way).
+ */
+export function anonymizeActorForExport(actor) {
+    if (!actor)
+        return undefined;
+    return {
+        user_hash: hashUser(actor.user),
+        host: actor.host,
+        pid: actor.pid,
+        ...(actor.agent ? { agent: actor.agent } : {}),
+    };
+}
+/** SHA-256 of the username with a fixed domain separator. Not reversible. */
+function hashUser(user) {
+    return createHash('sha256').update(`panguard-audit-user:${user}`).digest('hex').slice(0, 32);
+}
+function safeUsername() {
+    try {
+        return userInfo().username;
+    }
+    catch {
+        return 'unknown';
+    }
+}
+function safeHostname() {
+    try {
+        return hostname();
+    }
+    catch {
+        return 'unknown';
+    }
+}
+//# sourceMappingURL=attribution.js.map

package/dist/audit/attribution.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution.js","sourceRoot":"","sources":["../../src/audit/attribution.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA2BrD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,KAAwB;IACjD,OAAO;QACL,IAAI,EAAE,YAAY,EAAE;QACpB,IAAI,EAAE,YAAY,EAAE;QACpB,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED,oCAAoC;AACpC,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,UAAU,EAAE,EAAE,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAwB;IAC9D,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,OAAO;QACL,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;QAC/B,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,6EAA6E;AAC7E,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,uBAAuB,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/F,CAAC;AAED,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,OAAO,QAAQ,EAAE,CAAC,QAAQ,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,OAAO,QAAQ,EAAE,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

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

@@ -0,0 +1,110 @@
+/**
+ * AuditChain — durable, append-only, tamper-evident JSONL log.
+ *
+ * Wraps a JSONL file so every appended line is a {@link ChainedRecord}: linked
+ * to its predecessor by a SHA-256 hash and signed with a local HMAC key. The
+ * chain head (last seq + last hash) is persisted to a rotation-independent
+ * head-anchor so:
+ *   - a fresh process can append without rescanning the whole file, and
+ *   - tail truncation is detectable (head-anchor seq > last record seq).
+ *
+ * The chain SPANS rotation: when the active log is rotated out, the next file's
+ * first record links to the rotated-out file's last hash (carried in the
+ * head-anchor), so the chain is continuous across events.jsonl + events.jsonl.1.
+ *
+ * SCOPE — tamper EVIDENCE. The HMAC key is same-user-readable (see audit-key.ts
+ * and SECURITY.md). This detects tampering; it does not prevent it. The no-op
+ * anchor seam (getHead + optional anchor hook) is where remote anchoring — the
+ * enterprise upgrade that closes the same-user gap — plugs in.
+ *
+ * @module @panguard-ai/panguard-guard/audit/audit-chain
+ */
+import { type ChainedRecord, type VerifyResult } from './hash-chain.js';
+/** Persisted chain head — the anchor for appends and truncation detection. */
+export interface ChainHead {
+    /** seq of the last appended record (-1 if the chain is empty). */
+    readonly seq: number;
+    /** hash of the last appended record (GENESIS_HASH if empty). */
+    readonly hash: string;
+    /** ISO timestamp the head was last updated. */
+    readonly updatedAt: string;
+}
+/** Hook invoked after the head advances. Default is a no-op (local-only). */
+export type AnchorHook = (head: ChainHead) => void;
+/** Options for the audit chain. */
+export interface AuditChainOptions {
+    /** HMAC signing key. When omitted, records are hashed but not HMAC-signed. */
+    readonly key?: Buffer;
+    /**
+     * Directory holding the rotation-independent head-anchor. Defaults to the log
+     * file's directory. The anchor file itself is `<dataDir>/chainHead.json` when
+     * dataDir is given, else `<logPath>.head`.
+     */
+    readonly dataDir?: string;
+    /**
+     * Remote-anchor seam. Called (best-effort) after each head advance with the
+     * new head. Default no-op keeps the chain local-only. An enterprise build can
+     * publish the head to Threat Cloud here to close the same-user-key gap.
+     */
+    readonly anchor?: AnchorHook;
+}
+/** Append-only tamper-evident JSONL chain over a single logical log file. */
+export declare class AuditChain {
+    private readonly logPath;
+    private readonly headPath;
+    private readonly key;
+    private readonly anchor;
+    private head;
+    constructor(logPath: string, opts?: AuditChainOptions);
+    /**
+     * Append a payload as a new chained record and persist it. Returns the record.
+     *
+     * Fail-open on WRITE error: a broken audit file must never brick the guarded
+     * path. Append errors log loudly to stderr; the record is still returned so
+     * the caller proceeds.
+     */
+    append<T>(payload: T): ChainedRecord<T>;
+    /**
+     * Read every record across the active file + rotated files, oldest first,
+     * using a streaming reader (line-by-line, memory-bounded). Chained lines parse
+     * to ChainedRecord; legacy un-chained lines are preserved verbatim as their
+     * parsed object so verify() can classify them as the 'unchained-legacy' prefix.
+     * The element type is `unknown` because the suffix may mix both (callers cast
+     * + filter; verify() accepts unknown[]).
+     */
+    readAll(): Promise<ChainedRecord[]>;
+    /**
+     * Verify the durable chain end-to-end. Detects edits, deletions, insertions,
+     * reorders (all 'hash-break'/'seq-gap'), bad HMAC, and tail truncation
+     * (head-anchor seq strictly greater than the last on-disk record seq).
+     */
+    verify(): Promise<VerifyResult>;
+    /** Current persisted chain head. The no-op anchor seam reads this. */
+    getHead(): ChainHead;
+    /**
+     * Carry the chain across a log rotation. The caller (ReportAgent) renames the
+     * active file out of the way; the head-anchor already holds the rotated-out
+     * file's last hash, so the NEXT append's prevHash chains to it automatically.
+     * This is a no-op marker for clarity + future hooks — the head is the source
+     * of truth, so rotation needs no special chain handling here.
+     */
+    noteRotation(): void;
+    private writeHead;
+    /**
+     * Load the head-anchor. If it is missing or stale (file exists but anchor
+     * absent), self-heal by streaming the file to recompute the true head and
+     * warn loudly.
+     */
+    private loadOrHealHead;
+    private tryReadHead;
+    /** Synchronous head recompute from the last on-disk record (self-heal path). */
+    private recomputeHeadSync;
+    private safeAnchor;
+    /** Active file first, then rotated files in OLDEST-first order? No: we want
+     * oldest-first overall so the chain reads in append order. Rotation produces
+     * events.jsonl (newest) + events.jsonl.1 (older) + ... so oldest is highest N. */
+    private orderedLogFiles;
+    private rotatedFiles;
+    private streamFile;
+}
+//# sourceMappingURL=audit-chain.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"audit-chain.d.ts","sourceRoot":"","sources":["../../src/audit/audit-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAeH,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,YAAY,EAClB,MAAM,iBAAiB,CAAC;AAIzB,8EAA8E;AAC9E,MAAM,WAAW,SAAS;IACxB,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,6EAA6E;AAC7E,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,SAAS,KAAK,IAAI,CAAC;AAEnD,mCAAmC;AACnC,MAAM,WAAW,iBAAiB;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;CAC9B;AAID,6EAA6E;AAC7E,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAa;IACpC,OAAO,CAAC,IAAI,CAAY;gBAEZ,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB;IAiBzD;;;;;;OAMG;IACH,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;IA8BvC;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC;IASzC;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,YAAY,CAAC;IA6BrC,sEAAsE;IACtE,OAAO,IAAI,SAAS;IAQpB;;;;;;OAMG;IACH,YAAY,IAAI,IAAI;IAUpB,OAAO,CAAC,SAAS;IAMjB;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAkCtB,OAAO,CAAC,WAAW;IAkBnB,gFAAgF;IAChF,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,UAAU;IAalB;;sFAEkF;IAClF,OAAO,CAAC,eAAe;IAOvB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,UAAU;CAuBnB"}

package/dist/audit/audit-chain.js

@@ -0,0 +1,316 @@
+/**
+ * AuditChain — durable, append-only, tamper-evident JSONL log.
+ *
+ * Wraps a JSONL file so every appended line is a {@link ChainedRecord}: linked
+ * to its predecessor by a SHA-256 hash and signed with a local HMAC key. The
+ * chain head (last seq + last hash) is persisted to a rotation-independent
+ * head-anchor so:
+ *   - a fresh process can append without rescanning the whole file, and
+ *   - tail truncation is detectable (head-anchor seq > last record seq).
+ *
+ * The chain SPANS rotation: when the active log is rotated out, the next file's
+ * first record links to the rotated-out file's last hash (carried in the
+ * head-anchor), so the chain is continuous across events.jsonl + events.jsonl.1.
+ *
+ * SCOPE — tamper EVIDENCE. The HMAC key is same-user-readable (see audit-key.ts
+ * and SECURITY.md). This detects tampering; it does not prevent it. The no-op
+ * anchor seam (getHead + optional anchor hook) is where remote anchoring — the
+ * enterprise upgrade that closes the same-user gap — plugs in.
+ *
+ * @module @panguard-ai/panguard-guard/audit/audit-chain
+ */
+import { appendFileSync, createReadStream, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync, } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { createLogger } from '@panguard-ai/core';
+import { GENESIS_HASH, computeHash, signHmac, verifyChain, } from './hash-chain.js';
+const logger = createLogger('panguard-guard:audit-chain');
+const EMPTY_HEAD = { seq: -1, hash: GENESIS_HASH, updatedAt: '' };
+/** Append-only tamper-evident JSONL chain over a single logical log file. */
+export class AuditChain {
+    logPath;
+    headPath;
+    key;
+    anchor;
+    head;
+    constructor(logPath, opts = {}) {
+        this.logPath = logPath;
+        this.key = opts.key;
+        this.anchor = opts.anchor ?? (() => { });
+        this.headPath = opts.dataDir
+            ? join(opts.dataDir, 'chainHead.json')
+            : `${logPath}.head`;
+        try {
+            mkdirSync(dirname(logPath), { recursive: true, mode: 0o700 });
+        }
+        catch {
+            // Directory may already exist.
+        }
+        this.head = this.loadOrHealHead();
+    }
+    /**
+     * Append a payload as a new chained record and persist it. Returns the record.
+     *
+     * Fail-open on WRITE error: a broken audit file must never brick the guarded
+     * path. Append errors log loudly to stderr; the record is still returned so
+     * the caller proceeds.
+     */
+    append(payload) {
+        const seq = this.head.seq + 1;
+        const ts = new Date().toISOString();
+        const prevHash = this.head.hash;
+        const hash = computeHash(prevHash, seq, ts, payload);
+        const record = {
+            seq,
+            ts,
+            payload,
+            prevHash,
+            hash,
+            ...(this.key ? { hmac: signHmac(hash, this.key) } : {}),
+        };
+        try {
+            appendFileSync(this.logPath, JSON.stringify(record) + '\n', 'utf-8');
+            const nextHead = { seq, hash, updatedAt: ts };
+            this.writeHead(nextHead);
+            this.head = nextHead;
+            this.safeAnchor(nextHead);
+        }
+        catch (err) {
+            // FAIL-OPEN on write: loud stderr, but the caller proceeds.
+            process.stderr.write(`[panguard-audit] append failed (continuing fail-open): ${errMsg(err)}\n`);
+        }
+        return record;
+    }
+    /**
+     * Read every record across the active file + rotated files, oldest first,
+     * using a streaming reader (line-by-line, memory-bounded). Chained lines parse
+     * to ChainedRecord; legacy un-chained lines are preserved verbatim as their
+     * parsed object so verify() can classify them as the 'unchained-legacy' prefix.
+     * The element type is `unknown` because the suffix may mix both (callers cast
+     * + filter; verify() accepts unknown[]).
+     */
+    async readAll() {
+        const out = [];
+        for (const filePath of this.orderedLogFiles()) {
+            const recs = await this.streamFile(filePath);
+            out.push(...recs);
+        }
+        return out;
+    }
+    /**
+     * Verify the durable chain end-to-end. Detects edits, deletions, insertions,
+     * reorders (all 'hash-break'/'seq-gap'), bad HMAC, and tail truncation
+     * (head-anchor seq strictly greater than the last on-disk record seq).
+     */
+    async verify() {
+        const records = await this.readAll();
+        const base = verifyChain(records, this.key);
+        // A content-level failure (hash-break / seq-gap / bad-hmac) is MORE specific
+        // than truncation and points at the exact bad index, so it wins. Truncation
+        // is reported only when the surviving content otherwise verifies — i.e. the
+        // chain is intact but shorter than the head-anchor remembers (tail removed).
+        const contentOk = base.ok || base.reason === 'unchained-legacy';
+        if (!contentOk)
+            return base;
+        // Truncation: the head-anchor remembers a seq the file no longer contains.
+        // Use the highest CHAINED seq on disk (legacy lines have no seq).
+        let lastSeq = -1;
+        for (const rec of records) {
+            if (isChainedRecord(rec) && rec.seq > lastSeq)
+                lastSeq = rec.seq;
+        }
+        if (this.head.seq > lastSeq) {
+            return {
+                ok: false,
+                verifiedCount: base.verifiedCount,
+                firstBadIndex: records.length,
+                reason: 'truncated',
+            };
+        }
+        return base;
+    }
+    /** Current persisted chain head. The no-op anchor seam reads this. */
+    getHead() {
+        return this.head;
+    }
+    // ---------------------------------------------------------------------------
+    // Rotation support — kept rotation-independent via the head-anchor.
+    // ---------------------------------------------------------------------------
+    /**
+     * Carry the chain across a log rotation. The caller (ReportAgent) renames the
+     * active file out of the way; the head-anchor already holds the rotated-out
+     * file's last hash, so the NEXT append's prevHash chains to it automatically.
+     * This is a no-op marker for clarity + future hooks — the head is the source
+     * of truth, so rotation needs no special chain handling here.
+     */
+    noteRotation() {
+        logger.info(`Audit chain spans rotation at seq ${this.head.seq} (head hash carried forward)`);
+    }
+    // ---------------------------------------------------------------------------
+    // Head-anchor persistence (tmp + rename, 0600).
+    // ---------------------------------------------------------------------------
+    writeHead(head) {
+        const tmp = `${this.headPath}.tmp`;
+        writeFileSync(tmp, JSON.stringify(head), { mode: 0o600 });
+        renameSync(tmp, this.headPath);
+    }
+    /**
+     * Load the head-anchor. If it is missing or stale (file exists but anchor
+     * absent), self-heal by streaming the file to recompute the true head and
+     * warn loudly.
+     */
+    loadOrHealHead() {
+        const onDisk = this.tryReadHead();
+        const fileExists = existsSync(this.logPath) || this.rotatedFiles().length > 0;
+        if (onDisk && !fileExists) {
+            // Anchor present but no log — treat anchor as authoritative (empty chain
+            // is the only safe assumption if files vanished; keep anchor for truncation
+            // detection on next verify()).
+            return onDisk;
+        }
+        if (!onDisk && !fileExists) {
+            return EMPTY_HEAD;
+        }
+        if (!onDisk && fileExists) {
+            // Self-heal: recompute head from the file.
+            logger.warn(`Audit head-anchor missing but log exists at ${this.logPath} — self-healing by stream`);
+            const healed = this.recomputeHeadSync();
+            try {
+                this.writeHead(healed);
+            }
+            catch (err) {
+                logger.warn(`Failed to persist healed head: ${errMsg(err)}`);
+            }
+            return healed;
+        }
+        // Both present — anchor is authoritative for appends. Truncation/edit is
+        // surfaced by verify(), not by silently trusting or rewriting here.
+        return onDisk;
+    }
+    tryReadHead() {
+        try {
+            if (!existsSync(this.headPath))
+                return null;
+            const raw = readFileSync(this.headPath, 'utf-8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.seq === 'number' && typeof parsed.hash === 'string') {
+                return {
+                    seq: parsed.seq,
+                    hash: parsed.hash,
+                    updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : '',
+                };
+            }
+        }
+        catch (err) {
+            logger.warn(`Audit head-anchor unreadable: ${errMsg(err)}`);
+        }
+        return null;
+    }
+    /** Synchronous head recompute from the last on-disk record (self-heal path). */
+    recomputeHeadSync() {
+        let lastChained = null;
+        for (const filePath of this.orderedLogFiles()) {
+            try {
+                const content = readFileSync(filePath, 'utf-8');
+                const lines = content.split('\n').filter((l) => l.trim().length > 0);
+                for (const line of lines) {
+                    const parsed = safeParse(line);
+                    if (parsed && isChainedRecord(parsed)) {
+                        lastChained = parsed;
+                    }
+                }
+            }
+            catch {
+                // skip unreadable file
+            }
+        }
+        if (!lastChained)
+            return EMPTY_HEAD;
+        return {
+            seq: lastChained.seq,
+            hash: lastChained.hash,
+            updatedAt: lastChained.ts,
+        };
+    }
+    safeAnchor(head) {
+        try {
+            this.anchor(head);
+        }
+        catch (err) {
+            // Anchoring is best-effort: never let it break the append path.
+            process.stderr.write(`[panguard-audit] anchor hook failed: ${errMsg(err)}\n`);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // File discovery + streaming (mirrors report-agent's stream pattern).
+    // ---------------------------------------------------------------------------
+    /** Active file first, then rotated files in OLDEST-first order? No: we want
+     * oldest-first overall so the chain reads in append order. Rotation produces
+     * events.jsonl (newest) + events.jsonl.1 (older) + ... so oldest is highest N. */
+    orderedLogFiles() {
+        const rotated = this.rotatedFiles(); // ascending by N: .1, .2, ...
+        // Oldest first = highest N first, then the active file last.
+        const oldestFirst = [...rotated].reverse().map((r) => r.file);
+        return [...oldestFirst, this.logPath];
+    }
+    rotatedFiles() {
+        const dir = dirname(this.logPath);
+        const base = basename(this.logPath);
+        try {
+            return readdirSync(dir)
+                .filter((f) => f.startsWith(base + '.'))
+                .map((f) => ({ file: join(dir, f), num: parseInt(f.slice(base.length + 1), 10) }))
+                .filter((x) => !isNaN(x.num))
+                .sort((a, b) => a.num - b.num);
+        }
+        catch {
+            return [];
+        }
+    }
+    streamFile(filePath) {
+        return new Promise((resolve) => {
+            const records = [];
+            try {
+                if (!existsSync(filePath)) {
+                    resolve(records);
+                    return;
+                }
+                const stream = createReadStream(filePath, { encoding: 'utf-8' });
+                const rl = createInterface({ input: stream, crlfDelay: Infinity });
+                rl.on('line', (line) => {
+                    if (!line.trim())
+                        return;
+                    const parsed = safeParse(line);
+                    // Push chained AND legacy lines verbatim; verify() classifies them.
+                    if (parsed)
+                        records.push(parsed);
+                });
+                rl.on('close', () => resolve(records));
+                rl.on('error', () => resolve(records));
+            }
+            catch {
+                resolve(records);
+            }
+        });
+    }
+}
+function safeParse(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+}
+function isChainedRecord(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');
+}
+function errMsg(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=audit-chain.js.map

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

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

package/dist/audit/audit-key.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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
+ */
+/**
+ * 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 declare function getAuditKey(): Promise<Buffer>;
+/** Reset the in-process cache. Test-only seam. */
+export declare function __resetAuditKeyCacheForTests(): void;
+//# sourceMappingURL=audit-key.d.ts.map

package/dist/audit/audit-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-key.d.ts","sourceRoot":"","sources":["../../src/audit/audit-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiCH;;;;;;GAMG;AACH,wBAAsB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAyBnD;AAwDD,kDAAkD;AAClD,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD"}