@schema-weaver/pg-connector 0.0.0-stage → 2.0.0

package/dist/cjs/audit/local-writer.d.ts

@@ -0,0 +1,255 @@
+import { AUDIT_HEAD_FILENAME, type ChainVerifyResult } from './chain';
+import { AuditEvent, AuditHead, AuditWriterHealth } from './types';
+export interface LocalWriterOptions {
+    dir: string;
+    /** Rotate the active log past this size. Default 10 MiB. */
+    maxFileSize?: number;
+    /** Number of rotated archives to keep. Default 10. */
+    maxArchiveFiles?: number;
+    /** Mode for the log files themselves. Default 0o600. */
+    fileMode?: number;
+    /**
+     * Mode for the audit **directory**. Default 0o700.
+     *
+     * This must be a directory mode. A directory at 0o600 has no execute bit, is
+     * therefore untraversable, and every write into it fails EACCES — which is how
+     * a clean install ended up with no audit trail at all (finding C-06).
+     */
+    dirMode?: number;
+    /** Group-commit interval for non-durable appends. Default 50ms. */
+    flushIntervalMs?: number;
+    /** Appends buffered before a group commit is forced. Default 256. */
+    batchSize?: number;
+}
+export interface AppendOptions {
+    /**
+     * When true (the default) the record is written and `fsync`'d before the
+     * returned promise resolves. `logSync()` depends on this; `log()` does not.
+     */
+    durable?: boolean;
+}
+export declare const ACTIVE_AUDIT_FILE = "audit.jsonl";
+/** Notified after a successful fsync with the newest durable record. */
+export type CommitListener = (last: AuditEvent | null, retainedFromSeq: number | null) => void;
+/**
+ * Append-only local audit writer with group commit.
+ *
+ * Durability contract:
+ *   - `append(event, { durable: true })` resolves only after the record has been
+ *     written and `fsync`'d. This is what `AuditSink.logSync()` relies on.
+ *   - `append(event, { durable: false })` resolves once the record has been
+ *     handed to the kernel; a group commit `fsync`s it within `flushIntervalMs`,
+ *     or immediately once `batchSize` records are buffered. This is what
+ *     `AuditSink.log()` uses.
+ *   - `flush()` forces the outstanding `fsync`; `close()` flushes, `fsync`s and
+ *     releases the handle. Both are safe to call more than once and safe to race
+ *     with `append()`: every mutating operation is serialised on one chain, so a
+ *     concurrent append either lands before the close or reopens afterwards. A
+ *     failure in either is reported through `getHealth()` and rethrown — never
+ *     swallowed into a "flushed OK".
+ *
+ * One long-lived handle replaces the previous open/fsync/close per event, and
+ * the `mkdir` + `stat` per event are gone from the hot path (finding M-05).
+ */
+export declare class LocalAuditWriter {
+    private readonly opts;
+    private readonly activePath;
+    private lastKnownSize;
+    /** Serialises mutating operations so fd/size/rotation state stays coherent. */
+    private opChain;
+    private handle;
+    private unflushedBytes;
+    private pendingRecords;
+    private flushTimer;
+    private lastError;
+    private lastErrorAt;
+    private lastWriteAt;
+    private dirMode;
+    private fileMode;
+    private ready;
+    private reportedError;
+    private rotations;
+    private eventsWritten;
+    private eventsFailed;
+    private bytesWritten;
+    private commitListener;
+    private lastAppended;
+    private retainedFromSeq;
+    constructor(opts: LocalWriterOptions);
+    get dir(): string;
+    get activeFilePath(): string;
+    /**
+     * Registers the durable-commit hook. `AuditSink` uses it to anchor the chain
+     * head at exactly the point where records became durable.
+     */
+    setCommitListener(fn: CommitListener | null): void;
+    /**
+     * Oldest sequence number still on disk, or null when no record is retained.
+     *
+     * Rotation keeps a bounded number of archives, so the oldest records are
+     * eventually evicted on purpose. Whole-log verification therefore starts at
+     * this sequence number rather than at the genesis hash (finding M-06/H-13
+     * interaction: an evicted archive used to make every later verify report a
+     * phantom `seq_gap`).
+     */
+    getRetentionFloor(): number | null;
+    append(event: AuditEvent, opts?: AppendOptions): Promise<void>;
+    /**
+     * Creates the audit directory (0o700, repairing a stuck 0o600 one) and opens
+     * the log file (0o600). Called before the chain head is anchored so a broken
+     * install is repaired before anything tries to use the directory.
+     */
+    prepare(): Promise<void>;
+    /** Forces an fsync of everything written but not yet committed. */
+    flush(): Promise<void>;
+    /**
+     * Flushes every buffered record, `fsync`s it, then closes the long-lived
+     * handle. The writer stays usable afterwards — a later `append()` reopens.
+     *
+     * Shutdown contract, and the reason the daemon may call it after a signal and
+     * again on an explicit stop:
+     *   - **Idempotent.** A second `close()` is a no-op that resolves: the handle
+     *     is cleared before it is closed, so the descriptor can never be closed
+     *     twice.
+     *   - **Nothing is buffered on return.** The group-commit timer is cancelled
+     *     first, so it cannot fire against a closed descriptor afterwards.
+     *   - **The handle is released even when the flush fails.** Otherwise a
+     *     failing fsync would leak the descriptor *and* hide behind a rejected
+     *     promise that a caller may not await. The flush error is reported through
+     *     `getHealth()` and rethrown; it is never turned into a fake "flushed OK".
+     */
+    close(): Promise<void>;
+    /** Rotates the active file. Chain continuity is the caller's to preserve. */
+    rotate(): Promise<void>;
+    getHealth(): AuditWriterHealth;
+    /**
+     * Loads every record of the log, oldest archive first.
+     *
+     * Kept for small callers (filters, tests). It materialises the whole history,
+     * so verification goes through {@link verifyAuditLog} instead of this
+     * (finding M-06).
+     */
+    readAll(opts?: {
+        limit?: number;
+    }): Promise<AuditEvent[]>;
+    /** Streams every record in chronological order, one record at a time. */
+    stream(opts?: {
+        maxRecords?: number;
+    }): AsyncGenerator<AuditEvent, void, void>;
+    /**
+     * Newest record of the newest non-empty log file.
+     *
+     * Startup chain recovery: the in-memory head is gone after a restart and
+     * `head.json` can be a tick behind the last durable append. Returns `null`
+     * when the log is empty or unreadable.
+     */
+    readTailEvent(maxBytes?: number): Promise<AuditEvent | null>;
+    private run;
+    private writeRecord;
+    private ensureReady;
+    /**
+     * Reads the sequence number of the oldest record still on disk.
+     *
+     * The oldest archive is `audit-<maxArchiveFiles>.jsonl` (higher index = older),
+     * and the floor only moves up: it is a promise about what the log retains, so
+     * it must never go backwards.
+     */
+    private refreshRetentionFloor;
+    /**
+     * Repairs a directory left untraversable by an older version. `mkdir` is a
+     * no-op when the directory already exists, so without this the wrong mode is
+     * sticky and every append keeps failing EACCES (finding C-06).
+     */
+    private repairDirMode;
+    private currentFileSize;
+    private flushNow;
+    /**
+     * A failure to anchor the head does not undo the records already on disk, so
+     * it is reported rather than thrown — but it is never swallowed either: the
+     * writer goes unhealthy and says so once.
+     */
+    private notifyCommit;
+    private scheduleFlush;
+    private cancelFlushTimer;
+    private rotateNow;
+    private closeHandle;
+    private dropHandle;
+    /**
+     * Records the failure and complains once per distinct error, so audit loss is
+     * loud without one stack trace per query.
+     */
+    private recordFailure;
+    private noteSuccess;
+}
+export interface VerifyAuditLogOptions {
+    /** Signing key. Defaults to `SW_AGENT_AUDIT_KEY` / `audit.key`. */
+    key?: Buffer | string;
+    /** Expected head. Defaults to `head.json` in `dir`; pass `null` to skip. */
+    head?: AuditHead | null;
+    /** Directory/keyfile to resolve the key from when `key` is omitted. */
+    keyDir?: string;
+    /** Stop after this many records. Guards against a runaway log. */
+    maxRecords?: number;
+    /** First sequence number the log must carry. Defaults to the head's retention floor, else 1. */
+    expectedSeq?: number;
+}
+export interface AuditLogVerification extends ChainVerifyResult {
+    /** Log files walked, oldest first. */
+    files: string[];
+    /** Records that were not parseable JSON. */
+    malformed_lines: number;
+    /** Files that exist but could not be read. */
+    unreadable_files: string[];
+    head_present: boolean;
+    chain_id: string | null;
+    /** Every anchor that was consulted, in the order given. */
+    anchor_sources: string[];
+    /** Which of them decided the verdict. */
+    anchor_source: string | null;
+}
+export interface VerifyStreamOptions {
+    /** Signing key. There is no unkeyed verification. */
+    key: Buffer | string;
+    /** Expected head. When omitted the stream is verified for internal consistency only. */
+    head?: AuditHead | null;
+    /** Sequence number the first record must carry. Default 1. */
+    expectedSeq?: number;
+    /** Hash the first record must chain from. Defaults to the genesis hash. */
+    expectedPrevHash?: string;
+    /** Chain id every record must carry. Default: pinned from the first record. */
+    chainId?: string;
+    /** Stop after this many records. */
+    maxRecords?: number;
+}
+/**
+ * Incremental verification of an ordered record stream, with early exit on the
+ * first bad record (finding M-06).
+ *
+ * Holds only the previous record's mac/seq, so peak memory is O(1) in the
+ * number of records. Anything that is not an object is treated as corruption
+ * rather than skipped: silently ignoring an unreadable line would let an
+ * attacker delete records that a partial write happened to break.
+ */
+export declare function verifyStream(source: AsyncIterable<unknown> | Iterable<unknown>, opts: VerifyStreamOptions): Promise<ChainVerifyResult>;
+/**
+ * Verifies the whole audit log as one chronological sequence across rotated
+ * files, anchored on the strongest available claim about where the chain ends.
+ *
+ * Two anchors are consulted: `head.json` inside the audit directory and the
+ * monotonic floor beside it. Either alone can be rolled back together with the
+ * log; the pair cannot, which is what makes a restored older copy detectable
+ * (finding C-05).
+ *
+ * The entry point CLI commands should call: it resolves the key, reads the
+ * anchors, streams the log in O(1) memory and early-exits on the first bad
+ * record (findings C-05, H-13, M-06).
+ */
+export declare function verifyAuditLog(dir: string, opts?: VerifyAuditLogOptions): Promise<AuditLogVerification>;
+export { AUDIT_HEAD_FILENAME };
+/**
+ * Re-exported so callers that already import from this module (setup paths,
+ * `doctor`, `init`) have one obvious entry point. The implementation lives in
+ * `./files` because it needs no writer state.
+ */
+export { AUDIT_DIR_MODE, AUDIT_FILE_MODE, ensureAuditDir, probeAuditDir, repairAuditDirMode, } from './files';
+//# sourceMappingURL=local-writer.d.ts.map

package/dist/cjs/audit/local-writer.d.ts.map

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