filegrc 0.6.5 → 0.7.1

package/src/soc2.js

@@ -0,0 +1,227 @@
+import { coverageEnd, coverageStart } from "./coverage.js";
+
+export const REQUIRED_SOC2_DESCRIPTION_REFERENCES = Array.from(
+  { length: 9 },
+  (_, index) => `DC${index + 1}`
+);
+
+export const REQUIRED_SOC2_SECURITY_REFERENCES = [
+  "CC1.1",
+  "CC1.2",
+  "CC1.3",
+  "CC1.4",
+  "CC1.5",
+  "CC2.1",
+  "CC2.2",
+  "CC2.3",
+  "CC3.1",
+  "CC3.2",
+  "CC3.3",
+  "CC3.4",
+  "CC4.1",
+  "CC4.2",
+  "CC5.1",
+  "CC5.2",
+  "CC5.3",
+  "CC6.1",
+  "CC6.2",
+  "CC6.3",
+  "CC6.4",
+  "CC6.5",
+  "CC6.6",
+  "CC6.7",
+  "CC6.8",
+  "CC7.1",
+  "CC7.2",
+  "CC7.3",
+  "CC7.4",
+  "CC7.5",
+  "CC8.1",
+  "CC9.1",
+  "CC9.2"
+];
+
+const SOC2_PROGRAM_GOALS = new Set([
+  "readiness",
+  "soc-2-type-1",
+  "soc-2-type-2"
+]);
+
+export function soc2RequirementApplicabilityConstraint(requirement, program, modelVersion = "4") {
+  if (
+    String(modelVersion) !== "4"
+    || requirement?.type !== "requirement"
+    || !SOC2_PROGRAM_GOALS.has(program?.assuranceGoal)
+  ) return null;
+  const reference = String(requirement.reference || "").trim().toUpperCase();
+  const security = REQUIRED_SOC2_SECURITY_REFERENCES.includes(reference);
+  const description = REQUIRED_SOC2_DESCRIPTION_REFERENCES.includes(reference);
+  if (!security && !description) return null;
+  const family = security ? "Security Common Criteria" : "SOC 2 Description Criteria";
+  return {
+    requiredDecision: "applicable",
+    allowedDecisions: ["applicable"],
+    message: `${reference} is required for the selected SOC 2 Security program.`,
+    defaultRationale: `${reference} is part of the required ${family} baseline for the selected ${soc2GoalLabel(program.assuranceGoal)} Program.`
+  };
+}
+
+function soc2GoalLabel(goal) {
+  if (goal === "soc-2-type-1") return "SOC 2 Type 1";
+  if (goal === "soc-2-type-2") return "SOC 2 Type 2";
+  return "SOC 2 readiness";
+}
+
+export function missingSoc2References(requirements, requiredReferences) {
+  const references = new Set(requirements.map(({ reference }) => String(reference || "").trim().toUpperCase()));
+  return requiredReferences.filter((reference) => !references.has(reference));
+}
+
+export function recordWasInUseDuringAudit(record, engagementStart, engagementEnd) {
+  if (!record) return false;
+  if (record.type === "vendor") {
+    if (!["active", "deprecated", "terminated"].includes(record.status)) return false;
+    const endedOn = record.endDate || (record.status === "terminated" ? record.statusTransition?.changedOn : null);
+    if (engagementEnd && record.startDate && record.startDate > engagementEnd) return false;
+    if (engagementStart && endedOn && endedOn < engagementStart) return false;
+    if (record.status === "terminated" && engagementStart && !endedOn) return false;
+    return true;
+  }
+  if (["active", "deprecated"].includes(record.status)) return true;
+  if (!engagementStart) return false;
+  if (["component", "system"].includes(record.type) && record.status === "retired") {
+    return Boolean(record.statusTransition?.changedOn && record.statusTransition.changedOn >= engagementStart);
+  }
+  return false;
+}
+
+export function auditorWasEngaged(auditor, audit) {
+  const engagementStart = audit?.managementAcknowledgedOn
+    || audit?.fieldworkStart
+    || coverageStart(audit?.coverage);
+  const engagementEnd = audit?.reportDate
+    || audit?.fieldworkEnd
+    || coverageEnd(audit?.coverage);
+  if (!recordWasInUseDuringAudit(auditor, engagementStart, engagementEnd)) return false;
+  const endedOn = auditor.endDate || (auditor.status === "terminated" ? auditor.statusTransition?.changedOn : null);
+  if (engagementStart && auditor.startDate && auditor.startDate > engagementStart) return false;
+  if (engagementEnd && endedOn && endedOn < engagementEnd) return false;
+  return true;
+}
+
+export function personWasActiveOn(person, on) {
+  if (person?.type !== "person" || !on) return false;
+  if (person.startDate && person.startDate > on) return false;
+  const endedOn = person.endDate || (person.status === "inactive" ? person.statusTransition?.changedOn : null);
+  if (endedOn && endedOn < on) return false;
+  return person.status === "active" || (person.status === "inactive" && Boolean(endedOn));
+}
+
+export function appointmentWasAuthorizedOn(appointment, on, byId) {
+  if (appointment?.type !== "appointment" || !on || !["active", "ended"].includes(appointment.status)) return false;
+  if (!appointment.startsOn || appointment.startsOn > on) return false;
+  if (appointment.endsOn && appointment.endsOn < on) return false;
+  return personWasActiveOn(byId.get(appointment.holderId), on);
+}
+
+export function signatoryAppointmentIssue(audit, byId) {
+  if (!audit?.reportDate) {
+    return {
+      code: "signatory-authority-date-missing",
+      message: "Record the CPA report date before confirming who had authority to sign management's assertion and written representations."
+    };
+  }
+  const ids = audit.signatoryAppointmentIds || [];
+  if (!ids.length) {
+    return {
+      code: "signatory-authority-missing",
+      message: "Link the dated authority Appointment for each management assertion and representation signer."
+    };
+  }
+  const permittedScopes = new Set([
+    "workspace",
+    audit.id,
+    audit.programId,
+    ...(audit.systemIds || []),
+    ...[...byId.values()].filter((record) => record.type === "organization").map(({ id }) => id)
+  ].filter(Boolean));
+  const invalid = ids.filter((id) => {
+    const appointment = byId.get(id);
+    return !appointmentWasAuthorizedOn(appointment, audit.reportDate, byId)
+      || !(appointment.scopeResourceIds || []).some((scopeId) => permittedScopes.has(scopeId));
+  });
+  if (invalid.length) {
+    return {
+      code: "signatory-authority-invalid",
+      message: `Confirm that ${invalid.join(", ")} names a dated Appointment whose holder was active and whose scope covered the workspace, Program, or Audit on ${audit.reportDate}.`
+    };
+  }
+  return null;
+}
+
+export function soc2ReportEvidenceIssue(evidence, audit, modelVersion = "4") {
+  if (
+    evidence?.type !== "evidence"
+    || evidence.status !== "verified"
+    || evidence.artifactKind !== "third-party-report"
+    || evidence.artifactSubtype !== "soc2-report"
+  ) {
+    return {
+      code: "invalid-audit-report-evidence",
+      message: `${evidence?.title || audit?.title || "The audit"} must be verified third-party-report Evidence with subtype soc2-report for the issued SOC 2 report.`
+    };
+  }
+  const issuedOn = (String(modelVersion) === "4"
+    ? evidence.sourceGeneratedAt
+    : evidence.sourceGeneratedAt || evidence.businessEventAt || evidence.collectedOn
+  )?.slice(0, 10);
+  if (!issuedOn) {
+    return {
+      code: "audit-report-date-missing",
+      message: `Record the issued SOC 2 report's actual issuance timestamp in ${evidence.title}'s sourceGeneratedAt field.`
+    };
+  }
+  if (audit?.reportDate && issuedOn !== audit.reportDate) {
+    return {
+      code: "audit-report-date-mismatch",
+      message: `${evidence.title} is dated ${issuedOn}, which does not match the Audit reportDate ${audit.reportDate}.`
+    };
+  }
+  if (audit?.reportDate && audit.opinionDate && audit.opinionDate !== audit.reportDate) {
+    return {
+      code: "audit-opinion-date-mismatch",
+      message: `The Audit opinionDate ${audit.opinionDate} does not match reportDate ${audit.reportDate}. Reconcile both dates to the issued CPA report.`
+    };
+  }
+  return null;
+}
+
+export function subsequentEventsReviewIssue(audit) {
+  const review = audit?.subsequentEventsReview;
+  if (!review) {
+    return {
+      code: "subsequent-events-review-missing",
+      message: "Review incidents, changes, findings, fraud, legal matters, subservice coverage, representations, and other relevant events through the CPA report date."
+    };
+  }
+  if (!(review.reviewedByIds || []).length || !String(review.conclusion || "").trim()) {
+    return {
+      code: "subsequent-events-review-incomplete",
+      message: "The subsequent-events review must name its reviewers and record management's conclusion."
+    };
+  }
+  const requiredThroughOn = audit.reportDate || audit.fieldworkEnd || audit.coverage?.endsOn || audit.coverage?.on;
+  if (!review.throughOn || (requiredThroughOn && review.throughOn < requiredThroughOn)) {
+    return {
+      code: "subsequent-events-period-incomplete",
+      message: `The subsequent-events review must cover through ${requiredThroughOn || "the latest engagement date"}${audit.reportDate ? ", the CPA report date" : ""}.`
+    };
+  }
+  if (!review.reviewedOn || review.reviewedOn < review.throughOn) {
+    return {
+      code: "subsequent-events-review-date-invalid",
+      message: "The subsequent-events review date must be on or after the date through which events were reviewed."
+    };
+  }
+  return null;
+}

package/src/state.js

@@ -8,11 +8,13 @@ import { planObligations } from "./obligations.js";
 import { resolveDataPath, resolveWorkspaceRoot } from "./paths.js";
 import { assessProgramReadiness } from "./program-readiness.js";
 import { markdownEntries } from "./resource-markdown.js";
+import { resolveProgram } from "./program.js";
 import { currentCalendarDate } from "./time.js";
 import { serializeWorkspaceMutation } from "./mutation.js";
 import { fingerprintWorkspace, validateWorkspace } from "./validate.js";
 import { assessWorkflow } from "./workflow.js";
 import { measureTiming } from "./timing.js";
+import { soc2RequirementApplicabilityConstraint } from "./soc2.js";
 
 const renderedMarkdownCache = new Map();
 const MAX_RENDERED_MARKDOWN_CACHE_ENTRIES = 1_000;
@@ -82,6 +84,11 @@ async function createAppStateUnlocked(input, options) {
     asOf,
     generatedAt
   }));
+  const activeProgram = resolveProgram(loaded);
+  const applicabilityConstraints = Object.fromEntries(loaded.resources.flatMap((record) => {
+    const constraint = soc2RequirementApplicabilityConstraint(record, activeProgram, loaded.model.modelVersion);
+    return constraint ? [[record.id, constraint]] : [];
+  }));
   const audits = loaded.resources.filter((record) => record.type === "audit");
   const auditPreparations = await measureTiming("state-audit-preparation", async () => Object.fromEntries(await Promise.all(
     (audits.length ? audits : [null]).map(async (audit) => {
@@ -140,6 +147,7 @@ async function createAppStateUnlocked(input, options) {
     },
     obligations,
     collectionReviews,
+    applicabilityConstraints,
     programReadiness,
     auditPreparations,
     workflow,

package/src/validate.js

@@ -7,7 +7,7 @@ import { collectionRevision } from "./collection-revision.js";
 import { isSafeGitName } from "./git-name.js";
 import { isCanonicalDataPath, resolveDataPath } from "./paths.js";
 import { parseCalendarDate, validCalendarRecurrence } from "./recurrence.js";
-import { obligationIsRunning } from "./program-lifecycle.js";
+import { obligationIsEnabled } from "./program-lifecycle.js";
 import { partyPeople } from "./parties.js";
 import { isMarkdownChoice, markdownEntries } from "./resource-markdown.js";
 import { currentCalendarDate, isRfc3339Timestamp } from "./time.js";
@@ -74,6 +74,7 @@ async function validateWorkspaceUnmeasured(input) {
     validateLocation(record, definition, entry.relativePath, diagnostics);
     validateRecord(record, definition, loaded.model, displayPath, diagnostics);
     validateDateRanges(record, displayPath, diagnostics);
+    validateProposedEffectiveDate(record, asOf, displayPath, diagnostics);
     if (record.type === "appointment") validateAppointment(record, byId, displayPath, diagnostics);
     if (record.type === "program") validateProgram(record, displayPath, diagnostics);
     if (record.type === "component") validateComponent(record, displayPath, diagnostics);
@@ -135,7 +136,7 @@ async function validateWorkspaceUnmeasured(input) {
     }
     validateIndependentApproval(record, byId, displayPath, diagnostics);
     validateCompletedObligationEvent(record, byId, loaded.model, displayPath, diagnostics);
-    validateImplementedControlSchedules(record, obligationsByControl, byId, asOf, displayPath, diagnostics);
+    validateImplementedControlSchedules(record, obligationsByControl, displayPath, diagnostics);
     await validateMarkdown(record, definition, loaded.model, loaded.root, displayPath, diagnostics);
     await validateApprovalBinding(record, loaded.model, loaded.root, displayPath, diagnostics);
   }
@@ -246,7 +247,7 @@ export async function fingerprintWorkspace(input = process.cwd()) {
   return { fingerprint: hash.digest("hex"), loaded };
 }
 
-function validateImplementedControlSchedules(record, obligationsByControl, byId, asOf, path, diagnostics) {
+function validateImplementedControlSchedules(record, obligationsByControl, path, diagnostics) {
   if (record.type !== "control" || record.status !== "implemented") return;
   const schedules = obligationsByControl.get(record.id) || [];
   if (!schedules.length) {
@@ -258,21 +259,13 @@ function validateImplementedControlSchedules(record, obligationsByControl, byId,
     ));
     return;
   }
-  if (schedules.every((obligation) => obligationIsRunning(obligation, byId, asOf))) return;
-  const stopped = schedules.filter((obligation) => !obligationIsRunning(obligation, byId, asOf));
+  if (schedules.some(obligationIsEnabled)) return;
+  const stopped = schedules.filter((obligation) => !obligationIsEnabled(obligation));
   const paused = stopped.filter((obligation) => obligation.status === "paused");
-  const waiting = stopped.filter((obligation) => obligation.status === "active");
-  const policyBlockers = [...new Set(waiting.flatMap((obligation) => (obligation.policyIds || []).map((id) => {
-    const policy = byId.get(id);
-    if (!policy || policy.type !== "policy") return `${id} (missing)`;
-    if (policy.status !== "active") return `${policy.title} (${policy.status})`;
-    if (!policy.effectiveOn) return `${policy.title} (effective date missing)`;
-    if (policy.effectiveOn > asOf) return `${policy.title} (effective ${policy.effectiveOn})`;
-    return null;
-  })).filter(Boolean))];
+  const proposed = stopped.filter((obligation) => obligation.status === "proposed");
   const reasons = [
-    waiting.length
-      ? `${waiting.length} enabled ${waiting.length === 1 ? "schedule is" : "schedules are"} waiting for governing ${policyBlockers.length === 1 ? "policy" : "policies"} to become active and effective${policyBlockers.length ? `: ${policyBlockers.join(", ")}` : ""}. Complete Step 2 first.`
+    proposed.length
+      ? `${proposed.length} linked ${proposed.length === 1 ? "schedule is" : "schedules are"} still proposed. Enable ${proposed.length === 1 ? "it" : "them"} before implementing the control; the schedule will remain dormant until its governing Policy is active and effective.`
       : "",
     paused.length
       ? `${paused.length} linked ${paused.length === 1 ? "schedule is" : "schedules are"} paused. Enable ${paused.length === 1 ? "it" : "them"} before implementing the control.`
@@ -281,7 +274,7 @@ function validateImplementedControlSchedules(record, obligationsByControl, byId,
   diagnostics.push(error(
     "control-work-queue-not-running",
     path,
-    `This control cannot be marked implemented yet. ${reasons}`
+    `This control cannot be marked implemented yet. ${reasons || "Enable at least one linked schedule."}`
   ));
 }
 
@@ -302,6 +295,19 @@ function validateDateRanges(record, path, diagnostics) {
   }
 }
 
+function validateProposedEffectiveDate(record, asOf, path, diagnostics) {
+  if (
+    !["policy", "document"].includes(record.type)
+    || !record.proposedEffectiveOn
+    || record.proposedEffectiveOn >= asOf
+  ) return;
+  diagnostics.push(warning(
+    "past-proposed-effective-date",
+    path,
+    `The proposed effective date ${record.proposedEffectiveOn} has passed. Choose a current or future date when management activates the approved content; do not backdate adoption.`
+  ));
+}
+
 function validateAppointment(record, byId, path, diagnostics) {
   if ((record.scopeResourceIds || []).includes(record.id)) {
     diagnostics.push(error(
@@ -364,9 +370,19 @@ function validateControlComponents(record, byId, path, diagnostics) {
 }
 
 function validateAuditSubservices(record, byId, path, diagnostics) {
+  const selectedSystemIds = new Set(record.systemIds || []);
+  const seenComponentIds = new Set();
   for (const [index, treatment] of (record.subserviceTreatments || []).entries()) {
     for (const componentId of treatment.componentIds || []) {
       const component = byId.get(componentId);
+      if (seenComponentIds.has(componentId)) {
+        diagnostics.push(error(
+          "duplicate-subservice-component",
+          path,
+          `subserviceTreatments[${index}] repeats Component "${componentId}" in more than one treatment.`
+        ));
+      }
+      seenComponentIds.add(componentId);
       if (component?.type === "component" && component.vendorId !== treatment.vendorId) {
         diagnostics.push(error(
           "subservice-vendor-mismatch",
@@ -374,6 +390,16 @@ function validateAuditSubservices(record, byId, path, diagnostics) {
           `subserviceTreatments[${index}] Component "${componentId}" is not supplied by Vendor "${treatment.vendorId}".`
         ));
       }
+      if (
+        component?.type === "component"
+        && !(component.systemUses || []).some(({ systemId }) => selectedSystemIds.has(systemId))
+      ) {
+        diagnostics.push(error(
+          "subservice-component-outside-audit-scope",
+          path,
+          `subserviceTreatments[${index}] Component "${componentId}" has no use in a System selected by this Audit.`
+        ));
+      }
     }
   }
 }