Add enterprise data residency guard

README.md

@@ -1,2 +1,4 @@
 # deepevents.ai
 deepevents.ai main codebase
+
+- `enterprise-data-residency-guard/` adds enterprise data residency and cross-border transfer controls for institutional research operations.

enterprise-data-residency-guard/README.md

@@ -0,0 +1,33 @@
+# Enterprise Data Residency Guard
+
+Institutional customers need proof that research artifacts, identities, exports, and webhook deliveries stay inside approved data regions unless a transfer impact review says otherwise. This module turns tenant policy, research records, and destination metadata into deterministic decisions for admins.
+
+## What It Covers
+
+- Region-aware transfer decisions for repository exports, LMS sync, journals, funder portals, and lab notebooks.
+- Research data classifications including public metadata, unpublished manuscripts, controlled human-subject data, PHI, grant reports, and embargoed preprints.
+- Admin dashboard metrics for approved, review, and blocked transfers.
+- Webhook-safe event envelopes with deterministic digests.
+- Export manifest entries that preserve residency evidence without credentials.
+
+## Run It
+
+```bash
+npm run check
+npm test
+npm run demo
+```
+
+## Reviewer Notes
+
+- Synthetic data only. No credentials, protected health data, or real institution records.
+- Zero dependencies. The logic uses Node built-ins so reviewers can run it offline.
+- The sample shows one blocked PHI transfer, two manual reviews, and approved in-region exports.
+
+## Files
+
+- `src/data-residency-guard.js` - residency policy evaluator and helpers.
+- `data/sample-residency-input.json` - synthetic tenants, destinations, and records.
+- `test/data-residency-guard.test.js` - coverage for decisions, dashboard metrics, digest stability, and manifest output.
+- `docs/requirement-map.md` - issue #19 acceptance mapping.
+- `docs/demo.svg` and `docs/demo.gif` - short visual proof artifacts for the demo run.

enterprise-data-residency-guard/data/sample-residency-input.json

@@ -0,0 +1,168 @@
+{
+  "generatedAt": "2026-05-16T08:50:00.000Z",
+  "tenants": [
+    {
+      "id": "tenant-eu-biology",
+      "name": "Helmholtz Biology Institute",
+      "homeRegion": "EU",
+      "allowedRegions": ["EU", "EEA"],
+      "regimes": ["GDPR", "HorizonEU"],
+      "policy": {
+        "requiresDpaForCrossBorder": true,
+        "requiresSccForNonAdequateRegion": true,
+        "requiresHumanReviewForSensitiveData": true,
+        "blockedClassifications": ["phi"],
+        "embargoExportsRequireRelease": true
+      }
+    },
+    {
+      "id": "tenant-us-clinical",
+      "name": "Midwest Translational Lab",
+      "homeRegion": "US",
+      "allowedRegions": ["US"],
+      "regimes": ["HIPAA", "NIH"],
+      "policy": {
+        "requiresDpaForCrossBorder": true,
+        "requiresSccForNonAdequateRegion": false,
+        "requiresHumanReviewForSensitiveData": true,
+        "blockedClassifications": ["phi"],
+        "embargoExportsRequireRelease": true
+      }
+    },
+    {
+      "id": "tenant-uk-social",
+      "name": "Northshire Social Science Centre",
+      "homeRegion": "UK",
+      "allowedRegions": ["UK", "EU", "US"],
+      "regimes": ["UK-GDPR", "UKRI"],
+      "policy": {
+        "requiresDpaForCrossBorder": false,
+        "requiresSccForNonAdequateRegion": true,
+        "requiresHumanReviewForSensitiveData": false,
+        "blockedClassifications": [],
+        "embargoExportsRequireRelease": true
+      }
+    }
+  ],
+  "destinations": [
+    {
+      "id": "zenodo-eu",
+      "name": "Zenodo",
+      "type": "repository",
+      "region": "EU",
+      "adequacy": true,
+      "hasDpa": true,
+      "supportsRestrictedAccess": true
+    },
+    {
+      "id": "pubmed-us",
+      "name": "PubMed Central",
+      "type": "repository",
+      "region": "US",
+      "adequacy": true,
+      "hasDpa": true,
+      "supportsRestrictedAccess": true
+    },
+    {
+      "id": "canvas-us",
+      "name": "Canvas LMS",
+      "type": "lms",
+      "region": "US",
+      "adequacy": true,
+      "hasDpa": false,
+      "supportsRestrictedAccess": false
+    },
+    {
+      "id": "journal-apac",
+      "name": "Pacific Journal Portal",
+      "type": "journal",
+      "region": "APAC",
+      "adequacy": false,
+      "hasDpa": false,
+      "supportsRestrictedAccess": true
+    },
+    {
+      "id": "dspace-uk",
+      "name": "Institutional DSpace",
+      "type": "repository",
+      "region": "UK",
+      "adequacy": true,
+      "hasDpa": true,
+      "supportsRestrictedAccess": true
+    }
+  ],
+  "records": [
+    {
+      "id": "rec-astro-open-data",
+      "tenantId": "tenant-uk-social",
+      "title": "Open survey response codebook",
+      "classification": "public-metadata",
+      "sourceRegion": "UK",
+      "destinationId": "dspace-uk",
+      "workflow": "repository-sync",
+      "embargoUntil": null,
+      "containsHumanSubjects": false,
+      "deidentified": true
+    },
+    {
+      "id": "rec-eu-manuscript",
+      "tenantId": "tenant-eu-biology",
+      "title": "Unpublished microscopy manuscript",
+      "classification": "unpublished-manuscript",
+      "sourceRegion": "EU",
+      "destinationId": "zenodo-eu",
+      "workflow": "preprint-deposit",
+      "embargoUntil": null,
+      "containsHumanSubjects": false,
+      "deidentified": true
+    },
+    {
+      "id": "rec-eu-clinical-supplement",
+      "tenantId": "tenant-eu-biology",
+      "title": "Clinical supplement with rare disease cohort",
+      "classification": "phi",
+      "sourceRegion": "EU",
+      "destinationId": "journal-apac",
+      "workflow": "journal-submission",
+      "embargoUntil": null,
+      "containsHumanSubjects": true,
+      "deidentified": false
+    },
+    {
+      "id": "rec-us-patient-dashboard",
+      "tenantId": "tenant-us-clinical",
+      "title": "Patient dashboard screenshots for teaching",
+      "classification": "controlled-human-data",
+      "sourceRegion": "US",
+      "destinationId": "canvas-us",
+      "workflow": "lms-sync",
+      "embargoUntil": null,
+      "containsHumanSubjects": true,
+      "deidentified": false
+    },
+    {
+      "id": "rec-uk-grant-report",
+      "tenantId": "tenant-uk-social",
+      "title": "UKRI project outcome packet",
+      "classification": "grant-report",
+      "sourceRegion": "UK",
+      "destinationId": "pubmed-us",
+      "workflow": "funder-export",
+      "embargoUntil": null,
+      "containsHumanSubjects": false,
+      "deidentified": true
+    },
+    {
+      "id": "rec-eu-embargoed-preprint",
+      "tenantId": "tenant-eu-biology",
+      "title": "Embargoed CRISPR preprint package",
+      "classification": "embargoed-preprint",
+      "sourceRegion": "EU",
+      "destinationId": "pubmed-us",
+      "workflow": "preprint-deposit",
+      "embargoUntil": "2026-07-01",
+      "containsHumanSubjects": false,
+      "deidentified": true
+    }
+  ]
+}

enterprise-data-residency-guard/docs/requirement-map.md

@@ -0,0 +1,17 @@
+# Requirement Map
+
+Issue: SCIBASE-AI/SCIBASE.AI#19 Enterprise Tooling
+
+| Requirement area | Evidence in this module |
+| --- | --- |
+| Admin dashboard controls | `dashboard.metrics`, destination breakdowns, and `dashboard.queue` in `src/data-residency-guard.js`. |
+| Compliance tracking | GDPR, HorizonEU, HIPAA, NIH, UK-GDPR, and UKRI regimes in sample tenant policy. |
+| API and webhooks | `webhookEvents` emits signed `scibase.residency.*` envelopes with deterministic digests. |
+| Export pipelines | `exportManifest` records residency routes, decision states, finding codes, and evidence digests. |
+| Institutional repository and LMS integrations | Synthetic routes include Zenodo, PubMed Central, Canvas LMS, DSpace, and a journal portal. |
+| Custom tags or flags for internal initiatives | Classification and workflow metadata produce decision queues for restricted, embargoed, and public records. |
+| Reviewer proof | `npm run check`, `npm test`, `npm run demo`, `docs/demo.svg`, and `docs/demo.gif`. |
+
+## Distinct Slice
+
+Existing #19 attempts focus on dashboards, export packaging, compliance packets, webhooks, identity drift, and retention holds. This module focuses on data residency and transfer impact decisions before exports or webhooks leave an institutional boundary.

enterprise-data-residency-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "enterprise-data-residency-guard",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Enterprise data residency and transfer impact guard for SCIBASE institutional tooling.",
+  "scripts": {
+    "check": "node --check src/data-residency-guard.js && node --check scripts/demo.js && node --check test/data-residency-guard.test.js",
+    "test": "node --test test/data-residency-guard.test.js",
+    "demo": "node scripts/demo.js"
+  }
+}

enterprise-data-residency-guard/scripts/demo.js

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { evaluateResidency, renderTextReport } from "../src/data-residency-guard.js";
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(moduleDir, "..");
+const inputPath = path.join(rootDir, "data", "sample-residency-input.json");
+const input = JSON.parse(fs.readFileSync(inputPath, "utf8"));
+
+const report = evaluateResidency(input);
+console.log(renderTextReport(report));