@connexum/ai-governance 1.0.0-beta.11

package/dist/retention/log-aggregators/datadog.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * DatadogRetentionAdapter -- P4-RET-04 Datadog retention API (AC 14)
+ *
+ * Wired 2026-05-02 per Thomas Layer 0 directive (F-NEW-CRIT-31).
+ *
+ * Configuration:
+ *   - DD_API_KEY: Datadog API key with logs_write permission
+ *   - DD_APP_KEY: Datadog application key
+ *   - DD_SITE: Datadog site (e.g. datadoghq.com, datadoghq.eu)
+ *   - DD_RETENTION_POLICY_MAP: JSON blob mapping tenantId -> policyId
+ *   - opts.baseUrl (test override): full base URL like http://127.0.0.1:18889
+ *
+ * Behavior:
+ *   - setTenantRetention(): PUT /api/v1/logs/config/retention-policy/<policyId>
+ *       { period_days: <days> }
+ *   - 10s default timeout, 1 retry on 5xx or network error.
+ *   - On final failure, dispatches to DLQ callback (if injected) and rethrows.
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatadogRetentionAdapter = void 0;
+const ADAPTER_TAG = 'datadog-retention';
+const DEFAULT_TIMEOUT_MS = 10_000;
+class DatadogRetentionAdapter {
+    aggregatorType = 'datadog';
+    apiKey;
+    appKey;
+    site;
+    baseUrl;
+    policyMap;
+    timeoutMs;
+    dlq;
+    fetchImpl;
+    constructor(opts) {
+        this.apiKey = opts?.apiKey ?? process.env.DD_API_KEY;
+        this.appKey = opts?.appKey ?? process.env.DD_APP_KEY;
+        this.site = opts?.site ?? process.env.DD_SITE ?? 'datadoghq.com';
+        this.baseUrl = opts?.baseUrl;
+        const rawMap = opts?.policyMap ??
+            (process.env.DD_RETENTION_POLICY_MAP
+                ? JSON.parse(process.env.DD_RETENTION_POLICY_MAP)
+                : {});
+        this.policyMap = new Map(Object.entries(rawMap));
+        this.timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.dlq = opts?.dlq;
+        this.fetchImpl = opts?.fetchImpl ?? globalThis.fetch;
+    }
+    async setTenantRetention(tenantId, days) {
+        if (!this.apiKey || !this.appKey) {
+            console.warn(`[${ADAPTER_TAG}] no credentials configured. Tenant=${tenantId}, days=${days}. ` +
+                `Set DD_API_KEY + DD_APP_KEY to enable.`);
+            return;
+        }
+        const policyId = this.policyMap.get(tenantId);
+        if (!policyId) {
+            console.warn(`[${ADAPTER_TAG}] no policyId mapped for tenant=${tenantId}. ` +
+                `Update DD_RETENTION_POLICY_MAP to enable.`);
+            return;
+        }
+        const base = this.baseUrl
+            ? this.baseUrl.replace(/\/$/, '')
+            : `https://api.${this.site}`;
+        const url = `${base}/api/v1/logs/config/retention-policy/${encodeURIComponent(policyId)}`;
+        const body = JSON.stringify({ period_days: days });
+        const headers = {
+            'DD-API-KEY': this.apiKey,
+            'DD-APPLICATION-KEY': this.appKey,
+            'Content-Type': 'application/json',
+        };
+        await this.dispatchWithRetry(tenantId, days, async () => {
+            return this.doFetch(url, { method: 'PUT', headers, body });
+        });
+    }
+    async getTenantRetention(tenantId) {
+        if (!this.apiKey || !this.appKey)
+            return null;
+        const policyId = this.policyMap.get(tenantId);
+        if (!policyId)
+            return null;
+        const base = this.baseUrl
+            ? this.baseUrl.replace(/\/$/, '')
+            : `https://api.${this.site}`;
+        const url = `${base}/api/v1/logs/config/retention-policy/${encodeURIComponent(policyId)}`;
+        try {
+            const res = await this.doFetch(url, {
+                method: 'GET',
+                headers: { 'DD-API-KEY': this.apiKey, 'DD-APPLICATION-KEY': this.appKey },
+            });
+            if (!res.ok)
+                return null;
+            const json = (await res.json());
+            return typeof json.period_days === 'number' ? json.period_days : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async doFetch(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await this.fetchImpl(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async dispatchWithRetry(tenantId, days, op) {
+        let lastErr;
+        for (let attempt = 1; attempt <= 2; attempt++) {
+            try {
+                const res = await op();
+                if (res.ok)
+                    return;
+                if (res.status >= 500 && attempt === 1) {
+                    lastErr = new Error(`Datadog retention API ${res.status} ${res.statusText}`);
+                    continue;
+                }
+                throw new Error(`Datadog retention API failed: ${res.status} ${res.statusText}`);
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt === 1 && this.isRetryable(err))
+                    continue;
+                break;
+            }
+        }
+        const errMsg = lastErr instanceof Error ? lastErr.message : String(lastErr);
+        if (this.dlq) {
+            this.dlq({
+                adapterType: this.aggregatorType,
+                tenantId,
+                days,
+                attempts: 2,
+                error: errMsg,
+                occurredAt: new Date().toISOString(),
+            });
+        }
+        console.error(`[${ADAPTER_TAG}] retention push failed after retry. tenant=${tenantId} days=${days} err=${errMsg}`);
+        throw lastErr instanceof Error ? lastErr : new Error(errMsg);
+    }
+    isRetryable(err) {
+        if (!(err instanceof Error))
+            return false;
+        return (err.name === 'AbortError' ||
+            err.message.includes('ECONNREFUSED') ||
+            err.message.includes('ECONNRESET') ||
+            err.message.includes('ETIMEDOUT') ||
+            err.message.includes('fetch failed'));
+    }
+}
+exports.DatadogRetentionAdapter = DatadogRetentionAdapter;
+//# sourceMappingURL=datadog.js.map

package/dist/retention/log-aggregators/datadog.js.map

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

package/dist/retention/log-aggregators/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Log aggregator retention adapters -- barrel export.
+ *
+ * @connexum/ai-governance
+ */
+export type { LogAggregatorRetention, ReconciliationResult } from './log-aggregator.js';
+export { NoOpRetentionAdapter, noOpRetentionAdapter } from './noop.js';
+export { SplunkRetentionAdapter } from './splunk.js';
+export type { RetentionDLQEntry, RetentionDLQCallback, SplunkRetentionAdapterOpts, } from './splunk.js';
+export { DatadogRetentionAdapter } from './datadog.js';
+export type { DatadogRetentionAdapterOpts } from './datadog.js';
+export { SentinelRetentionAdapter } from './sentinel.js';
+export type { SentinelRetentionAdapterOpts } from './sentinel.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/retention/log-aggregators/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/retention/log-aggregators/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,YAAY,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACvE,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,YAAY,EACV,iBAAiB,EACjB,oBAAoB,EACpB,0BAA0B,GAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,uBAAuB,EAAE,MAAM,cAAc,CAAC;AACvD,YAAY,EAAE,2BAA2B,EAAE,MAAM,cAAc,CAAC;AAChE,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC;AACzD,YAAY,EAAE,4BAA4B,EAAE,MAAM,eAAe,CAAC"}

package/dist/retention/log-aggregators/index.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * Log aggregator retention adapters -- barrel export.
+ *
+ * @connexum/ai-governance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentinelRetentionAdapter = exports.DatadogRetentionAdapter = exports.SplunkRetentionAdapter = exports.noOpRetentionAdapter = exports.NoOpRetentionAdapter = void 0;
+var noop_js_1 = require("./noop.js");
+Object.defineProperty(exports, "NoOpRetentionAdapter", { enumerable: true, get: function () { return noop_js_1.NoOpRetentionAdapter; } });
+Object.defineProperty(exports, "noOpRetentionAdapter", { enumerable: true, get: function () { return noop_js_1.noOpRetentionAdapter; } });
+var splunk_js_1 = require("./splunk.js");
+Object.defineProperty(exports, "SplunkRetentionAdapter", { enumerable: true, get: function () { return splunk_js_1.SplunkRetentionAdapter; } });
+var datadog_js_1 = require("./datadog.js");
+Object.defineProperty(exports, "DatadogRetentionAdapter", { enumerable: true, get: function () { return datadog_js_1.DatadogRetentionAdapter; } });
+var sentinel_js_1 = require("./sentinel.js");
+Object.defineProperty(exports, "SentinelRetentionAdapter", { enumerable: true, get: function () { return sentinel_js_1.SentinelRetentionAdapter; } });
+//# sourceMappingURL=index.js.map

package/dist/retention/log-aggregators/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/retention/log-aggregators/index.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;;AAGH,qCAAuE;AAA9D,+GAAA,oBAAoB,OAAA;AAAE,+GAAA,oBAAoB,OAAA;AACnD,yCAAqD;AAA5C,mHAAA,sBAAsB,OAAA;AAM/B,2CAAuD;AAA9C,qHAAA,uBAAuB,OAAA;AAEhC,6CAAyD;AAAhD,uHAAA,wBAAwB,OAAA"}

package/dist/retention/log-aggregators/log-aggregator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * LogAggregatorRetention -- P4-RET-04 Log aggregator retention interface (AC 14)
+ *
+ * Adapter interface implemented by each log aggregator backend.
+ * The reconciliation loop in governance-server queries PolicyMatrix per tenant
+ * and calls setTenantRetention() when the aggregator's current retention
+ * drifts from the matrix value.
+ *
+ * Concrete implementations:
+ *   - SplunkRetentionAdapter  (splunk.ts)  -- DEFERRED-SPLUNK-WIRE
+ *   - DatadogRetentionAdapter (datadog.ts) -- DEFERRED-DATADOG-WIRE
+ *   - SentinelRetentionAdapter(sentinel.ts)-- DEFERRED-SENTINEL-WIRE
+ *   - NoOpRetentionAdapter    (noop.ts)    -- default for tenants with no aggregator
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+/**
+ * Log aggregator retention adapter interface.
+ *
+ * Each concrete implementation wraps a specific aggregator's retention API.
+ * The governance server's reconciliation loop calls setTenantRetention() to
+ * push the resolved PolicyMatrix days to the aggregator.
+ */
+export interface LogAggregatorRetention {
+    /**
+     * Unique identifier for this aggregator type (e.g. 'splunk', 'datadog').
+     * Used in audit events and per-store coverage matrix.
+     */
+    readonly aggregatorType: string;
+    /**
+     * Set the log retention policy for a tenant to the given number of days.
+     *
+     * @param tenantId  Tenant whose logs are being configured.
+     * @param days      Retention period in days (from PolicyMatrix resolution).
+     * @returns         Promise resolving when the aggregator acknowledges the change.
+     * @throws          If the aggregator API call fails (non-retried in this cycle).
+     */
+    setTenantRetention(tenantId: string, days: number): Promise<void>;
+    /**
+     * Query the current retention setting for a tenant from the aggregator.
+     * Used by the reconciliation loop to detect drift.
+     *
+     * @param tenantId  Tenant to query.
+     * @returns         Current retention in days, or null if unknown.
+     */
+    getTenantRetention(tenantId: string): Promise<number | null>;
+}
+export interface ReconciliationResult {
+    tenantId: string;
+    aggregatorType: string;
+    previousDays: number | null;
+    targetDays: number;
+    /** Whether the aggregator value was updated during this reconciliation. */
+    updated: boolean;
+    /** Whether the aggregator is in drift (before the update). */
+    wasDrift: boolean;
+    reconciledAt: string;
+    error?: string;
+}
+//# sourceMappingURL=log-aggregator.d.ts.map

package/dist/retention/log-aggregators/log-aggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-aggregator.d.ts","sourceRoot":"","sources":["../../../src/retention/log-aggregators/log-aggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAEhC;;;;;;;OAOG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElE;;;;;;OAMG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC9D;AAMD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,8DAA8D;IAC9D,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/retention/log-aggregators/log-aggregator.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * LogAggregatorRetention -- P4-RET-04 Log aggregator retention interface (AC 14)
+ *
+ * Adapter interface implemented by each log aggregator backend.
+ * The reconciliation loop in governance-server queries PolicyMatrix per tenant
+ * and calls setTenantRetention() when the aggregator's current retention
+ * drifts from the matrix value.
+ *
+ * Concrete implementations:
+ *   - SplunkRetentionAdapter  (splunk.ts)  -- DEFERRED-SPLUNK-WIRE
+ *   - DatadogRetentionAdapter (datadog.ts) -- DEFERRED-DATADOG-WIRE
+ *   - SentinelRetentionAdapter(sentinel.ts)-- DEFERRED-SENTINEL-WIRE
+ *   - NoOpRetentionAdapter    (noop.ts)    -- default for tenants with no aggregator
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=log-aggregator.js.map

package/dist/retention/log-aggregators/log-aggregator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-aggregator.js","sourceRoot":"","sources":["../../../src/retention/log-aggregators/log-aggregator.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/retention/log-aggregators/noop.d.ts

@@ -0,0 +1,23 @@
+/**
+ * NoOpRetentionAdapter -- Default no-op adapter for tenants not using any
+ * log aggregator.
+ *
+ * setTenantRetention() resolves immediately without making any API call.
+ * getTenantRetention() returns null (unknown).
+ *
+ * This is the default adapter in the reconciliation loop when no aggregator
+ * is configured for a tenant.
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+import type { LogAggregatorRetention } from './log-aggregator.js';
+export declare class NoOpRetentionAdapter implements LogAggregatorRetention {
+    readonly aggregatorType = "noop";
+    setTenantRetention(_tenantId: string, _days: number): Promise<void>;
+    getTenantRetention(_tenantId: string): Promise<number | null>;
+}
+/** Singleton no-op adapter instance. */
+export declare const noOpRetentionAdapter: NoOpRetentionAdapter;
+//# sourceMappingURL=noop.d.ts.map

package/dist/retention/log-aggregators/noop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.d.ts","sourceRoot":"","sources":["../../../src/retention/log-aggregators/noop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAElE,qBAAa,oBAAqB,YAAW,sBAAsB;IACjE,QAAQ,CAAC,cAAc,UAAU;IAE3B,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAGpE;AAED,wCAAwC;AACxC,eAAO,MAAM,oBAAoB,sBAA6B,CAAC"}

package/dist/retention/log-aggregators/noop.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * NoOpRetentionAdapter -- Default no-op adapter for tenants not using any
+ * log aggregator.
+ *
+ * setTenantRetention() resolves immediately without making any API call.
+ * getTenantRetention() returns null (unknown).
+ *
+ * This is the default adapter in the reconciliation loop when no aggregator
+ * is configured for a tenant.
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noOpRetentionAdapter = exports.NoOpRetentionAdapter = void 0;
+class NoOpRetentionAdapter {
+    aggregatorType = 'noop';
+    async setTenantRetention(_tenantId, _days) {
+        // No-op: this tenant has no log aggregator configured.
+    }
+    async getTenantRetention(_tenantId) {
+        return null;
+    }
+}
+exports.NoOpRetentionAdapter = NoOpRetentionAdapter;
+/** Singleton no-op adapter instance. */
+exports.noOpRetentionAdapter = new NoOpRetentionAdapter();
+//# sourceMappingURL=noop.js.map

package/dist/retention/log-aggregators/noop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"noop.js","sourceRoot":"","sources":["../../../src/retention/log-aggregators/noop.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAIH,MAAa,oBAAoB;IACtB,cAAc,GAAG,MAAM,CAAC;IAEjC,KAAK,CAAC,kBAAkB,CAAC,SAAiB,EAAE,KAAa;QACvD,uDAAuD;IACzD,CAAC;IAED,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAVD,oDAUC;AAED,wCAAwC;AAC3B,QAAA,oBAAoB,GAAG,IAAI,oBAAoB,EAAE,CAAC"}

package/dist/retention/log-aggregators/sentinel.d.ts

@@ -0,0 +1,75 @@
+/**
+ * SentinelRetentionAdapter -- P4-RET-04 Azure Sentinel retention (AC 14)
+ *
+ * Wired 2026-05-02 per Thomas Layer 0 directive (F-NEW-CRIT-31).
+ *
+ * Configuration:
+ *   - AZURE_TENANT_ID: Azure AD tenant ID
+ *   - AZURE_CLIENT_ID: App registration client ID with Log Analytics Contributor
+ *   - AZURE_CLIENT_SECRET: Client secret
+ *   - AZURE_SUBSCRIPTION_ID: Azure subscription containing the workspaces
+ *   - SENTINEL_WORKSPACE_MAP: JSON blob mapping tenantId ->
+ *       { resourceGroupName, workspaceName }
+ *   - opts.armBaseUrl / opts.oauthBaseUrl (test overrides)
+ *
+ * Behavior:
+ *   1. Acquire OAuth2 token via client_credentials flow against
+ *      login.microsoftonline.com/<tenantId>/oauth2/v2.0/token
+ *   2. PATCH workspace at management.azure.com/.../workspaces/<ws>?api-version=2022-10-01
+ *      { properties: { retentionInDays: <days> } }
+ *   - 10s default timeout per call, 1 retry on 5xx or network error.
+ *   - Token cached in-process for ~50 minutes (default Azure lifetime is 60 min).
+ *   - On final failure, dispatches to DLQ callback (if injected) and rethrows.
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+import type { LogAggregatorRetention } from './log-aggregator.js';
+import type { RetentionDLQCallback } from './splunk.js';
+interface WorkspaceRef {
+    resourceGroupName: string;
+    workspaceName: string;
+}
+export interface SentinelRetentionAdapterOpts {
+    tenantId?: string;
+    clientId?: string;
+    clientSecret?: string;
+    subscriptionId?: string;
+    workspaceMap?: Record<string, WorkspaceRef>;
+    /** Test override: ARM base URL. Defaults to https://management.azure.com */
+    armBaseUrl?: string;
+    /** Test override: OAuth base URL. Defaults to https://login.microsoftonline.com */
+    oauthBaseUrl?: string;
+    timeoutMs?: number;
+    dlq?: RetentionDLQCallback;
+    fetchImpl?: typeof fetch;
+}
+export declare class SentinelRetentionAdapter implements LogAggregatorRetention {
+    readonly aggregatorType = "sentinel";
+    private readonly tenantId;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly subscriptionId;
+    private readonly workspaceMap;
+    private readonly armBaseUrl;
+    private readonly oauthBaseUrl;
+    private readonly timeoutMs;
+    private readonly dlq;
+    private readonly fetchImpl;
+    private cachedToken;
+    constructor(opts?: SentinelRetentionAdapterOpts);
+    setTenantRetention(tenantId: string, days: number): Promise<void>;
+    getTenantRetention(tenantId: string): Promise<number | null>;
+    /**
+     * Fetch a bearer token from Azure AD via client_credentials grant.
+     * Caches the token for TOKEN_TTL_MS.
+     * Exposed as protected so subclasses / tests can override if needed.
+     */
+    private getAccessToken;
+    private doFetch;
+    private dispatchWithRetry;
+    private isRetryable;
+}
+export {};
+//# sourceMappingURL=sentinel.d.ts.map

package/dist/retention/log-aggregators/sentinel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentinel.d.ts","sourceRoot":"","sources":["../../../src/retention/log-aggregators/sentinel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAQxD,UAAU,YAAY;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAOD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5C,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAC3B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,qBAAa,wBAAyB,YAAW,sBAAsB;IACrE,QAAQ,CAAC,cAAc,cAAc;IAErC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqB;IAC9C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAqB;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAqB;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA4B;IACzD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAmC;IACvD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC,OAAO,CAAC,WAAW,CAA4B;gBAEnC,IAAI,CAAC,EAAE,4BAA4B;IAmBzC,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IA0CjE,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgClE;;;;OAIG;YACW,cAAc;YAwCd,OAAO;YAUP,iBAAiB;IAsC/B,OAAO,CAAC,WAAW;CAUpB"}

package/dist/retention/log-aggregators/sentinel.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * SentinelRetentionAdapter -- P4-RET-04 Azure Sentinel retention (AC 14)
+ *
+ * Wired 2026-05-02 per Thomas Layer 0 directive (F-NEW-CRIT-31).
+ *
+ * Configuration:
+ *   - AZURE_TENANT_ID: Azure AD tenant ID
+ *   - AZURE_CLIENT_ID: App registration client ID with Log Analytics Contributor
+ *   - AZURE_CLIENT_SECRET: Client secret
+ *   - AZURE_SUBSCRIPTION_ID: Azure subscription containing the workspaces
+ *   - SENTINEL_WORKSPACE_MAP: JSON blob mapping tenantId ->
+ *       { resourceGroupName, workspaceName }
+ *   - opts.armBaseUrl / opts.oauthBaseUrl (test overrides)
+ *
+ * Behavior:
+ *   1. Acquire OAuth2 token via client_credentials flow against
+ *      login.microsoftonline.com/<tenantId>/oauth2/v2.0/token
+ *   2. PATCH workspace at management.azure.com/.../workspaces/<ws>?api-version=2022-10-01
+ *      { properties: { retentionInDays: <days> } }
+ *   - 10s default timeout per call, 1 retry on 5xx or network error.
+ *   - Token cached in-process for ~50 minutes (default Azure lifetime is 60 min).
+ *   - On final failure, dispatches to DLQ callback (if injected) and rethrows.
+ *
+ * Spec: P4-RET-01 Section 2.4, AC 14
+ *
+ * @connexum/ai-governance
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SentinelRetentionAdapter = void 0;
+const ADAPTER_TAG = 'sentinel-retention';
+const DEFAULT_TIMEOUT_MS = 10_000;
+const TOKEN_TTL_MS = 50 * 60 * 1000;
+const ARM_DEFAULT = 'https://management.azure.com';
+const OAUTH_DEFAULT = 'https://login.microsoftonline.com';
+class SentinelRetentionAdapter {
+    aggregatorType = 'sentinel';
+    tenantId;
+    clientId;
+    clientSecret;
+    subscriptionId;
+    workspaceMap;
+    armBaseUrl;
+    oauthBaseUrl;
+    timeoutMs;
+    dlq;
+    fetchImpl;
+    cachedToken = null;
+    constructor(opts) {
+        this.tenantId = opts?.tenantId ?? process.env.AZURE_TENANT_ID;
+        this.clientId = opts?.clientId ?? process.env.AZURE_CLIENT_ID;
+        this.clientSecret = opts?.clientSecret ?? process.env.AZURE_CLIENT_SECRET;
+        this.subscriptionId = opts?.subscriptionId ?? process.env.AZURE_SUBSCRIPTION_ID;
+        const rawMap = opts?.workspaceMap ??
+            (process.env.SENTINEL_WORKSPACE_MAP
+                ? JSON.parse(process.env.SENTINEL_WORKSPACE_MAP)
+                : {});
+        this.workspaceMap = new Map(Object.entries(rawMap));
+        this.armBaseUrl = (opts?.armBaseUrl ?? ARM_DEFAULT).replace(/\/$/, '');
+        this.oauthBaseUrl = (opts?.oauthBaseUrl ?? OAUTH_DEFAULT).replace(/\/$/, '');
+        this.timeoutMs = opts?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.dlq = opts?.dlq;
+        this.fetchImpl = opts?.fetchImpl ?? globalThis.fetch;
+    }
+    async setTenantRetention(tenantId, days) {
+        if (!this.tenantId ||
+            !this.clientId ||
+            !this.clientSecret ||
+            !this.subscriptionId) {
+            console.warn(`[${ADAPTER_TAG}] no Azure credentials. Tenant=${tenantId}, days=${days}. ` +
+                `Set AZURE_TENANT_ID + AZURE_CLIENT_ID + AZURE_CLIENT_SECRET + AZURE_SUBSCRIPTION_ID to enable.`);
+            return;
+        }
+        const workspace = this.workspaceMap.get(tenantId);
+        if (!workspace) {
+            console.warn(`[${ADAPTER_TAG}] no workspace mapped for tenant=${tenantId}. ` +
+                `Update SENTINEL_WORKSPACE_MAP to enable.`);
+            return;
+        }
+        await this.dispatchWithRetry(tenantId, days, async () => {
+            const token = await this.getAccessToken();
+            const url = `${this.armBaseUrl}/subscriptions/${encodeURIComponent(this.subscriptionId)}` +
+                `/resourceGroups/${encodeURIComponent(workspace.resourceGroupName)}` +
+                `/providers/Microsoft.OperationalInsights/workspaces/${encodeURIComponent(workspace.workspaceName)}` +
+                `?api-version=2022-10-01`;
+            const body = JSON.stringify({ properties: { retentionInDays: days } });
+            return this.doFetch(url, {
+                method: 'PATCH',
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                    'Content-Type': 'application/json',
+                },
+                body,
+            });
+        });
+    }
+    async getTenantRetention(tenantId) {
+        if (!this.tenantId ||
+            !this.clientId ||
+            !this.clientSecret ||
+            !this.subscriptionId) {
+            return null;
+        }
+        const workspace = this.workspaceMap.get(tenantId);
+        if (!workspace)
+            return null;
+        try {
+            const token = await this.getAccessToken();
+            const url = `${this.armBaseUrl}/subscriptions/${encodeURIComponent(this.subscriptionId)}` +
+                `/resourceGroups/${encodeURIComponent(workspace.resourceGroupName)}` +
+                `/providers/Microsoft.OperationalInsights/workspaces/${encodeURIComponent(workspace.workspaceName)}` +
+                `?api-version=2022-10-01`;
+            const res = await this.doFetch(url, {
+                method: 'GET',
+                headers: { Authorization: `Bearer ${token}` },
+            });
+            if (!res.ok)
+                return null;
+            const json = (await res.json());
+            const v = json.properties?.retentionInDays;
+            return typeof v === 'number' ? v : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Fetch a bearer token from Azure AD via client_credentials grant.
+     * Caches the token for TOKEN_TTL_MS.
+     * Exposed as protected so subclasses / tests can override if needed.
+     */
+    async getAccessToken() {
+        const now = Date.now();
+        if (this.cachedToken && this.cachedToken.expiresAt > now + 60_000) {
+            return this.cachedToken.token;
+        }
+        const url = `${this.oauthBaseUrl}/${encodeURIComponent(this.tenantId)}/oauth2/v2.0/token`;
+        const form = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: this.clientId,
+            client_secret: this.clientSecret,
+            scope: 'https://management.azure.com/.default',
+        });
+        const res = await this.doFetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: form.toString(),
+        });
+        if (!res.ok) {
+            throw new Error(`Azure AD token endpoint failed: ${res.status} ${res.statusText}`);
+        }
+        const json = (await res.json());
+        if (!json.access_token) {
+            throw new Error('Azure AD token endpoint returned no access_token');
+        }
+        const lifetimeMs = typeof json.expires_in === 'number'
+            ? Math.min(json.expires_in * 1000, TOKEN_TTL_MS)
+            : TOKEN_TTL_MS;
+        this.cachedToken = {
+            token: json.access_token,
+            expiresAt: now + lifetimeMs,
+        };
+        return json.access_token;
+    }
+    async doFetch(url, init) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            return await this.fetchImpl(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async dispatchWithRetry(tenantId, days, op) {
+        let lastErr;
+        for (let attempt = 1; attempt <= 2; attempt++) {
+            try {
+                const res = await op();
+                if (res.ok)
+                    return;
+                if (res.status >= 500 && attempt === 1) {
+                    lastErr = new Error(`Sentinel retention API ${res.status} ${res.statusText}`);
+                    continue;
+                }
+                throw new Error(`Sentinel retention API failed: ${res.status} ${res.statusText}`);
+            }
+            catch (err) {
+                lastErr = err;
+                if (attempt === 1 && this.isRetryable(err))
+                    continue;
+                break;
+            }
+        }
+        const errMsg = lastErr instanceof Error ? lastErr.message : String(lastErr);
+        if (this.dlq) {
+            this.dlq({
+                adapterType: this.aggregatorType,
+                tenantId,
+                days,
+                attempts: 2,
+                error: errMsg,
+                occurredAt: new Date().toISOString(),
+            });
+        }
+        console.error(`[${ADAPTER_TAG}] retention push failed after retry. tenant=${tenantId} days=${days} err=${errMsg}`);
+        throw lastErr instanceof Error ? lastErr : new Error(errMsg);
+    }
+    isRetryable(err) {
+        if (!(err instanceof Error))
+            return false;
+        return (err.name === 'AbortError' ||
+            err.message.includes('ECONNREFUSED') ||
+            err.message.includes('ECONNRESET') ||
+            err.message.includes('ETIMEDOUT') ||
+            err.message.includes('fetch failed'));
+    }
+}
+exports.SentinelRetentionAdapter = SentinelRetentionAdapter;
+//# sourceMappingURL=sentinel.js.map