@cendor/acttrace 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+/**
+ * `@cendor/acttrace` — a tamper-evident, auto-populated audit log for AI decisions. The TS port of
+ * `cendor.acttrace` (regex/pattern detectors only; no Presidio).
+ *
+ * Construct an {@link AuditLog} and it **subscribes** to `@cendor/core`'s event stream: every
+ * instrumented model/tool call — and the context decisions `@cendor/contextkit` rides on the same
+ * stream — becomes an audit entry with no per-call wiring. You add only the explicit human-facing
+ * events (`decision`, `humanOversight`).
+ *
+ * Integrity comes from a **hash chain**, not a server: `entry.hash = sha256(prev_hash +
+ * canonical(entry))`, so editing any past entry breaks every entry after it. {@link verify} re-walks
+ * the chain offline. Byte-conformant with the Python implementation: the canonical bytes that are
+ * hashed (and the HMAC inputs) are identical across languages.
+ */
+import { DETECTORS, type Detector, detectors, registerDetector } from './detectors.js';
+import { PolicyViolation, guard } from './guard.js';
+import { nerAvailable, nerRedactor } from './ner.js';
+import { LOCALE_PACKS, enableEntropyDetector, enableLocalePack } from './packs.js';
+import { Finding, Policy, redact, scan } from './policy.js';
+import { type PyValue } from './pyjson.js';
+import { type ChainStorage } from './storage.js';
+export { DETECTORS, registerDetector, detectors, Policy, Finding, scan, redact, guard, PolicyViolation, enableLocalePack, enableEntropyDetector, LOCALE_PACKS, nerAvailable, nerRedactor, };
+export type { Detector };
+/** The `prev_hash` of the first entry: 64 ASCII zeros. */
+export declare const GENESIS: string;
+/**
+ * Warned when `AuditLog({ maxEntries })` is set without `path`. Bounding the in-memory ring relies on
+ * the file as the source of truth; without a path, evicted entries are lost entirely.
+ */
+export declare class BoundedMemoryWithoutPathWarning extends Error {
+    constructor(message: string);
+}
+/** Frameworks with a bundled (starting-template) control mapping for {@link AuditLog.export}. */
+export declare function frameworks(): string[];
+/** `sha256(prev_hash + canonical({payload, seq, ts, type}))` — prev_hash TEXT-prepended, 4 keys. */
+export declare function chainHash(prevHash: string, seq: PyValue, ts: PyValue, etype: PyValue, payload: PyValue): string;
+/** HMAC over an export `_meta` header's four completeness fields (entries, head_hash, risk_tier, system). */
+export declare function metaSignature(key: string | Uint8Array, meta: {
+    system?: PyValue;
+    risk_tier?: PyValue;
+    head_hash?: PyValue;
+    entries?: PyValue;
+}): string;
+/** One link in the hash chain. Field order == on-disk key order. */
+export declare class AuditEntry {
+    readonly seq: number | bigint;
+    readonly ts: string;
+    readonly type: string;
+    readonly payload: PyValue;
+    readonly prev_hash: string;
+    readonly hash: string;
+    readonly sig: string;
+    constructor(seq: number | bigint, ts: string, type: string, payload: PyValue, prev_hash: string, hash: string, sig?: string);
+}
+export declare function defaultRedactor(obj: unknown): unknown;
+export interface FlagOptions {
+    action?: string;
+    severity?: string;
+    data?: unknown;
+    /** Extra payload fields (Python `**fields`), e.g. `{ auto: true }`. */
+    extra?: Record<string, unknown>;
+}
+export interface AuditLogOptions {
+    riskTier?: string;
+    path?: string | null;
+    signingKey?: string | Uint8Array | null;
+    redact?: boolean;
+    redactor?: ((obj: unknown) => unknown) | null;
+    flagOnRedact?: boolean;
+    policy?: Policy | null;
+    maxEntries?: number | null;
+    /** Advanced: override the chain storage backend (defaults to fs when `path` is set, else memory). */
+    storage?: ChainStorage;
+}
+/** A hash-chained, append-only, auto-populating audit log. */
+export declare class AuditLog {
+    readonly system: string;
+    readonly riskTier: string;
+    entries: AuditEntry[];
+    private readonly _signingKey;
+    private readonly _redact;
+    private readonly _policy;
+    private readonly _redactor;
+    private readonly _flagOnRedact;
+    private readonly _maxEntries;
+    private readonly _path;
+    private readonly _storage;
+    private _seq;
+    private _evictedFromMemory;
+    private _head;
+    constructor(system: string, opts?: AuditLogOptions);
+    /** The current chain head hash. Capture it to later assert completeness via `verify`. */
+    get head(): string;
+    /** Entries evicted from the in-memory ring by `maxEntries` (0 if unbounded). Never left the chain. */
+    get evictedFromMemory(): number;
+    private now;
+    /** @internal Append one chain link. Also invoked by {@link Decision}. */
+    _append(etype: string, payload: Record<string, unknown>): AuditEntry;
+    private readonly _onEvent;
+    /** Stop subscribing to the core event stream and close the log file handle (idempotent). */
+    detach(): void;
+    /**
+     * Group a unit of work. Auto-captured calls inside the async callback are tagged with this
+     * decision (via an `AsyncLocalStorage` scope). Returns the callback's result.
+     */
+    decision<T>(cb: (d: Decision) => T | Promise<T>, opts?: {
+        input?: unknown;
+        actor?: string;
+    }): Promise<T>;
+    /**
+     * Record a policy flag — a tamper-evident record that a data/usage policy fired. `action`/`severity`
+     * are normalized to lowercase; pass a category label in `data`, never the raw value. Auto-tags the
+     * active decision span.
+     */
+    flag(reason: string, opts?: FlagOptions): AuditEntry;
+    private entriesForExport;
+    private summary;
+    /** Write the chain as a JSONL evidence pack, optionally annotated with framework control IDs. */
+    export(path: string, framework?: string | null): void;
+}
+/** Handle for the active decision span (passed to the {@link AuditLog.decision} callback). */
+export declare class Decision {
+    readonly log: AuditLog;
+    readonly id: string;
+    constructor(log: AuditLog, id: string);
+    /** Record decision metadata (e.g. `{ model, prompt_id }`). */
+    record(fields: Record<string, unknown>): void;
+    /** Record an Art. 14-style human-oversight event: who reviewed, what action, and a note. */
+    humanOversight(reviewer: string, action: string, note?: string): void;
+    /** Record a policy flag tagged to this decision. Returns the chained {@link AuditEntry}. */
+    flag(reason: string, opts?: FlagOptions): AuditEntry;
+}
+export interface VerifyOptions {
+    key?: string | Uint8Array | null;
+    expectedHead?: string | null;
+    expectEntries?: number | null;
+}
+/**
+ * Re-walk the hash chain in a JSONL file. Returns `[ok, detail]`. Detects edits and deletions,
+ * including tail-truncation. Never throws on a missing/corrupt file — returns `[false, detail]`.
+ */
+export declare function verify(path: string, opts?: VerifyOptions): [boolean, string];
+/** `acttrace verify <path> [--key K] [--expect-head H] [--expect-entries N]`. Returns an exit code. */
+export declare function main(argv: string[]): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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