@wildo-ai/saas-models 1.1.2 → 1.1.3

package/dist/esm/compliance/audit-trails/application-audit-logs.shared.resources-config.schemas.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { AuditEventCategory, AuditEventSeverity, AuditableEvent_BaseSchema } from './auditable-events.shared.schema.js';
+import { createResourceConfiguration_Initialization } from '../../resources/resources-config.shared.factory.js';
+import { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../../resources/resources.shared.core.definitions.js';
+import { ResourceOperationRiskLevel, ResourceOperationVariantType } from '../../resources/resources.shared.schemas.js';
+import { CORE_APP_ROLES } from '../../security/authorizations/roles.shared.schemas.js';
+import { ResourceSystemAccessMode } from '../../resources/resources-config.shared.schemas.js';
+/**
+ * The APPLICATION-scoped door onto the audit trail.
+ *
+ * ## Why this exists at all
+ *
+ * `AUDIT_LOGS` is organization-scoped and its only route is
+ * `/organizations/{organizationId}/audit-logs`, so it returns exactly the rows carrying that
+ * tenant. A large share of security events carry NO organization by design — `logUserLogin` takes
+ * `organizationId` as optional because no organization is selected at login, and the same is true
+ * of session eviction, token refresh and application-wide authentication-policy changes. Measured
+ * on a dogfood application (#317): **94 of 127 rows had no organization**, and were reachable
+ * through no API. An operator could see 26% of the trail and could not attest the rest, while a
+ * reader querying the only available surface saw `user_login: 0` for a control that had emitted 21.
+ *
+ * ## Why a SEPARATE resource type rather than a second route
+ *
+ * `generateParentCombinations` composes every URL as
+ * `[...primaryScope, ...mandatoryContext, ...optionalCombo]`, so a routed application edge on
+ * `AUDIT_LOGS` would appear in EVERY combination and rewrite the organization route to
+ * `/applications/{applicationId}/organizations/{organizationId}/audit-logs` — breaking all eight of
+ * its documented paths and their consumers. Making the organization edge optional does not help:
+ * the empty combination is skipped whenever any parent exists, so no bare route is emitted either.
+ * A sibling type carrying ONE application parent takes the route it needs and leaves the existing
+ * door byte-identical. The pattern is the engine's own: notification badges are dual-scope with a
+ * type per scope, `APPLICATION_API_KEYS` shows the application routing shape, and `USER_SELF`
+ * shows a distinct type addressing another's rows.
+ *
+ * ## Two doors, ONE record set — the security contract
+ *
+ * Both types resolve to the `auditLogs` collection through
+ * `RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES`. That makes the isolation properties a
+ * per-DOOR obligation rather than a property of the rows:
+ *
+ * - the organization door keeps its tenant filter and its organization roles, unchanged;
+ * - this door is `APP_ADMIN_SUPER_ADMIN`-ONLY on every operation. An organization role must never
+ *   reach it — the rows behind it span every tenant;
+ * - a read here that touches a tenant-attributed row is a CROSS-TENANT read and OWES an audit
+ *   emission. **It is wired**, by the two halves below acting together, and neither is optional:
+ *   each read variant declares `admitsCrossTenantPlatformAdministration`, and
+ *   `ServicesRegistryHandler.recordCrossTenantReadAccess` observes every enrolled read and emits
+ *   `CROSS_TENANT_ADMINISTRATIVE_ACCESS` once per TENANT the returned rows belong to. The
+ *   declaration is what enrols the read: `authorizeOrganizations` — where that event is otherwise
+ *   emitted — runs only for ORGANIZATIONS-scoped resources and decides on ONE fetched row, so it
+ *   never sees this door at all. Grouping per tenant is what makes the crossing visible to the
+ *   REACHED tenant, in its own organization-scoped viewer, rather than only to the operator.
+ *   `.claude/rules/administrative-continuity-floors.md` requires every crossing to be named in the
+ *   trail, and the trail is the worst possible surface on which to make an operator read invisible.
+ *   See `security/authorizations/cross-tenant-read-observation.backend.ts` for why an UNDECLARED
+ *   door is deliberately not observed instead of being observed with a false `admissionDeclared`.
+ *
+ * ## Deliberately mirrored from the organization resource
+ *
+ * `isSystemResource`, `systemAccessPolicy.exportSubject: FORBIDDEN` and the ABSENCE of a
+ * `retentionPolicy` are copied ON PURPOSE. They are properties of the ROWS, and the rows are the
+ * same ones — a second door that disagreed about whether the audit trail is subject-exportable, or
+ * about how long it is kept, would be a policy fork over one record set. See the organization
+ * config for the reasoning behind each; do not change one without the other.
+ *
+ * ## Deliberately NOT mirrored
+ *
+ * There is no CREATE. The organization resource carries a `REPOSITORY_ONLY` CREATE because that is
+ * how audit rows are written; writing is not a scope question and must keep exactly one door.
+ */
+export const applicationAuditLogsResourceConfiguration_InitializationFactory = (resourcesRelationships) => createResourceConfiguration_Initialization({
+    mainSchema: AuditableEvent_BaseSchema,
+    resourceIdentifier: CoreResourceType.APPLICATION_AUDIT_LOGS,
+    resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION_AUDIT_LOGS],
+    resourceRelationships: resourcesRelationships,
+    isSystemResource: true,
+    /** Mirrored from the organization door — the same rows, so the same answer. Disclosing the monitoring trail to its own subject is self-defeating and out of Art. 20 scope. */
+    systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.FORBIDDEN },
+    coreOperations: [
+        CoreResourceOperation.READ,
+        CoreResourceOperation.LIST,
+        CoreResourceOperation.SEARCH,
+    ],
+    operationsConfiguration: {
+        [CoreResourceOperation.READ]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    /** APP_ADMIN_SUPER_ADMIN ONLY — never an organization role. The rows behind this door span every tenant. */
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    /**
+                     * Reading ONE tenant's audit row through the application door IS a crossing, so the cheapest
+                     * reach — fetch by id — is declared and audited exactly like the collection verbs. Declaring
+                     * it is also what stops `assignInitiatorOrganizationConfinementToFilter` silently narrowing
+                     * this door to an operator who happens to carry an ambient organization, which would make a
+                     * surface documented as spanning every tenant return one tenant and report success.
+                     */
+                    admitsCrossTenantPlatformAdministration: true,
+                }],
+        },
+        [CoreResourceOperation.LIST]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    /** The declared crossing — see READ. Every enrolled read emits one crossing per tenant reached. */
+                    admitsCrossTenantPlatformAdministration: true,
+                    filterFields: {
+                        eventType: z.string(),
+                        eventCategory: z.enum(AuditEventCategory),
+                        severity: z.enum(AuditEventSeverity),
+                        userId: z.string(),
+                        /**
+                         * Filterable so an operator can narrow to one tenant THROUGH this door, which is the
+                         * cross-tenant investigation this surface exists for. It is a FILTER, never the isolation
+                         * boundary: isolation on this door is the role gate above, and narrowing to a tenant does
+                         * not make the read any less cross-tenant for audit purposes.
+                         */
+                        organizationId: z.string(),
+                        correlationId: z.string(),
+                        clientInstanceId: z.string(),
+                        createdAt: z.date(),
+                    },
+                    /** `eventId` last, as the keyset tie-breaker — `createdAt` is not unique under boot/seed bursts. Mirrors the organization door; removing it reintroduces a paging data-loss path. */
+                    sortFields: ['createdAt', 'severity', 'eventType', 'eventId'],
+                    maxPaginatedResultPerPageLimit: 100,
+                }],
+        },
+        [CoreResourceOperation.SEARCH]: {
+            variants: [{
+                    variantType: ResourceOperationVariantType.API_CALL,
+                    isDefault: true,
+                    roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],
+                    riskLevel: ResourceOperationRiskLevel.MEDIUM,
+                    /** The declared crossing — see READ. Every enrolled read emits one crossing per tenant reached. */
+                    admitsCrossTenantPlatformAdministration: true,
+                    isSearchable: false,
+                    searchableFields: [],
+                    filterFields: {
+                        eventType: z.string(),
+                        eventCategory: z.enum(AuditEventCategory),
+                        severity: z.enum(AuditEventSeverity),
+                        userId: z.string(),
+                        organizationId: z.string(),
+                        correlationId: z.string(),
+                        clientInstanceId: z.string(),
+                        createdAt: z.date(),
+                    },
+                    sortFields: ['createdAt', 'severity', 'eventType'],
+                    maxPaginatedResultPerPageLimit: 100,
+                }],
+        },
+    },
+});
+//# sourceMappingURL=application-audit-logs.shared.resources-config.schemas.js.map

package/dist/esm/compliance/audit-trails/application-audit-logs.shared.resources-config.schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"application-audit-logs.shared.resources-config.schemas.js","sourceRoot":"","sources":["../../../../../src/compliance/audit-trails/application-audit-logs.shared.resources-config.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["import { z } from 'zod';\n\nimport { AuditEventCategory, AuditEventSeverity, AuditableEvent_BaseSchema } from './auditable-events.shared.schema';\nimport { createResourceConfiguration_Initialization } from '../../resources/resources-config.shared.factory';\nimport { CoreResourceOperation, CoreResourceType, coreResourceShared_FieldIdentifier } from '../../resources/resources.shared.core.definitions';\nimport { ResourceOperationRiskLevel, ResourceOperationVariantType, ResourceRelationship } from '../../resources/resources.shared.schemas';\nimport { CORE_APP_ROLES } from '../../security/authorizations/roles.shared.schemas';\nimport { ResourceSystemAccessMode } from '../../resources/resources-config.shared.schemas';\n\n/**\n * The APPLICATION-scoped door onto the audit trail.\n *\n * ## Why this exists at all\n *\n * `AUDIT_LOGS` is organization-scoped and its only route is\n * `/organizations/{organizationId}/audit-logs`, so it returns exactly the rows carrying that\n * tenant. A large share of security events carry NO organization by design — `logUserLogin` takes\n * `organizationId` as optional because no organization is selected at login, and the same is true\n * of session eviction, token refresh and application-wide authentication-policy changes. Measured\n * on a dogfood application (#317): **94 of 127 rows had no organization**, and were reachable\n * through no API. An operator could see 26% of the trail and could not attest the rest, while a\n * reader querying the only available surface saw `user_login: 0` for a control that had emitted 21.\n *\n * ## Why a SEPARATE resource type rather than a second route\n *\n * `generateParentCombinations` composes every URL as\n * `[...primaryScope, ...mandatoryContext, ...optionalCombo]`, so a routed application edge on\n * `AUDIT_LOGS` would appear in EVERY combination and rewrite the organization route to\n * `/applications/{applicationId}/organizations/{organizationId}/audit-logs` — breaking all eight of\n * its documented paths and their consumers. Making the organization edge optional does not help:\n * the empty combination is skipped whenever any parent exists, so no bare route is emitted either.\n * A sibling type carrying ONE application parent takes the route it needs and leaves the existing\n * door byte-identical. The pattern is the engine's own: notification badges are dual-scope with a\n * type per scope, `APPLICATION_API_KEYS` shows the application routing shape, and `USER_SELF`\n * shows a distinct type addressing another's rows.\n *\n * ## Two doors, ONE record set — the security contract\n *\n * Both types resolve to the `auditLogs` collection through\n * `RESOURCE_SHARED_PERSISTENCE_COLLECTION_ALIASES`. That makes the isolation properties a\n * per-DOOR obligation rather than a property of the rows:\n *\n * - the organization door keeps its tenant filter and its organization roles, unchanged;\n * - this door is `APP_ADMIN_SUPER_ADMIN`-ONLY on every operation. An organization role must never\n *   reach it — the rows behind it span every tenant;\n * - a read here that touches a tenant-attributed row is a CROSS-TENANT read and OWES an audit\n *   emission. **It is wired**, by the two halves below acting together, and neither is optional:\n *   each read variant declares `admitsCrossTenantPlatformAdministration`, and\n *   `ServicesRegistryHandler.recordCrossTenantReadAccess` observes every enrolled read and emits\n *   `CROSS_TENANT_ADMINISTRATIVE_ACCESS` once per TENANT the returned rows belong to. The\n *   declaration is what enrols the read: `authorizeOrganizations` — where that event is otherwise\n *   emitted — runs only for ORGANIZATIONS-scoped resources and decides on ONE fetched row, so it\n *   never sees this door at all. Grouping per tenant is what makes the crossing visible to the\n *   REACHED tenant, in its own organization-scoped viewer, rather than only to the operator.\n *   `.claude/rules/administrative-continuity-floors.md` requires every crossing to be named in the\n *   trail, and the trail is the worst possible surface on which to make an operator read invisible.\n *   See `security/authorizations/cross-tenant-read-observation.backend.ts` for why an UNDECLARED\n *   door is deliberately not observed instead of being observed with a false `admissionDeclared`.\n *\n * ## Deliberately mirrored from the organization resource\n *\n * `isSystemResource`, `systemAccessPolicy.exportSubject: FORBIDDEN` and the ABSENCE of a\n * `retentionPolicy` are copied ON PURPOSE. They are properties of the ROWS, and the rows are the\n * same ones — a second door that disagreed about whether the audit trail is subject-exportable, or\n * about how long it is kept, would be a policy fork over one record set. See the organization\n * config for the reasoning behind each; do not change one without the other.\n *\n * ## Deliberately NOT mirrored\n *\n * There is no CREATE. The organization resource carries a `REPOSITORY_ONLY` CREATE because that is\n * how audit rows are written; writing is not a scope question and must keep exactly one door.\n */\nexport const applicationAuditLogsResourceConfiguration_InitializationFactory = (\n  resourcesRelationships: ResourceRelationship[]\n) => createResourceConfiguration_Initialization<\n  undefined,\n  CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.SEARCH,\n  typeof AuditableEvent_BaseSchema\n>({\n  mainSchema: AuditableEvent_BaseSchema,\n  resourceIdentifier: CoreResourceType.APPLICATION_AUDIT_LOGS,\n  resourceFieldIdentifier: coreResourceShared_FieldIdentifier[CoreResourceType.APPLICATION_AUDIT_LOGS],\n  resourceRelationships: resourcesRelationships,\n  isSystemResource: true,\n  /** Mirrored from the organization door — the same rows, so the same answer. Disclosing the monitoring trail to its own subject is self-defeating and out of Art. 20 scope. */\n  systemAccessPolicy: { exportSubject: ResourceSystemAccessMode.FORBIDDEN },\n\n  coreOperations: [\n    CoreResourceOperation.READ,\n    CoreResourceOperation.LIST,\n    CoreResourceOperation.SEARCH,\n  ],\n\n  operationsConfiguration: {\n    [CoreResourceOperation.READ]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        /** APP_ADMIN_SUPER_ADMIN ONLY — never an organization role. The rows behind this door span every tenant. */\n        roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        /**\n         * Reading ONE tenant's audit row through the application door IS a crossing, so the cheapest\n         * reach — fetch by id — is declared and audited exactly like the collection verbs. Declaring\n         * it is also what stops `assignInitiatorOrganizationConfinementToFilter` silently narrowing\n         * this door to an operator who happens to carry an ambient organization, which would make a\n         * surface documented as spanning every tenant return one tenant and report success.\n         */\n        admitsCrossTenantPlatformAdministration: true,\n      }],\n    },\n\n    [CoreResourceOperation.LIST]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        /** The declared crossing — see READ. Every enrolled read emits one crossing per tenant reached. */\n        admitsCrossTenantPlatformAdministration: true,\n        filterFields: {\n          eventType: z.string(),\n          eventCategory: z.enum(AuditEventCategory),\n          severity: z.enum(AuditEventSeverity),\n          userId: z.string(),\n          /**\n           * Filterable so an operator can narrow to one tenant THROUGH this door, which is the\n           * cross-tenant investigation this surface exists for. It is a FILTER, never the isolation\n           * boundary: isolation on this door is the role gate above, and narrowing to a tenant does\n           * not make the read any less cross-tenant for audit purposes.\n           */\n          organizationId: z.string(),\n          correlationId: z.string(),\n          clientInstanceId: z.string(),\n          createdAt: z.date(),\n        },\n        /** `eventId` last, as the keyset tie-breaker — `createdAt` is not unique under boot/seed bursts. Mirrors the organization door; removing it reintroduces a paging data-loss path. */\n        sortFields: ['createdAt', 'severity', 'eventType', 'eventId'] as const,\n        maxPaginatedResultPerPageLimit: 100,\n      }],\n    },\n\n    [CoreResourceOperation.SEARCH]: {\n      variants: [{\n        variantType: ResourceOperationVariantType.API_CALL,\n        isDefault: true,\n        roles: [CORE_APP_ROLES.APP_ADMIN_SUPER_ADMIN],\n        riskLevel: ResourceOperationRiskLevel.MEDIUM,\n        /** The declared crossing — see READ. Every enrolled read emits one crossing per tenant reached. */\n        admitsCrossTenantPlatformAdministration: true,\n        isSearchable: false,\n        searchableFields: [],\n        filterFields: {\n          eventType: z.string(),\n          eventCategory: z.enum(AuditEventCategory),\n          severity: z.enum(AuditEventSeverity),\n          userId: z.string(),\n          organizationId: z.string(),\n          correlationId: z.string(),\n          clientInstanceId: z.string(),\n          createdAt: z.date(),\n        },\n        sortFields: ['createdAt', 'severity', 'eventType'] as const,\n        maxPaginatedResultPerPageLimit: 100,\n      }],\n    },\n  },\n});\n"]}

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

@@ -1,8 +1,24 @@
 import { z } from 'zod';
 /**
+ * @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.
+ *
+ * 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
+ * artifacts in file storage while the originals remain. The field is named `archiveAfterDays` rather
+ * than `retentionDays` for exactly that reason — nothing is retained-then-deleted, and an operator
+ * expecting the primary store to shrink has misread it.
+ *
+ * The decision is taken at each tick from live configuration, so changing the value takes effect
+ * without a restart, and a misconfigured value cannot orphan the schedule. An application that turns
+ * this on after it already has aged data seeds the archive with a one-off wider look-back run.
+ *
  * Phase 5 / F1 (audit-logging plan). Mirrors {@link DataSeedingConfigSchema} /
  * {@link LifecycleConfigSchema} in shape and intent: a small, OPTIONAL block on
  * the shared application configuration ({@link AppConfiguration_Shared_Schema})
@@ -10,6 +26,11 @@ import { z } from 'zod';
  * `compliance:audit-logs-archive` cron batch — without forking the factory's
  * built-in defaults.
  *
+ * It also carries the subsystem's one EGRESS posture
+ * ({@link allowPrivateNetworkSiemCollectors}), which belongs to the operator rather
+ * than to the tenant who authors a SIEM destination — see that field's own JSDoc
+ * for why the distinction is the whole control.
+ *
  * --------------------------------------------------------------------------
  * Archival, NOT deletion — audit logs are immutable
  * --------------------------------------------------------------------------
@@ -53,6 +74,8 @@ import { z } from 'zod';
  */
 export declare const AuditTrailConfigSchema: z.ZodObject<{
     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 */
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,sBAAsB;;iBAmBjC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC"}
+{"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"}

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

@@ -1,8 +1,24 @@
 import { z } from 'zod';
 /**
+ * @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.
+ *
+ * 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
+ * artifacts in file storage while the originals remain. The field is named `archiveAfterDays` rather
+ * than `retentionDays` for exactly that reason — nothing is retained-then-deleted, and an operator
+ * expecting the primary store to shrink has misread it.
+ *
+ * The decision is taken at each tick from live configuration, so changing the value takes effect
+ * without a restart, and a misconfigured value cannot orphan the schedule. An application that turns
+ * this on after it already has aged data seeds the archive with a one-off wider look-back run.
+ *
  * Phase 5 / F1 (audit-logging plan). Mirrors {@link DataSeedingConfigSchema} /
  * {@link LifecycleConfigSchema} in shape and intent: a small, OPTIONAL block on
  * the shared application configuration ({@link AppConfiguration_Shared_Schema})
@@ -10,6 +26,11 @@ import { z } from 'zod';
  * `compliance:audit-logs-archive` cron batch — without forking the factory's
  * built-in defaults.
  *
+ * It also carries the subsystem's one EGRESS posture
+ * ({@link allowPrivateNetworkSiemCollectors}), which belongs to the operator rather
+ * than to the tenant who authors a SIEM destination — see that field's own JSDoc
+ * for why the distinction is the whole control.
+ *
  * --------------------------------------------------------------------------
  * Archival, NOT deletion — audit logs are immutable
  * --------------------------------------------------------------------------
@@ -70,5 +91,40 @@ export const AuditTrailConfigSchema = z.object({
      * staging/production environment fails startup with a CONFIGURATION error.
      */
     archiveAfterDays: z.number().int().min(1).max(2555).optional(),
+    /**
+     * May a SIEM export deliver to a collector on an address the public internet cannot reach?
+     *
+     * ── What it is for ─────────────────────────────────────────────────────────
+     * A SIEM webhook URL is TENANT-authored (`siemExportConfig.webhookUrl`, written by an organization
+     * administrator) and the delivery worker POSTs to it with the deployment's own network position.
+     * That is a server-side request forgery primitive by construction, and the classic targets are the
+     * ones every guard in `security/ssrf` names: `169.254.169.254`, loopback admin ports, RFC 1918.
+     *
+     * But one legitimate deployment shape genuinely lives there: a self-hosted collector (Splunk,
+     * QRadar, a syslog bridge) on the same private network as the application. Refusing that
+     * unconditionally would not be "safe" — it would break a supported topology and push operators to
+     * a worse workaround.
+     *
+     * ── Why it is an OPERATOR field and not a tenant field ─────────────────────
+     * It lives HERE, on the application configuration the deployment operator authors, and NOT on
+     * `SiemExportConfigBaseSchema`, which the tenant authors. A tenant-settable "allow private
+     * addresses" flag would hand the party supplying the attacker-controlled URL the switch that
+     * disarms the guard aimed at them — an SSRF bypass with a checkbox. The operator declares the
+     * network posture; the tenant chooses a destination within it.
+     *
+     * ── Why OPTIONAL rather than `.default(false)` ─────────────────────────────
+     * The reader tests for `=== true`, so absent is refuse, and the fail-closed posture is the one you
+     * get by doing nothing — the same contract `archiveAfterDays` states one field above. It is left
+     * without a Zod default so `AuditTrailConfigSchema.parse({})` still round-trips as `{}`; an
+     * always-materialised `false` would make the block non-empty for every application that never
+     * authored it, which is what the pin below this schema's tests exists to prevent.
+     *
+     * ── What it does NOT relax ─────────────────────────────────────────────────
+     * Not the scheme policy, not the credentials-in-URL refusal, and not the PINNING: the delivery
+     * still connects only to an address classified at the moment of connection. It widens WHICH
+     * addresses are admitted, never whether the admitted address is the one connected to.
+     */
+    allowPrivateNetworkSiemCollectors: z.boolean().optional(),
 });
+/** @wildo_source:part:end saas.models.audit.trail-config */
 //# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;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;CAC/D,CAAC,CAAC","sourcesContent":["import { z } from 'zod';\n\n/**\n * `AuditTrailConfig` — application-level operator-tunable configuration for the\n * compliance audit-trail subsystem.\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 * --------------------------------------------------------------------------\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\nexport type AuditTrailConfig = z.infer<typeof AuditTrailConfigSchema>;\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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"]}