Skip to content

SmrtHub Retention & Legal Hold Plan (Phase 3)

Last updated: 2025-11-20

1. Purpose & Scope

  • Establish the canonical models, config locations, and evidence flows for retention policies and legal holds introduced in Phase 3 of the Compliance roadmap.
  • Provide a single reference that engineering, support, and compliance teams can follow while HubWindow’s WinUI3 UI is still under construction.
  • Applies to all SmrtHub runtimes (Supervisor, Storage Guard service host, Support Bundle exporter, python_core automation).

2. Control Surfaces

2.1 Production (future)

  • HubWindow Settings ➜ Advanced ➜ "Retention & Legal Holds" (WinUI3)
  • Two panels: Retention Policies and Legal Holds.
  • Uses shared models from Smrt.Retention (see section 3) and persists via Smrt.Config into canonical JSON files.
  • Presents audit metadata (last verification time, next run, outstanding alerts).

2.2 Interim (development/testing)

  • Supervisor configuration
  • appsettings.json gains RetentionPolicies + LegalHoldStore sections referencing shared JSON artifacts.
  • Supervisor CLI verbs:
    • --retention-status (dump effective policy + verification health)
    • --add-legal-hold --name <string> --provider <slug> --scope <path/pattern> --reason <string>
    • --clear-legal-hold --id <guid>
    • --export-retention-evidence (copies the latest verification report + policy snapshots for manual review).
  • Temporary system tray action
  • HubWindow tray menu exposes "Open Retention Config Folder" to help admins edit JSON until WinUI landing page is ready.

3. Shared Models (SmrtApps/src/Smrt.Retention)

Type Purpose Fields
RetentionPolicy Defines per-provider windows & safeguards ProviderSlug, DisplayName, RetentionDays, MinimumCopies, FreeSpaceFloorPercent, MaxArtifactSizeMb, Notes
LegalHold Represents an active hold Id (Guid), Name, ProviderSlug, Scope (path pattern or label), CreatedUtc, CreatedBy, ExpiresUtc?, Reason, Tickets, IsSystemHold
RetentionConfiguration Root persisted via Smrt.Config DefaultPolicy, Policies[], LegalHolds[], EmergencyPurgeAllowed, LastUpdatedUtc, UpdatedBy
RetentionEvidence Output of verification worker VerificationId, GeneratedUtc, PoliciesHash, LegalHoldHash, Providers[], Warnings[], Errors[], SignaturePath

3.1 Validation Rules

  • RetentionDays: 1–9999 and ≤ 731: enforce corporate upper bounds (default 365).
  • MinimumCopies: default 1, cannot exceed 10.
  • FreeSpaceFloorPercent: default 15%; if breached, verification logs a warning and marks provider Degraded.
  • LegalHold.Scope: supports folder glob (c:\data\*), provider-native label (sharepoint:Site/Library), or artifact tag.
  • Legal holds override retention windows; artifacts matching any active hold are excluded from purge plans.
  • All models serialized via ConfigJson.AtomicWrite to %ProgramData%/SmrtHub/Config/retention/retention-policy.json (shared) with .bak backup.

4. Evidence & Storage Locations

Artifact Path Producer Notes
Policies JSON %ProgramData%/SmrtHub/Config/retention/retention-policy.json Supervisor/HubWindow Shared by all hosts; fall back to %LocalAppData% on dev boxes.
Legal holds JSON %ProgramData%/SmrtHub/Config/retention/legal-holds.json Supervisor/HubWindow Same atomic write guarantees.
Verification reports %ProgramData%/SmrtHub/Logs/system-info/retention/retention-verification.json (daily) + .sig Storage Guard service Signed by Storage Guard shared secret; includes hash of policies + holds.
CLI exports %ProgramData%/SmrtHub/Logs/system-info/retention/exports/* Supervisor CLI Zips latest policy + evidence for auditors.

4.1 Development Seed Data

  • The repo now ships mocked retention artifacts so Support Bundle previews and SmrtSupport presets surface realistic evidence without waiting on the production verification worker.
  • Seeds live under SmrtHub/Config/retention/ (policies + legal holds) and SmrtHub/Logs/system-info/retention/ (verification JSON, .sig, health summary, provider logs).
  • The sample verification references OneDrive Enterprise and iCloud Drive so the Compliance preset aligns with the seeded legal holds. Refresh the files whenever presets introduce new providers or hashes.

5. Scheduled Verification Job

5.1 Host & Cadence

  • Lives inside Smrt.StorageGuard.ServiceHost as RetentionVerificationWorker.
  • Default cadence: every 6 hours (RetentionVerification:IntervalMinutes), overridable via config.
  • Shares the existing secret + signing infrastructure; writes JSON + HMAC signature per run.

5.2 Workflow

  1. Load RetentionConfiguration + LegalHolds via Smrt.Config.
  2. Enumerate providers using provider adapters (OneDrive, SharePoint, SMB, LocalArchive) defined in Smrt.Retention.Providers.
  3. For each provider, gather:
  4. Actual stored artifacts (counts, age distribution, free space, applied labels).
  5. Legal hold coverage (which artifacts are hold-protected).
  6. Compare findings to policy constraints and record results (Pass/Warning/Error) with remediation guidance.
  7. Emit structured log events under slug retention-verifier and append to the signed report.
  8. Notify Supervisor by writing a health summary to %ProgramData%/SmrtHub/Logs/system-info/retention/retention-health.json with Status: Healthy|Warning|Error and ConsecutiveFailures.

5.3 Alerting & Telemetry

  • Smrt.Logging: events include VerificationId, Provider, Status, ActionRequired, LegalHoldCount.
  • Supervisor metrics: ingestion thread reads retention-health.json and surfaces status on the health endpoint + CLI.
  • Support Bundle: new provider (section 7) copies the latest retention-verification.json, .sig, and retention-health.json.

6. Interim Automation & CLI

  • Supervisor CLI verbs (see section 2.2) call into Smrt.Retention helpers to mutate policies/holds with validation.
  • Add SmrtHubSupervisor:Retention config section documenting: 
    {
  "Retention": {
    "PolicyPath": "%ProgramData%/SmrtHub/Config/retention/retention-policy.json",
    "LegalHoldPath": "%ProgramData%/SmrtHub/Config/retention/legal-holds.json",
    "Cli": { "RequireAdmin": true }
  }
}
  • Provide PowerShell helper script Tools/Retention/Invoke-RetentionCli.ps1 for unattended automation.

7. Support Bundle Integration

  • Smrt.SupportBundle now ships with RetentionEvidenceProvider, which packages:
  • retention-policy.json
  • legal-holds.json
  • Latest retention-verification.json + .sig
  • retention-health.json
  • Provider-specific automation logs dropped under %ProgramData%/SmrtHub/Logs/system-info/retention/providers/<slug>/*.json
  • The provider mirrors Storage Guard handling—artifacts are copied under system-info/retention/ and participate in sanitization, manifest hashing, and review reports.
  • Follow-up: update bundle manifest schema to expose a RetentionEvidence summary (per-provider status + verification timestamp) and add redaction-focused tests for legal hold reasons.

8. Operator Workflow & Evidence Checklist

  • Daily/weekly validation
  • Supervisor CLI – run SmrtHubSupervisor.exe --retention-status to confirm the active policy, legal holds, and last verification time. Use --retention-export --output <network share> to stage the JSON artifacts whenever compliance requests evidence.
  • Storage Guard verification – confirm that retention-verifier events are present in SmrtHub/Logs/system-info/retention/retention-health.json and that the signed snapshot (storage-guard.json + .sig) now includes the Retention payload. If the Status is Warning/Error, capture the associated log files before remediation.
  • Support Bundle capture – trigger SupportBundleExporter (through HubWindow tray or CLI harness) with ExportCategories.SystemInfo enabled. Validate that the bundle contains system-info/storage-guard.json, system-info/storage-guard.sig, system-info/storage-guard-verification.json, and the full system-info/retention/ folder (policies, legal holds, verification JSON + .sig, health summary, provider logs).
  • Archive & ticket – attach the retention export directory and the Support Bundle ZIP to the compliance ticket, recording operator ID and timestamp. SnapRun support deletes received bundles after the case closes per the Privacy/Security policy.
  • Escalation path
  • If Supervisor CLI returns a validation error, fix the JSON locally and retry --retention-apply. For production, always supply --updated-by <corp operator> so audit trails capture ownership.
  • If Storage Guard verification fails cryptographically, run SmrtHubSupervisor.exe --retention-export and attach the failing snapshot/signature pair so engineering can diagnose mismatches.
  • If Support Bundle is missing retention evidence, ensure the Storage Guard/retention directories exist under %ProgramData%/SmrtHub and rerun with elevated privileges.

9. Provider Automation & Runbooks

Provider Automation Evidence Captured
OneDrive / SharePoint Microsoft Graph PowerShell module scripts assign retention labels + legal holds. Scripts output JSON summaries stored under providers/sharepoint/*.json. Label status per site/library, hold coverage list, last run timestamp.
SMB / File Server Windows FSRM templates enforce quotas + retention tasks (scheduled via Task Scheduler). Logs under providers/smb/*.json show job outcome + list of deleted/preserved files.
Local Archive / External Drives Operator checklist (signed) maintained in %ProgramData%/SmrtHub/Logs/system-info/retention/providers/local-archive/acknowledgement.json. Includes device serial, seal status, handoff ticket.
Cloud Buckets (future) Placeholder for S3/Azure Blob policies; spec reserved for Phase 4+.

Runbacks live in MKDocs/docs/runbooks/Retention/ with mirrored entries summarized in README.Files/SmrtHub-Retention-and-LegalHold.README.md once automation ships.

10. Testing Expectations

  • Unit tests inside SmrtApps/tests/Smrt.Retention.Tests covering model validation, serialization, and policy conflict detection.
  • Integration tests for Storage Guard worker verifying signed outputs + failure scenarios (missing provider adapter, insufficient free space, expired hold).
  • Supervisor CLI tests ensuring commands mutate JSON atomically and reject invalid inputs.
  • Support Bundle tests verifying new provider captures files and redactions.

11. Implementation Roadmap

  1. Scaffold Smrt.Retention library + tests.
  2. Wire Supervisor config + CLI to use shared library.
  3. Implement RetentionVerificationWorker inside Storage Guard host; produce evidence files + telemetry.
  4. Add Support Bundle provider + automation logs ingestion.
  5. Author runbooks + MKDocs page referencing this plan.
  6. Integrate HubWindow UI once advanced settings shell is ready.

Questions or updates: coordinate via Phase 3 tracking issue; update this README when behavior changes or new providers are added.