atabey 0.0.37 → 0.1.0

package/dist/shared/src/modules/observability/audit-chain.js

@@ -0,0 +1,262 @@
+/**
+ * Tamper-evident audit hash chain helpers (Phase 1.4).
+ *
+ * Chain: each entry stores prev_hash (previous entry hash or GENESIS) and hash = SHA-256(payload).
+ * Any mutation of historical rows fails verification.
+ */
+import crypto from "crypto";
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { databaseHolder } from "../storage/database.js";
+export const AUDIT_CHAIN_GENESIS = "GENESIS";
+/**
+ * Resolve the HMAC key for the audit chain (memoized).
+ *
+ * Priority:
+ *   1. ATABEY_AUDIT_HMAC_KEY env var (recommended for production / secret managers)
+ *   2. `.atabey/audit-hmac.key` next to the SQLite DB (created 0600 on first use)
+ *   3. null → falls back to unkeyed SHA-256 (insecure; warned once)
+ *
+ * A key is required for the chain to be genuinely tamper-evident. Without it,
+ * anyone who can write the DB can also recompute the hashes.
+ */
+let cachedKey;
+let warnedUnkeyed = false;
+const inMemoryAnchors = new Map();
+/** Directory holding the HMAC key and chain anchor (next to the SQLite DB), or null for :memory: DBs. */
+function resolveChainDir() {
+    const envDir = process.env.ATABEY_TEST_DIR || process.env.ATABEY_FRAMEWORK_DIR;
+    if (envDir && envDir.trim()) {
+        return envDir.trim();
+    }
+    try {
+        const db = databaseHolder.getDB();
+        if (db) {
+            if (db.memory === true || db.name === ":memory:" || db.name === "") {
+                return null;
+            }
+            if (typeof db.name === "string" && db.name) {
+                return path.dirname(db.name);
+            }
+        }
+    }
+    catch {
+        /* DB not initialized yet */
+    }
+    return process.env.VITEST
+        ? path.join(os.tmpdir(), `atabey-vitest-worker-${process.pid}`, ".atabey")
+        : path.join(process.cwd(), ".atabey");
+}
+export function resolveAuditChainKey() {
+    if (cachedKey !== undefined)
+        return cachedKey;
+    const envKey = process.env.ATABEY_AUDIT_HMAC_KEY;
+    if (envKey && envKey.trim()) {
+        cachedKey = Buffer.from(envKey.trim(), "utf8");
+        return cachedKey;
+    }
+    const dir = resolveChainDir();
+    if (!dir) {
+        cachedKey = null;
+        return cachedKey;
+    }
+    const keyFile = path.join(dir, "audit-hmac.key");
+    try {
+        if (fs.existsSync(keyFile)) {
+            cachedKey = fs.readFileSync(keyFile);
+            return cachedKey;
+        }
+        if (process.env.ATABEY_AUDIT_HMAC_AUTOCREATE !== "false" && !process.env.VITEST) {
+            fs.mkdirSync(dir, { recursive: true });
+            const generated = crypto.randomBytes(32);
+            fs.writeFileSync(keyFile, generated, { mode: 0o600 });
+            cachedKey = generated;
+            return cachedKey;
+        }
+    }
+    catch {
+        /* fall through to unkeyed */
+    }
+    cachedKey = null;
+    return cachedKey;
+}
+/** Test helper — clears the memoized key. */
+export function clearAuditChainKeyCache() {
+    cachedKey = undefined;
+    warnedUnkeyed = false;
+    inMemoryAnchors.clear();
+}
+/**
+ * Keyed digest for audit chain entries.
+ * Uses HMAC-SHA256 when a key is available; otherwise falls back to plain
+ * SHA-256 with a one-time warning (degraded, not recommended).
+ */
+export function chainDigest(payload) {
+    const key = resolveAuditChainKey();
+    if (key) {
+        return crypto.createHmac("sha256", key).update(payload, "utf8").digest("hex");
+    }
+    if (!warnedUnkeyed) {
+        warnedUnkeyed = true;
+        process.stderr.write("[AUDIT] WARNING: no audit HMAC key configured — chain is unkeyed (SHA-256 only). " +
+            "Set ATABEY_AUDIT_HMAC_KEY or allow key-file creation for tamper-evidence.\n");
+    }
+    return crypto.createHash("sha256").update(payload, "utf8").digest("hex");
+}
+/** @deprecated Use chainDigest() — unkeyed SHA-256 is not tamper-evident. */
+export function sha256Hex(payload) {
+    return crypto.createHash("sha256").update(payload, "utf8").digest("hex");
+}
+function anchorFile(dir, name) {
+    return path.join(dir, `audit-chain-${name}.anchor.json`);
+}
+export function writeChainAnchor(name, tip, count) {
+    const data = { tip, count, updatedAt: new Date().toISOString() };
+    const dir = resolveChainDir();
+    if (!dir) {
+        inMemoryAnchors.set(name, data);
+        return;
+    }
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(anchorFile(dir, name), JSON.stringify(data), { mode: 0o600 });
+    }
+    catch {
+        /* non-fatal: verification will report "no anchor" */
+    }
+}
+export function readChainAnchor(name) {
+    const dir = resolveChainDir();
+    if (!dir) {
+        return inMemoryAnchors.get(name) ?? null;
+    }
+    try {
+        const f = anchorFile(dir, name);
+        if (!fs.existsSync(f))
+            return null;
+        return JSON.parse(fs.readFileSync(f, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function clearChainAnchor(name) {
+    inMemoryAnchors.delete(name);
+    const dir = resolveChainDir();
+    if (!dir)
+        return;
+    try {
+        const f = anchorFile(dir, name);
+        if (fs.existsSync(f))
+            fs.unlinkSync(f);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * Canonical payload for agent execution logs (Storage.saveLog).
+ *
+ * v2: fields are length-delimited via JSON to remove `|`-join boundary
+ * ambiguity (previously agent="a|b" collided with action="b|c"). Changing this
+ * invalidates verification of rows written by older (v1) builds.
+ */
+export function buildAgentLogChainPayload(fields) {
+    return JSON.stringify([
+        "v2",
+        fields.prevHash,
+        fields.agent,
+        fields.action,
+        fields.traceId,
+        fields.status,
+        fields.summary,
+        fields.timestamp,
+    ]);
+}
+/**
+ * Canonical payload for structured Audit.log entries (v2, length-delimited).
+ */
+export function buildStructuredAuditChainPayload(fields) {
+    return JSON.stringify([
+        "v2",
+        fields.prevHash,
+        fields.agent,
+        fields.action,
+        fields.status,
+        fields.traceId,
+        fields.timestamp,
+        fields.detailsJson,
+        fields.errorMessage,
+    ]);
+}
+/**
+ * Verify a sequence of rows already ordered by id ASC.
+ * `computePayload(row, prevHash)` must rebuild the exact string used at insert time.
+ *
+ * @param options.digest        keyed digest used at insert time (default: chainDigest)
+ * @param options.expectedTip   last appended hash (from an external anchor) — detects truncation
+ * @param options.expectedCount number of chained rows expected — detects deletion at the tail
+ */
+export function verifyHashChain(rows, computePayload, options = {}) {
+    const digest = options.digest ?? chainDigest;
+    let expectedPrev = rows.length > 0 ? (rows[0].prev_hash || AUDIT_CHAIN_GENESIS) : AUDIT_CHAIN_GENESIS;
+    let checked = 0;
+    for (const row of rows) {
+        checked++;
+        const prev = row.prev_hash || "";
+        if (prev !== expectedPrev) {
+            return {
+                valid: false,
+                checked,
+                failedLogId: row.id,
+                reason: `prev_hash mismatch at row ${row.id}`,
+                tip: "A log was deleted, reordered, or inserted out of chain order.",
+            };
+        }
+        if (!row.hash) {
+            return {
+                valid: false,
+                checked,
+                failedLogId: row.id,
+                reason: `Missing hash at row ${row.id}`,
+                tip: "Legacy row without hash; re-seed or accept and re-hash from tip.",
+            };
+        }
+        const payload = computePayload(row, prev);
+        const calculated = digest(payload);
+        if (calculated !== row.hash) {
+            return {
+                valid: false,
+                checked,
+                failedLogId: row.id,
+                reason: `Hash corruption at row ${row.id}`,
+                tip: "Row content was modified after append (or the HMAC key changed).",
+            };
+        }
+        expectedPrev = row.hash;
+    }
+    // Truncation detection against an external anchor.
+    if (options.expectedCount !== undefined && rows.length < options.expectedCount) {
+        return {
+            valid: false,
+            checked,
+            reason: `Chain truncated: expected ${options.expectedCount} rows, found ${rows.length}.`,
+            tip: "Tail audit rows were deleted after append.",
+        };
+    }
+    if (options.expectedTip !== undefined && rows.length > 0) {
+        const actualTip = rows[rows.length - 1].hash;
+        if (actualTip !== options.expectedTip) {
+            return {
+                valid: false,
+                checked,
+                failedLogId: rows[rows.length - 1].id,
+                reason: "Chain tip does not match the anchored tip.",
+                tip: "Rows were appended/replaced outside the audited writer, or deleted.",
+            };
+        }
+    }
+    return { valid: true, checked, tip: rows.length > 0 ? rows[rows.length - 1].hash ?? undefined : undefined };
+}
+//# sourceMappingURL=audit-chain.js.map

package/dist/shared/src/modules/observability/audit-chain.js.map

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

package/dist/shared/src/modules/observability/audit.d.ts

@@ -0,0 +1,121 @@
+/**
+ * [AUDIT] Structured Audit Log Service
+ *
+ * Records all critical operations in structured JSON format to SQLite.
+ * Queryable, filterable, and traceable.
+ *
+ * [KVKK/GDPR] GDPR and KVKK Art. 4, 5, 11, 12 compliant:
+ * - Sensitive data automatically masked (PII masking)
+ * - Data retention limited (TTL)
+ * - Data subject rights supported (erasure, query)
+ *
+ * Usage:
+ *   Audit.log("user.create", "SUCCESS", { userId: "usr_123" });
+ *   Audit.query({ action: "user.create", status: "FAILED" });
+ */
+import { type ChainVerifyResult } from "./audit-chain.js";
+export type AuditStatus = "SUCCESS" | "FAILED" | "BLOCKED" | "APPROVED" | "REJECTED";
+export type DataCategory = "OPERATIONAL" | "USER_DATA" | "API_CALL" | "SECURITY" | "COMPLIANCE";
+export interface AuditEntry {
+    id?: number;
+    timestamp: string;
+    action: string;
+    status: AuditStatus;
+    agent: string;
+    traceId?: string;
+    details?: Record<string, unknown>;
+    errorMessage?: string;
+    durationMs?: number;
+    dataCategory?: DataCategory;
+    /** [KVKK] Data retention period (days). null = unlimited (not recommended) */
+    retentionDays?: number;
+    /** Tamper-evident chain (Phase 1.4) */
+    prev_hash?: string;
+    hash?: string;
+}
+export declare class Audit {
+    private static TABLE;
+    /** Out-of-DB anchor file name for the structured audit chain. */
+    private static ANCHOR_NAME;
+    /** [KVKK] Default data retention period: 30 days */
+    private static DEFAULT_RETENTION_DAYS;
+    /** [KVKK] Maximum retention for sensitive categories: 90 days */
+    private static MAX_RETENTION_DAYS;
+    static initialize(): void;
+    /**
+     * Refresh the out-of-DB chain anchor after a legitimate deletion
+     * (retention / right-to-erasure). Without this, legitimate deletions would
+     * be indistinguishable from tampering.
+     */
+    private static refreshAnchor;
+    /**
+     * Logs a structured audit entry.
+     * [KVKK] Sensitive data is automatically masked.
+     */
+    static log(action: string, status: AuditStatus, options?: {
+        agent?: string;
+        traceId?: string;
+        details?: Record<string, unknown>;
+        errorMessage?: string;
+        durationMs?: number;
+        dataCategory?: DataCategory;
+        /** [KVKK] Custom retention period (days). Default: 30 */
+        retentionDays?: number;
+    }): void;
+    /**
+     * Verify tamper-evident chain for structured audit_log table.
+     */
+    static verifyIntegrity(): ChainVerifyResult;
+    /**
+     * Queries audit logs with filters.
+     */
+    static query(options?: {
+        action?: string;
+        status?: AuditStatus;
+        agent?: string;
+        traceId?: string;
+        dataCategory?: DataCategory;
+        limit?: number;
+        offset?: number;
+        since?: string;
+        until?: string;
+    }): AuditEntry[];
+    /**
+   * [KVKK Art. 11] Deletes records upon data subject request.
+   * Clears all records matching a given traceId or agent.
+   *
+   * @param filter Which records to delete
+   * @returns Number of deleted records
+   */
+    static deleteByFilter(filter: {
+        traceId?: string;
+        agent?: string;
+        action?: string;
+        olderThanDays?: number;
+    }): number;
+    /**
+     * [KVKK/GDPR] Cleans expired records.
+     * Operates based on each audit record's retentionDays field.
+     * Can be auto-triggered by cron job or each Audit.log() call.
+     *
+     * @returns Number of cleaned records
+     */
+    static cleanExpired(): number;
+    /**
+     * Returns audit statistics.
+     */
+    static getStats(): {
+        total: number;
+        byStatus: Record<string, number>;
+        byAction: Record<string, number>;
+        byCategory: Record<string, number>;
+        recentErrors: AuditEntry[];
+        expiredCount: number;
+    };
+    /**
+     * [KVKK Art. 7] Clears all audit records.
+     * Used under the "Right to Erasure" provision.
+     * Only authorized users may call this.
+     */
+    static clearAll(confirmationCode: string): number;
+}