filegrc 0.7.0 → 0.8.0

package/src/program.js

@@ -1,5 +1,7 @@
+import { modelSupports } from "../model/index.js";
+
 export function resolveProgram(loaded, requestedId) {
-  if (String(loaded.model.modelVersion) !== "4") return loaded.workspace;
+  if (!modelSupports(loaded.model, "program-scope")) return loaded.workspace;
   const programs = loaded.resources.filter((record) => record.type === "program" && record.status !== "retired");
   if (requestedId) {
     const program = programs.find(({ id }) => id === requestedId);
@@ -33,7 +35,7 @@ export function resolveProgram(loaded, requestedId) {
 }
 
 export function selectedRequirementIds(program, model) {
-  if (String(model.modelVersion) === "4") {
+  if (modelSupports(model, "program-scope")) {
     return (program.requirementApplicability || [])
       .filter(({ decision }) => decision === "applicable")
       .map(({ requirementId }) => requirementId);
@@ -42,7 +44,7 @@ export function selectedRequirementIds(program, model) {
 }
 
 export function programComponents(loaded, program) {
-  if (String(loaded.model.modelVersion) !== "4") return [];
+  if (!modelSupports(loaded.model, "program-scope")) return [];
   const systemIds = new Set(program.systemIds || []);
   return loaded.resources.filter((record) => (
     record.type === "component"

package/src/reconciliation.js

@@ -2,6 +2,7 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
+import { modelSupports } from "../model/index.js";
 import { createObligationEvent } from "./obligations.js";
 import { markdownEntries } from "./resource-markdown.js";
 import { loadWorkspace } from "./workspace.js";
@@ -94,13 +95,13 @@ export async function planReconciliation(input = process.cwd()) {
   const loaded = input?.resources && input?.model && input?.entries
     ? input
     : await loadWorkspace(input);
-  if (!["3", "4"].includes(String(loaded.model.modelVersion))) {
+  if (!modelSupports(loaded.model, "guided-workflow")) {
     return {
       contractVersion: 1,
       gitRevision: gitRevision(loaded.root),
       changedPaths: [],
       candidates: [],
-      message: "Direct-file transition reconciliation is available in model v3 and v4 workspaces."
+      message: "Direct-file transition reconciliation is available in model v3 and newer workspaces."
     };
   }
   const changedPaths = gitChangedPaths(loaded.root);

package/src/server.js

@@ -5,6 +5,7 @@ import { extname, join, resolve } from "node:path";
 import { performance } from "node:perf_hooks";
 import { getResourceDefinition } from "../model/index.js";
 import { prepareAuditWorkspace } from "./audit-preparation.js";
+import { activateDocuments } from "./document-activation.js";
 import { createNextAuditCycle, planNextAuditCycle } from "./audit-transition.js";
 import { applyApplicabilityReviewWithContext, planApplicabilityReview } from "./batch-review.js";
 import { applyCollectionReview, planCollectionReview } from "./collection-review.js";
@@ -330,6 +331,13 @@ export function createFilegrcServer(input = process.cwd(), options = {}) {
         }, () => activatePolicies(input, { ...payload, confirmed: true }));
         return json(response, 200, result);
       }
+      if (request.method === "POST" && url.pathname === "/api/document-activations") {
+        const payload = await readJson(request);
+        const result = await browserMutation(input, options, {
+          message: (activation) => `Activate ${activation.documentIds.length} governed ${activation.documentIds.length === 1 ? "Document" : "Documents"}`
+        }, () => activateDocuments(input, { ...payload, confirmed: true }));
+        return json(response, 200, result);
+      }
       if (request.method === "POST" && url.pathname === "/api/resources") {
         const payload = normalizeResourceMutation(await readJson(request));
         const { record } = payload;
@@ -543,13 +551,8 @@ function browserMutation(input, options, mutationOptions, task) {
       includeDetails: false,
       validationProof: result?.[BROWSER_VALIDATION]
     }));
-    if (result?.synchronization?.status === "syncing" && state.repository.status !== "syncing") {
-      result.synchronization = {
-        ...result.synchronization,
-        status: state.repository.status === "synced" ? "synced" : "not-synced",
-        synchronizedAt: state.repository.lastSuccessfulSynchronization ?? null,
-        pushError: state.repository.backgroundSyncError ?? null
-      };
+    if (result?.synchronization) {
+      result.synchronization = reconcileMutationSynchronization(result.synchronization, state.repository);
     }
     return {
       ...result,
@@ -564,6 +567,25 @@ function browserMutation(input, options, mutationOptions, task) {
   });
 }
 
+export function reconcileMutationSynchronization(synchronization, repository) {
+  if (synchronization?.status !== "syncing" || repository.status === "syncing") return synchronization;
+  const backgroundFailed = repository.backgroundSynchronization?.status === "failed";
+  if (repository.status !== "synced" && !backgroundFailed) {
+    // A repository snapshot can finish just before a fast background push while
+    // its state is inspected just after the push. Keep the queued result until
+    // a verified success or failure replaces it.
+    return synchronization;
+  }
+  return {
+    ...synchronization,
+    status: repository.status === "synced" ? "synced" : "not-synced",
+    synchronizedAt: repository.lastSuccessfulSynchronization ?? null,
+    pushError: repository.backgroundSyncError
+      ?? repository.backgroundSynchronization?.error
+      ?? null
+  };
+}
+
 function prefersFastMutation(request) {
   return String(request.headers.prefer || "")
     .split(",")

package/src/setup.js

@@ -1,3 +1,4 @@
+import { modelSupports } from "../model/index.js";
 import { applyResourceBatch } from "./files.js";
 import { createResourceId } from "./id.js";
 import { resolveProgram, selectedRequirementIds } from "./program.js";
@@ -9,6 +10,7 @@ const CRITICALITIES = new Set(["low", "medium", "high", "critical"]);
 export async function setupWorkspace(input = process.cwd(), payload = {}) {
   const loaded = await loadWorkspace(input);
   const setup = normalizeSetupPayload(payload);
+  setup.classificationId = resolveClassificationId(loaded, setup.classificationId);
   validateSetup(loaded, setup);
   const plan = buildSetupRecords(loaded, setup);
   const updates = [
@@ -44,6 +46,7 @@ export async function setupWorkspace(input = process.cwd(), payload = {}) {
 export async function planWorkspaceSetup(input = process.cwd(), payload = {}) {
   const loaded = await loadWorkspace(input);
   const setup = normalizeSetupPayload(payload);
+  setup.classificationId = resolveClassificationId(loaded, setup.classificationId);
   validateSetup(loaded, setup);
   const plan = buildSetupRecords(loaded, setup);
   return {
@@ -77,7 +80,9 @@ export function summarizeSetupResult(result) {
       commitment: result.commitment ? "saved" : "unchanged"
     },
     system: setupSystemSummary(result.system),
-    target: setupTargetSummary(result.program || result.workspace, { modelVersion: result.program ? "4" : "3" }),
+    target: setupTargetSummary(result.program || result.workspace, {
+      modelVersion: result.workspace?.dataModelVersion || (result.program ? "5" : "3")
+    }),
     renderer: result.renderer ? setupRendererSummary(result.renderer) : null,
     commitment: result.commitment || null,
     onboardingComplete: result.onboardingComplete
@@ -129,7 +134,7 @@ function validateSetup(loaded, setup) {
       throw new Error(`System "${setup.systemId}" cannot be used for initial scope because it is ${system.status}.`);
     }
   }
-  const classifications = String(loaded.model.modelVersion) === "4"
+  const classifications = modelSupports(loaded.model, "program-scope")
     ? loaded.resources.filter(({ type, status }) => type === "classification" && status === "active").map(({ id }) => id)
     : Object.keys(loaded.workspace.classificationDefinitions || {});
   if (classifications.length && !classifications.includes(setup.classificationId)) {
@@ -137,6 +142,21 @@ function validateSetup(loaded, setup) {
   }
 }
 
+function resolveClassificationId(loaded, value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) return value;
+  const candidates = modelSupports(loaded.model, "program-scope")
+    ? loaded.resources
+      .filter(({ type, status }) => type === "classification" && status === "active")
+      .map(({ id, title }) => ({ id, label: title }))
+    : Object.entries(loaded.workspace.classificationDefinitions || {})
+      .map(([id, label]) => ({ id, label }));
+  const matches = candidates.filter(({ id, label }) => (
+    id.toLowerCase() === normalized || String(label || "").trim().toLowerCase() === normalized
+  ));
+  return matches.length === 1 ? matches[0].id : value;
+}
+
 function findSetupSystem(resources, target, setup) {
   const scopedSystemIds = new Set(target.systemIds || []);
   return (setup.systemId && resources.find(({ type, id }) => type === "system" && id === setup.systemId))
@@ -150,7 +170,7 @@ function findSetupSystem(resources, target, setup) {
 
 function buildSetupRecords(loaded, setup) {
   const target = resolveProgram(loaded);
-  const v4 = String(loaded.model.modelVersion) === "4";
+  const v4 = modelSupports(loaded.model, "program-scope");
   const existingSystem = findSetupSystem(loaded.resources, target, setup);
   const systemId = existingSystem?.id || createResourceId(
     "system",
@@ -216,7 +236,7 @@ function buildSetupRecords(loaded, setup) {
     && !["superseded", "retired"].includes(record.status)
     && (record.systemIds || []).includes(systemId)
   ));
-  const commitment = ["3", "4"].includes(String(loaded.model.modelVersion)) && !existingCommitment
+  const commitment = modelSupports(loaded.model, "guided-workflow") && !existingCommitment
     ? {
         id: createResourceId(
           "commitment",
@@ -227,7 +247,7 @@ function buildSetupRecords(loaded, setup) {
         title: `${setup.serviceName} service commitment`,
         status: "planned",
         commitmentKind: "service",
-        statement: "Replace this starter with the actual customer promise or approved service requirement before activation.",
+        statement: "[Complete before activation: State the actual customer promise or approved service requirement.]",
         systemIds: [systemId],
         ownerIds: [setup.ownerId],
         customerFacing: true,

package/src/soc2.js

@@ -0,0 +1,228 @@
+import { modelSupports } from "../model/index.js";
+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 (
+    !modelSupports(modelVersion, "program-scope")
+    || 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 = (modelSupports(modelVersion, "program-scope")
+    ? 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,