@wildo-ai/saas-models 1.1.4 → 1.1.6

package/dist/esm/compliance/audit-trails/audit-trail-config.shared.schemas.d.ts

@@ -1,13 +1,17 @@
 import { z } from 'zod';
+import { type ApplicationRetentionSchedule } from '../privacy/retention-schedule.shared.schemas';
 /**
  * @wildo_source:part:start saas.models.audit.trail-config facet:layer:shared facet:audience:app-developer
  *
  * `AuditTrailConfig` — application-level operator-tunable configuration for the
  * compliance audit-trail subsystem.
  *
- * ⚠️ **`archiveAfterDays` IS the opt-in, and it never deletes anything.** While it is unset the
- * archival job still runs and does nothing, and every audit record stays in the primary store
- * indefinitely — so an application that has never set it is accumulating, not rotating.
+ * ⚠️ **The archival horizon comes from ONE of two places, and it never deletes anything.** It is
+ * `archiveAfterDays` when set, otherwise the declared `dataRetention[AUDIT_LOGS]` period (#1613,
+ * `resolveAuditArchiveAfterDays`); an application that declares both with different values is refused at
+ * startup, so the two cannot disagree. With NEITHER, the archival job still runs and does nothing, and every
+ * audit record stays in the primary store indefinitely — accumulating, not rotating. Declaring the
+ * `AUDIT_LOGS` period therefore turns archival ON.
  *
  * Setting it does not shrink the primary store either. `AUDIT_LOGS` is immutable by invariant: it
  * has no UPDATE and no DELETE, so records older than the horizon are COPIED to durable archival
@@ -43,9 +47,7 @@ import { z } from 'zod';
  * remain in the always-on `AUDIT_LOGS` store (and, when configured, in the
  * append-only immudb tamper-proof ledger). This is why the field is named
  * `archiveAfterDays` and not `retentionDays`: nothing is retained-then-deleted;
- * the value is purely the ARCHIVAL HORIZON. (The distinction mirrors the
- * `archiveAfterDays` vs `retentionDays` split in the general
- * `DataRetentionPolicySchema`.)
+ * the value is purely the ARCHIVAL HORIZON.
  *
  * --------------------------------------------------------------------------
  * Why the config lives in `saas-models` (not next to the batch)
@@ -72,10 +74,39 @@ import { z } from 'zod';
  * schema must not read. The schema `.min(1)` is the absolute floor; the runtime
  * validator raises it to 365 outside development.
  */
+/** Access posture for the deployment-wide audit viewer; tenant-scoped audit access is unchanged. */
+export declare enum AuditApplicationReadAccess {
+    /** Ordinary production default: the existing application super-administrator role is sufficient. Every cross-tenant read remains observed. */
+    ROLE_BASED = "role-based",
+    /** Additionally require a live time-bound application-wide grant approved by a different platform administrator. */
+    INDEPENDENT_APPROVAL = "independent-approval"
+}
 export declare const AuditTrailConfigSchema: z.ZodObject<{
+    applicationReadAccess: z.ZodOptional<z.ZodEnum<typeof AuditApplicationReadAccess>>;
     archiveAfterDays: z.ZodOptional<z.ZodNumber>;
     allowPrivateNetworkSiemCollectors: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type AuditTrailConfig = z.infer<typeof AuditTrailConfigSchema>;
 /** @wildo_source:part:end saas.models.audit.trail-config */
+/**
+ * The effective audit archival horizon: the explicit `archiveAfterDays`, else the declared
+ * `AUDIT_LOGS` period, else `undefined` (archival off). The one reader every consumer goes through —
+ * the archive batch and the startup floor — so the derived value is floored exactly like an authored one.
+ *
+ * The explicit value wins only because startup has refused it whenever it DISAGREES with a declared
+ * period ({@link findAuditArchiveHorizonConflict}).
+ */
+export declare function resolveAuditArchiveAfterDays(auditTrail: {
+    readonly archiveAfterDays?: number;
+} | undefined, schedule: ApplicationRetentionSchedule | undefined): number | undefined;
+/**
+ * The disagreement startup refuses: an explicit `archiveAfterDays` beside a declared `AUDIT_LOGS` period
+ * of a different length. `undefined` when there is none.
+ */
+export declare function findAuditArchiveHorizonConflict(auditTrail: {
+    readonly archiveAfterDays?: number;
+} | undefined, schedule: ApplicationRetentionSchedule | undefined): {
+    readonly archiveAfterDays: number;
+    readonly auditLogsRetentionDays: number;
+} | undefined;
 //# sourceMappingURL=audit-trail-config.shared.schemas.d.ts.map

package/dist/esm/compliance/audit-trails/audit-trail-config.shared.schemas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-trail-config.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../src/compliance/audit-trails/audit-trail-config.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,eAAO,MAAM,sBAAsB;;;iBAsDjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,4DAA4D"}
+{"version":3,"file":"audit-trail-config.shared.schemas.d.ts","sourceRoot":"","sources":["../../../../../src/compliance/audit-trails/audit-trail-config.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAsB,KAAK,4BAA4B,EAAE,MAAM,8CAA8C,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,oGAAoG;AACpG,oBAAY,0BAA0B;IACpC,8IAA8I;IAC9I,UAAU,eAAe;IACzB,oHAAoH;IACpH,oBAAoB,yBAAyB;CAC9C;AAED,eAAO,MAAM,sBAAsB;;;;iBAkEjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AACtE,4DAA4D;AAE5D;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EAC9D,QAAQ,EAAE,4BAA4B,GAAG,SAAS,GACjD,MAAM,GAAG,SAAS,CAEpB;AAED;;;GAGG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,EAC9D,QAAQ,EAAE,4BAA4B,GAAG,SAAS,GACjD;IAAE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK5F"}

package/dist/esm/compliance/audit-trails/audit-trail-config.shared.schemas.js

@@ -1,13 +1,17 @@
 import { z } from 'zod';
+import { DataRetentionClass } from '../privacy/retention-schedule.shared.schemas.js';
 /**
  * @wildo_source:part:start saas.models.audit.trail-config facet:layer:shared facet:audience:app-developer
  *
  * `AuditTrailConfig` — application-level operator-tunable configuration for the
  * compliance audit-trail subsystem.
  *
- * ⚠️ **`archiveAfterDays` IS the opt-in, and it never deletes anything.** While it is unset the
- * archival job still runs and does nothing, and every audit record stays in the primary store
- * indefinitely — so an application that has never set it is accumulating, not rotating.
+ * ⚠️ **The archival horizon comes from ONE of two places, and it never deletes anything.** It is
+ * `archiveAfterDays` when set, otherwise the declared `dataRetention[AUDIT_LOGS]` period (#1613,
+ * `resolveAuditArchiveAfterDays`); an application that declares both with different values is refused at
+ * startup, so the two cannot disagree. With NEITHER, the archival job still runs and does nothing, and every
+ * audit record stays in the primary store indefinitely — accumulating, not rotating. Declaring the
+ * `AUDIT_LOGS` period therefore turns archival ON.
  *
  * Setting it does not shrink the primary store either. `AUDIT_LOGS` is immutable by invariant: it
  * has no UPDATE and no DELETE, so records older than the horizon are COPIED to durable archival
@@ -43,9 +47,7 @@ import { z } from 'zod';
  * remain in the always-on `AUDIT_LOGS` store (and, when configured, in the
  * append-only immudb tamper-proof ledger). This is why the field is named
  * `archiveAfterDays` and not `retentionDays`: nothing is retained-then-deleted;
- * the value is purely the ARCHIVAL HORIZON. (The distinction mirrors the
- * `archiveAfterDays` vs `retentionDays` split in the general
- * `DataRetentionPolicySchema`.)
+ * the value is purely the ARCHIVAL HORIZON.
  *
  * --------------------------------------------------------------------------
  * Why the config lives in `saas-models` (not next to the batch)
@@ -72,7 +74,22 @@ import { z } from 'zod';
  * schema must not read. The schema `.min(1)` is the absolute floor; the runtime
  * validator raises it to 365 outside development.
  */
+/** Access posture for the deployment-wide audit viewer; tenant-scoped audit access is unchanged. */
+export var AuditApplicationReadAccess;
+(function (AuditApplicationReadAccess) {
+    /** Ordinary production default: the existing application super-administrator role is sufficient. Every cross-tenant read remains observed. */
+    AuditApplicationReadAccess["ROLE_BASED"] = "role-based";
+    /** Additionally require a live time-bound application-wide grant approved by a different platform administrator. */
+    AuditApplicationReadAccess["INDEPENDENT_APPROVAL"] = "independent-approval";
+})(AuditApplicationReadAccess || (AuditApplicationReadAccess = {}));
 export const AuditTrailConfigSchema = z.object({
+    /**
+     * Application audit viewer admission. Omitted means ROLE_BASED in every environment.
+     * INDEPENDENT_APPROVAL adds the existing independently approved elevation; it never substitutes for roles.
+     * Both policies keep immutable records, application/tenant filters and read observations. This does not
+     * change access to other application-wide resources or per-tenant administrative grants.
+     */
+    applicationReadAccess: z.enum(AuditApplicationReadAccess).optional(),
     /**
      * Age (in days) beyond which audit records are EXPORTED to durable archival
      * file-storage artifacts by the `compliance:audit-logs-archive` cron batch.
@@ -81,9 +98,14 @@ export const AuditTrailConfigSchema = z.object({
      * archival horizon only (see the block-level JSDoc on why the field is
      * `archiveAfterDays`, not `retentionDays`).
      *
-     * OPTIONAL — when omitted (`undefined`), NO archival runs and audit records
-     * are retained in the primary store indefinitely. This is the compliance-safe
-     * default: an operator must explicitly opt in before any archival happens.
+     * OPTIONAL, and **single-sourced to the retention schedule (#1613)**: when
+     * omitted, the horizon is the application's declared
+     * `dataRetention[AUDIT_LOGS].retentionDays` — the period the audit trail is
+     * kept in the live store before it is archived — so one number answers "how
+     * long is the audit trail kept" instead of two that drift. Setting both to
+     * DIFFERENT values is refused at startup. With neither declared, NO archival
+     * runs and audit records stay in the primary store indefinitely. Resolve it
+     * through {@link resolveAuditArchiveAfterDays}, never by reading this field.
      *
      * Bounds: min 1 / max 2555 (≈ 7 years), mirroring the SSO
      * `auditConfig.retentionDays` precedent. A production floor of 365 days is
@@ -127,4 +149,26 @@ export const AuditTrailConfigSchema = z.object({
     allowPrivateNetworkSiemCollectors: z.boolean().optional(),
 });
 /** @wildo_source:part:end saas.models.audit.trail-config */
+/**
+ * The effective audit archival horizon: the explicit `archiveAfterDays`, else the declared
+ * `AUDIT_LOGS` period, else `undefined` (archival off). The one reader every consumer goes through —
+ * the archive batch and the startup floor — so the derived value is floored exactly like an authored one.
+ *
+ * The explicit value wins only because startup has refused it whenever it DISAGREES with a declared
+ * period ({@link findAuditArchiveHorizonConflict}).
+ */
+export function resolveAuditArchiveAfterDays(auditTrail, schedule) {
+    return auditTrail?.archiveAfterDays ?? schedule?.[DataRetentionClass.AUDIT_LOGS]?.retentionDays;
+}
+/**
+ * The disagreement startup refuses: an explicit `archiveAfterDays` beside a declared `AUDIT_LOGS` period
+ * of a different length. `undefined` when there is none.
+ */
+export function findAuditArchiveHorizonConflict(auditTrail, schedule) {
+    const archiveAfterDays = auditTrail?.archiveAfterDays;
+    const auditLogsRetentionDays = schedule?.[DataRetentionClass.AUDIT_LOGS]?.retentionDays;
+    if (archiveAfterDays === undefined || auditLogsRetentionDays === undefined)
+        return undefined;
+    return archiveAfterDays === auditLogsRetentionDays ? undefined : { archiveAfterDays, auditLogsRetentionDays };
+}
 //# sourceMappingURL=audit-trail-config.shared.schemas.js.map

package/dist/esm/compliance/audit-trails/audit-trail-config.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"audit-trail-config.shared.schemas.js","sourceRoot":"","sources":["../../../../src/compliance/audit-trails/audit-trail-config.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C;;;;;;;;;;;;;;;;OAgBG;IACH,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,iCAAiC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC1D,CAAC,CAAC;AAGH,4DAA4D","sourcesContent":["import { z } from 'zod';\n\n/**\n * @wildo_source:part:start saas.models.audit.trail-config facet:layer:shared facet:audience:app-developer\n *\n * `AuditTrailConfig` — application-level operator-tunable configuration for the\n * compliance audit-trail subsystem.\n *\n * ⚠️ **`archiveAfterDays` IS the opt-in, and it never deletes anything.** While it is unset the\n * archival job still runs and does nothing, and every audit record stays in the primary store\n * indefinitely — so an application that has never set it is accumulating, not rotating.\n *\n * Setting it does not shrink the primary store either. `AUDIT_LOGS` is immutable by invariant: it\n * has no UPDATE and no DELETE, so records older than the horizon are COPIED to durable archival\n * artifacts in file storage while the originals remain. The field is named `archiveAfterDays` rather\n * than `retentionDays` for exactly that reason — nothing is retained-then-deleted, and an operator\n * expecting the primary store to shrink has misread it.\n *\n * The decision is taken at each tick from live configuration, so changing the value takes effect\n * without a restart, and a misconfigured value cannot orphan the schedule. An application that turns\n * this on after it already has aged data seeds the archive with a one-off wider look-back run.\n *\n * Phase 5 / F1 (audit-logging plan). Mirrors {@link DataSeedingConfigSchema} /\n * {@link LifecycleConfigSchema} in shape and intent: a small, OPTIONAL block on\n * the shared application configuration ({@link AppConfiguration_Shared_Schema})\n * that tunes an engine-owned background batch — here the\n * `compliance:audit-logs-archive` cron batch — without forking the factory's\n * built-in defaults.\n *\n * It also carries the subsystem's one EGRESS posture\n * ({@link allowPrivateNetworkSiemCollectors}), which belongs to the operator rather\n * than to the tenant who authors a SIEM destination — see that field's own JSDoc\n * for why the distinction is the whole control.\n *\n * --------------------------------------------------------------------------\n * Archival, NOT deletion — audit logs are immutable\n * --------------------------------------------------------------------------\n * The `AUDIT_LOGS` resource is IMMUTABLE by invariant (G5): its\n * `coreOperations` are `READ | LIST | SEARCH | CREATE` — there is NO `UPDATE`\n * and NO `DELETE`. The retention mechanism therefore NEVER removes audit\n * records from the primary store. Instead, records older than\n * {@link archiveAfterDays} are EXPORTED (copied) to durable off-DB archival\n * artifacts in file storage by the archival batch, while the original rows\n * remain in the always-on `AUDIT_LOGS` store (and, when configured, in the\n * append-only immudb tamper-proof ledger). This is why the field is named\n * `archiveAfterDays` and not `retentionDays`: nothing is retained-then-deleted;\n * the value is purely the ARCHIVAL HORIZON. (The distinction mirrors the\n * `archiveAfterDays` vs `retentionDays` split in the general\n * `DataRetentionPolicySchema`.)\n *\n * --------------------------------------------------------------------------\n * Why the config lives in `saas-models` (not next to the batch)\n * --------------------------------------------------------------------------\n * The runtime wiring (`StartApplicationBackendService.initialize`) and the\n * batch body read operator-tunable configuration EXCLUSIVELY from\n * `appConfigService.config?.*` — i.e. the {@link AppConfiguration_Shared_Schema}\n * aggregate. Placing the schema here (rather than in `saas-backend-lib` next to\n * the batch) keeps every operator-tunable engine batch symmetric with\n * `dataSeeding` / `lifecycle` and gives one source of truth the batch factory\n * and the startup validator can both import (`saas-models` cannot depend on\n * `saas-backend-lib` — the dependency arrow points the other way).\n *\n * --------------------------------------------------------------------------\n * Bounds + production floor\n * --------------------------------------------------------------------------\n * {@link archiveAfterDays} bounds mirror the SSO `auditConfig.retentionDays`\n * precedent (min 1 day, max 2555 ≈ 7 years). A stricter PRODUCTION FLOOR (365\n * days) is enforced at boot by\n * `ApplicationStartupConfigValidatorService.validate()` — NOT by a schema-level\n * `.min()` and NOT by a Zod `.superRefine()`, because the environment\n * (development vs staging/production) is a RUNTIME signal\n * (`process.env.APPLICATION_ENV`) that a pure, environment-agnostic shared\n * schema must not read. The schema `.min(1)` is the absolute floor; the runtime\n * validator raises it to 365 outside development.\n */\nexport const AuditTrailConfigSchema = z.object({\n  /**\n   * Age (in days) beyond which audit records are EXPORTED to durable archival\n   * file-storage artifacts by the `compliance:audit-logs-archive` cron batch.\n   *\n   * Records are NEVER deleted from the primary `AUDIT_LOGS` store — this is the\n   * archival horizon only (see the block-level JSDoc on why the field is\n   * `archiveAfterDays`, not `retentionDays`).\n   *\n   * OPTIONAL — when omitted (`undefined`), NO archival runs and audit records\n   * are retained in the primary store indefinitely. This is the compliance-safe\n   * default: an operator must explicitly opt in before any archival happens.\n   *\n   * Bounds: min 1 / max 2555 (≈ 7 years), mirroring the SSO\n   * `auditConfig.retentionDays` precedent. A production floor of 365 days is\n   * enforced at boot (see block-level JSDoc) — setting a value below 365 in a\n   * staging/production environment fails startup with a CONFIGURATION error.\n   */\n  archiveAfterDays: z.number().int().min(1).max(2555).optional(),\n\n  /**\n   * May a SIEM export deliver to a collector on an address the public internet cannot reach?\n   *\n   * ── What it is for ─────────────────────────────────────────────────────────\n   * A SIEM webhook URL is TENANT-authored (`siemExportConfig.webhookUrl`, written by an organization\n   * administrator) and the delivery worker POSTs to it with the deployment's own network position.\n   * That is a server-side request forgery primitive by construction, and the classic targets are the\n   * ones every guard in `security/ssrf` names: `169.254.169.254`, loopback admin ports, RFC 1918.\n   *\n   * But one legitimate deployment shape genuinely lives there: a self-hosted collector (Splunk,\n   * QRadar, a syslog bridge) on the same private network as the application. Refusing that\n   * unconditionally would not be \"safe\" — it would break a supported topology and push operators to\n   * a worse workaround.\n   *\n   * ── Why it is an OPERATOR field and not a tenant field ─────────────────────\n   * It lives HERE, on the application configuration the deployment operator authors, and NOT on\n   * `SiemExportConfigBaseSchema`, which the tenant authors. A tenant-settable \"allow private\n   * addresses\" flag would hand the party supplying the attacker-controlled URL the switch that\n   * disarms the guard aimed at them — an SSRF bypass with a checkbox. The operator declares the\n   * network posture; the tenant chooses a destination within it.\n   *\n   * ── Why OPTIONAL rather than `.default(false)` ─────────────────────────────\n   * The reader tests for `=== true`, so absent is refuse, and the fail-closed posture is the one you\n   * get by doing nothing — the same contract `archiveAfterDays` states one field above. It is left\n   * without a Zod default so `AuditTrailConfigSchema.parse({})` still round-trips as `{}`; an\n   * always-materialised `false` would make the block non-empty for every application that never\n   * authored it, which is what the pin below this schema's tests exists to prevent.\n   *\n   * ── What it does NOT relax ─────────────────────────────────────────────────\n   * Not the scheme policy, not the credentials-in-URL refusal, and not the PINNING: the delivery\n   * still connects only to an address classified at the moment of connection. It widens WHICH\n   * addresses are admitted, never whether the admitted address is the one connected to.\n   */\n  allowPrivateNetworkSiemCollectors: z.boolean().optional(),\n});\n\nexport type AuditTrailConfig = z.infer<typeof AuditTrailConfigSchema>;\n/** @wildo_source:part:end saas.models.audit.trail-config */\n"]}
+{"version":3,"file":"audit-trail-config.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/audit-trails/audit-trail-config.shared.schemas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAqC,MAAM,8CAA8C,CAAC;AAErH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,oGAAoG;AACpG,MAAM,CAAN,IAAY,0BAKX;AALD,WAAY,0BAA0B;IACpC,8IAA8I;IAC9I,uDAAyB,CAAA;IACzB,oHAAoH;IACpH,2EAA6C,CAAA;AAC/C,CAAC,EALW,0BAA0B,KAA1B,0BAA0B,QAKrC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C;;;;;OAKG;IACH,qBAAqB,EAAE,CAAC,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC,QAAQ,EAAE;IACpE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE;IAE9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACH,iCAAiC,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC1D,CAAC,CAAC;AAGH,4DAA4D;AAE5D;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAC1C,UAA8D,EAC9D,QAAkD;IAElD,OAAO,UAAU,EAAE,gBAAgB,IAAI,QAAQ,EAAE,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;AAClG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,+BAA+B,CAC7C,UAA8D,EAC9D,QAAkD;IAElD,MAAM,gBAAgB,GAAG,UAAU,EAAE,gBAAgB,CAAC;IACtD,MAAM,sBAAsB,GAAG,QAAQ,EAAE,CAAC,kBAAkB,CAAC,UAAU,CAAC,EAAE,aAAa,CAAC;IACxF,IAAI,gBAAgB,KAAK,SAAS,IAAI,sBAAsB,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC7F,OAAO,gBAAgB,KAAK,sBAAsB,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,CAAC;AAChH,CAAC","sourcesContent":["import { z } from 'zod';\n\nimport { DataRetentionClass, type ApplicationRetentionSchedule } from '../privacy/retention-schedule.shared.schemas';\n\n/**\n * @wildo_source:part:start saas.models.audit.trail-config facet:layer:shared facet:audience:app-developer\n *\n * `AuditTrailConfig` — application-level operator-tunable configuration for the\n * compliance audit-trail subsystem.\n *\n * ⚠️ **The archival horizon comes from ONE of two places, and it never deletes anything.** It is\n * `archiveAfterDays` when set, otherwise the declared `dataRetention[AUDIT_LOGS]` period (#1613,\n * `resolveAuditArchiveAfterDays`); an application that declares both with different values is refused at\n * startup, so the two cannot disagree. With NEITHER, the archival job still runs and does nothing, and every\n * audit record stays in the primary store indefinitely — accumulating, not rotating. Declaring the\n * `AUDIT_LOGS` period therefore turns archival ON.\n *\n * Setting it does not shrink the primary store either. `AUDIT_LOGS` is immutable by invariant: it\n * has no UPDATE and no DELETE, so records older than the horizon are COPIED to durable archival\n * artifacts in file storage while the originals remain. The field is named `archiveAfterDays` rather\n * than `retentionDays` for exactly that reason — nothing is retained-then-deleted, and an operator\n * expecting the primary store to shrink has misread it.\n *\n * The decision is taken at each tick from live configuration, so changing the value takes effect\n * without a restart, and a misconfigured value cannot orphan the schedule. An application that turns\n * this on after it already has aged data seeds the archive with a one-off wider look-back run.\n *\n * Phase 5 / F1 (audit-logging plan). Mirrors {@link DataSeedingConfigSchema} /\n * {@link LifecycleConfigSchema} in shape and intent: a small, OPTIONAL block on\n * the shared application configuration ({@link AppConfiguration_Shared_Schema})\n * that tunes an engine-owned background batch — here the\n * `compliance:audit-logs-archive` cron batch — without forking the factory's\n * built-in defaults.\n *\n * It also carries the subsystem's one EGRESS posture\n * ({@link allowPrivateNetworkSiemCollectors}), which belongs to the operator rather\n * than to the tenant who authors a SIEM destination — see that field's own JSDoc\n * for why the distinction is the whole control.\n *\n * --------------------------------------------------------------------------\n * Archival, NOT deletion — audit logs are immutable\n * --------------------------------------------------------------------------\n * The `AUDIT_LOGS` resource is IMMUTABLE by invariant (G5): its\n * `coreOperations` are `READ | LIST | SEARCH | CREATE` — there is NO `UPDATE`\n * and NO `DELETE`. The retention mechanism therefore NEVER removes audit\n * records from the primary store. Instead, records older than\n * {@link archiveAfterDays} are EXPORTED (copied) to durable off-DB archival\n * artifacts in file storage by the archival batch, while the original rows\n * remain in the always-on `AUDIT_LOGS` store (and, when configured, in the\n * append-only immudb tamper-proof ledger). This is why the field is named\n * `archiveAfterDays` and not `retentionDays`: nothing is retained-then-deleted;\n * the value is purely the ARCHIVAL HORIZON.\n *\n * --------------------------------------------------------------------------\n * Why the config lives in `saas-models` (not next to the batch)\n * --------------------------------------------------------------------------\n * The runtime wiring (`StartApplicationBackendService.initialize`) and the\n * batch body read operator-tunable configuration EXCLUSIVELY from\n * `appConfigService.config?.*` — i.e. the {@link AppConfiguration_Shared_Schema}\n * aggregate. Placing the schema here (rather than in `saas-backend-lib` next to\n * the batch) keeps every operator-tunable engine batch symmetric with\n * `dataSeeding` / `lifecycle` and gives one source of truth the batch factory\n * and the startup validator can both import (`saas-models` cannot depend on\n * `saas-backend-lib` — the dependency arrow points the other way).\n *\n * --------------------------------------------------------------------------\n * Bounds + production floor\n * --------------------------------------------------------------------------\n * {@link archiveAfterDays} bounds mirror the SSO `auditConfig.retentionDays`\n * precedent (min 1 day, max 2555 ≈ 7 years). A stricter PRODUCTION FLOOR (365\n * days) is enforced at boot by\n * `ApplicationStartupConfigValidatorService.validate()` — NOT by a schema-level\n * `.min()` and NOT by a Zod `.superRefine()`, because the environment\n * (development vs staging/production) is a RUNTIME signal\n * (`process.env.APPLICATION_ENV`) that a pure, environment-agnostic shared\n * schema must not read. The schema `.min(1)` is the absolute floor; the runtime\n * validator raises it to 365 outside development.\n */\n/** Access posture for the deployment-wide audit viewer; tenant-scoped audit access is unchanged. */\nexport enum AuditApplicationReadAccess {\n  /** Ordinary production default: the existing application super-administrator role is sufficient. Every cross-tenant read remains observed. */\n  ROLE_BASED = 'role-based',\n  /** Additionally require a live time-bound application-wide grant approved by a different platform administrator. */\n  INDEPENDENT_APPROVAL = 'independent-approval',\n}\n\nexport const AuditTrailConfigSchema = z.object({\n  /**\n   * Application audit viewer admission. Omitted means ROLE_BASED in every environment.\n   * INDEPENDENT_APPROVAL adds the existing independently approved elevation; it never substitutes for roles.\n   * Both policies keep immutable records, application/tenant filters and read observations. This does not\n   * change access to other application-wide resources or per-tenant administrative grants.\n   */\n  applicationReadAccess: z.enum(AuditApplicationReadAccess).optional(),\n  /**\n   * Age (in days) beyond which audit records are EXPORTED to durable archival\n   * file-storage artifacts by the `compliance:audit-logs-archive` cron batch.\n   *\n   * Records are NEVER deleted from the primary `AUDIT_LOGS` store — this is the\n   * archival horizon only (see the block-level JSDoc on why the field is\n   * `archiveAfterDays`, not `retentionDays`).\n   *\n   * OPTIONAL, and **single-sourced to the retention schedule (#1613)**: when\n   * omitted, the horizon is the application's declared\n   * `dataRetention[AUDIT_LOGS].retentionDays` — the period the audit trail is\n   * kept in the live store before it is archived — so one number answers \"how\n   * long is the audit trail kept\" instead of two that drift. Setting both to\n   * DIFFERENT values is refused at startup. With neither declared, NO archival\n   * runs and audit records stay in the primary store indefinitely. Resolve it\n   * through {@link resolveAuditArchiveAfterDays}, never by reading this field.\n   *\n   * Bounds: min 1 / max 2555 (≈ 7 years), mirroring the SSO\n   * `auditConfig.retentionDays` precedent. A production floor of 365 days is\n   * enforced at boot (see block-level JSDoc) — setting a value below 365 in a\n   * staging/production environment fails startup with a CONFIGURATION error.\n   */\n  archiveAfterDays: z.number().int().min(1).max(2555).optional(),\n\n  /**\n   * May a SIEM export deliver to a collector on an address the public internet cannot reach?\n   *\n   * ── What it is for ─────────────────────────────────────────────────────────\n   * A SIEM webhook URL is TENANT-authored (`siemExportConfig.webhookUrl`, written by an organization\n   * administrator) and the delivery worker POSTs to it with the deployment's own network position.\n   * That is a server-side request forgery primitive by construction, and the classic targets are the\n   * ones every guard in `security/ssrf` names: `169.254.169.254`, loopback admin ports, RFC 1918.\n   *\n   * But one legitimate deployment shape genuinely lives there: a self-hosted collector (Splunk,\n   * QRadar, a syslog bridge) on the same private network as the application. Refusing that\n   * unconditionally would not be \"safe\" — it would break a supported topology and push operators to\n   * a worse workaround.\n   *\n   * ── Why it is an OPERATOR field and not a tenant field ─────────────────────\n   * It lives HERE, on the application configuration the deployment operator authors, and NOT on\n   * `SiemExportConfigBaseSchema`, which the tenant authors. A tenant-settable \"allow private\n   * addresses\" flag would hand the party supplying the attacker-controlled URL the switch that\n   * disarms the guard aimed at them — an SSRF bypass with a checkbox. The operator declares the\n   * network posture; the tenant chooses a destination within it.\n   *\n   * ── Why OPTIONAL rather than `.default(false)` ─────────────────────────────\n   * The reader tests for `=== true`, so absent is refuse, and the fail-closed posture is the one you\n   * get by doing nothing — the same contract `archiveAfterDays` states one field above. It is left\n   * without a Zod default so `AuditTrailConfigSchema.parse({})` still round-trips as `{}`; an\n   * always-materialised `false` would make the block non-empty for every application that never\n   * authored it, which is what the pin below this schema's tests exists to prevent.\n   *\n   * ── What it does NOT relax ─────────────────────────────────────────────────\n   * Not the scheme policy, not the credentials-in-URL refusal, and not the PINNING: the delivery\n   * still connects only to an address classified at the moment of connection. It widens WHICH\n   * addresses are admitted, never whether the admitted address is the one connected to.\n   */\n  allowPrivateNetworkSiemCollectors: z.boolean().optional(),\n});\n\nexport type AuditTrailConfig = z.infer<typeof AuditTrailConfigSchema>;\n/** @wildo_source:part:end saas.models.audit.trail-config */\n\n/**\n * The effective audit archival horizon: the explicit `archiveAfterDays`, else the declared\n * `AUDIT_LOGS` period, else `undefined` (archival off). The one reader every consumer goes through —\n * the archive batch and the startup floor — so the derived value is floored exactly like an authored one.\n *\n * The explicit value wins only because startup has refused it whenever it DISAGREES with a declared\n * period ({@link findAuditArchiveHorizonConflict}).\n */\nexport function resolveAuditArchiveAfterDays(\n  auditTrail: { readonly archiveAfterDays?: number } | undefined,\n  schedule: ApplicationRetentionSchedule | undefined,\n): number | undefined {\n  return auditTrail?.archiveAfterDays ?? schedule?.[DataRetentionClass.AUDIT_LOGS]?.retentionDays;\n}\n\n/**\n * The disagreement startup refuses: an explicit `archiveAfterDays` beside a declared `AUDIT_LOGS` period\n * of a different length. `undefined` when there is none.\n */\nexport function findAuditArchiveHorizonConflict(\n  auditTrail: { readonly archiveAfterDays?: number } | undefined,\n  schedule: ApplicationRetentionSchedule | undefined,\n): { readonly archiveAfterDays: number; readonly auditLogsRetentionDays: number } | undefined {\n  const archiveAfterDays = auditTrail?.archiveAfterDays;\n  const auditLogsRetentionDays = schedule?.[DataRetentionClass.AUDIT_LOGS]?.retentionDays;\n  if (archiveAfterDays === undefined || auditLogsRetentionDays === undefined) return undefined;\n  return archiveAfterDays === auditLogsRetentionDays ? undefined : { archiveAfterDays, auditLogsRetentionDays };\n}\n"]}