# Walkthrough: Architecture Benchmark 01, Security Hardening & Remote Command Control Plane **Date**: 2026-09-22 **Target Systems**: - **ClassNotify Server**: ASP.NET Core 8 WebAPI & SignalR Hub (`https://classnotify.paradise.eu.org`) - **ClassNotify Windows Service**: .NET 8 Background Service (Session 0 LocalSystem) - **ClassNotify Client**: .NET 8 WPF Desktop Client (Interactive User Session) - **ClassNotify Database**: PostgreSQL 16 on Oracle Linux VPS (Tokyo) --- ## 1. Executive Summary & Review Verdict Across P1 Batches 8, 9, and 10, ClassNotify has achieved enterprise-grade hardening across edge credentials, notification delivery, and remote device command control planes: - **P1 Batch 8 (Edge Credential & IPC Hardening)**: Formally `SEALED & APPROVED` (Snapshot `20260921-233339-75238B30`). - **P1 Batch 9 (Offline Delivery / Pending Receipt + TTL)**: Formally `SEALED & APPROVED` (Snapshot `20260922-064320-19629A5E`). - **P1 Batch 10 (Remote Command Reliability, Idempotency & Audit Trail)**: Fully implemented and verified with 100% test pass rate (13/13 Automated CommandTests + 6/6 Physical Real E2E Tests). --- ## 2. P1 Batch 8: Windows Edge Credential & IPC Hardening (Sealed & Approved) Following the approved Architecture Benchmark 01, P1 Batch 8 resolved two critical Windows edge security vectors: 1. **DPAPI LocalMachine + Hardened NTFS File ACLs**: - Encrypted `device_credentials.json` with DPAPI `DataProtectionScope.LocalMachine`. - Strict Fail-Closed ACL enforcement: `SYSTEM` and `Administrators` only; ordinary users blocked. 2. **IPC Defense-in-Depth Handshake**: - Ephemeral 128-bit GUID launch token via `--ipc-token `. - 4-way verification: Process Name, PID, Session ID, and Token. --- ## 3. P1 Batch 9: Offline Delivery, Pending Receipt & Business TTL (Sealed & Approved) P1 Batch 9 implemented an end-to-end, resilient offline notification delivery mechanism: 1. **Durable Intent & Business TTL**: - `ExpiresAt` column, composite indexes, and type-based TTL policies (Call=10m, Notice=60m, Urgent=24h). - Zero replay of legacy notifications via SQL backfill and runtime suppression. 2. **ClientNotificationBuffer**: - `SemaphoreSlim(1,1)` lock, atomic Peek-then-Dequeue, and backlog barrier preserving strict FIFO order. 3. **Dual Fail-Closed Publishing Gate**: - Sanitization of all text files and fail-closed secret scanning in `Publish-AuditSnapshot.ps1`. --- ## 4. P1 Batch 10: Remote Command Reliability, Idempotency & Audit Trail ### 4.1 Architecture & Core Design Batch 10 established a dependable, secure, and fully audited remote command control plane: ```mermaid sequenceDiagram autonumber actor Teacher as Teacher / Admin (Web) participant Server as ClassNotify Server (API & SignalR) participant DB as PostgreSQL Database participant Service as Windows Service (Session 0) participant Deduplicator as DeviceCommandDeduplicator participant Client as WPF Client (Session 4) Teacher->>Server: POST /api/v1/commands/dispatch (CommandType, TargetDeviceId) Note over Server: Whitelist Check & Tenant Ownership Isolation Server->>DB: INSERT DeviceCommand (Status=Pending, ExpiresAt) Server->>Service: SignalR DeviceHub.ExecuteDeviceCommand(dto) Note over Server: Status -> Dispatched Service->>Deduplicator: TryRegister(CommandId) alt Already Processed (Duplicate / Reconnect) Deduplicator-->>Service: Reject (Cached Result) Service->>Server: ReportCommandResult(CachedResult) else New Valid Command Deduplicator-->>Service: Accept (Acquire Execution) alt CommandType == SelfCheck Service->>Service: Run Health Check (DNS, HTTPS, SignalR, Pipe, TTS) else CommandType == RestartClient Service->>Client: IPC Terminate / Kill Process Service->>Service: SessionLauncher.LaunchInteractiveClient(SessionId) end Service->>Server: SignalR DeviceHub.ReportCommandResult(CommandId, Code, Duration, Message) Server->>DB: UPDATE DeviceCommand (Status=Succeeded/Failed, CompletedAt, Result) Server->>Teacher: SignalR TeacherHub.OnDeviceCommandStatusChanged(dto) end ``` ### 4.2 Key Technical Features & Invariants 1. **Strict Command Whitelist**: - Only 4 safe diagnostic/maintenance commands are accepted: `SelfCheck`, `RestartClient`, `Reconnect`, `RefreshConfig`. - Arbitrary commands (e.g. `rm -rf`, `powershell`, `cmd`, `calc.exe`) are rejected at the API controller with HTTP 400. 2. **Device & Multi-Tenant Strong Isolation**: - Dispatch requests verify caller's tenant ownership. Calling a device in another tenant returns HTTP 403 Forbidden. - Result reporting in `DeviceHub.ReportCommandResult` strictly verifies caller's authenticated `DeviceId` matches `command.DeviceId`. Cross-device spoofing returns HTTP 403 Forbidden. 3. **Short-Lived TTL & Expired Policy**: - `RestartClient` / `Reconnect`: TTL = 2 minutes. - `SelfCheck` / `RefreshConfig`: TTL = 5 minutes. - Expired commands are marked `Expired` on dispatch or query and are never executed upon late reconnect. 4. **In-Memory Sliding-Window Deduplication**: - `DeviceCommandDeduplicator` in `ClassNotify.Shared` maintains a bounded concurrent cache with sliding expiration. - Replayed command IDs return prior execution results without invoking redundant side effects. 5. **Session 0 to Session 4 Interactive Process Relaunch**: - Fixed Windows desktop station issue (`0xC0000142`): cleared `lpDesktop` to allow default interactive desktop assignment. - Token session assignment via Win32 `SetTokenInformation` ensuring correct session binding. - Supported CLI arguments via `Environment.GetCommandLineArgs()` in single-file WPF .NET 8 client. --- ## 5. Verification & Test Metrics ### 5.1 Automated Command Test Suite (`ClassNotify.CommandTests` — 13/13 Passed) ```text Test Run Successful. Total tests: 13 Passed: 13 Failed: 0 Duration: 4.8s ``` - `[PASS] Whitelist_Rejects_NonWhitelistedCommands` - `[PASS] Tenant_Cannot_Dispatch_Command_To_Another_Tenant_Device` - `[PASS] Device_Cannot_Report_Result_For_Another_Device_Command` - `[PASS] Expired_Command_Is_Rejected_And_Marked_Expired` - `[PASS] Deduplicator_Prevents_Duplicate_Execution` - `[PASS] Deduplicator_Releases_Capacity_When_Expired` - `[PASS] Status_Machine_Validates_Legal_Transitions` - `[PASS] SelfCheck_Execution_Returns_Sanitized_Health_Summary` - `[PASS] RestartClient_Command_Signals_Process_Relaunch` - `[PASS] Query_Filters_By_Device_Status_And_Type` - `[PASS] Unresponsive_Command_Normalizes_To_TimedOut` - `[PASS] TeacherHub_Broadcasts_Status_Change_Event` - `[PASS] SignalR_Disconnect_Reconnect_Preserves_Audit_Record` ### 5.2 Physical Real E2E Test Suite (`tests/test_command_real_e2e.ps1` — 6/6 Passed) ```text ========================================================== ClassNotify P1 Batch 10: Live Physical Remote Command E2E Test (Windows Service + Live Server + Real Client) ========================================================== >>> [1/6] Verifying Local Environment & Device Credentials... [PASS] Local Environment & Device Credentials Healthy (dev_b510ddb1, PID: 41604) >>> [2/6] Authenticating Teacher on Server... [PASS] Teacher Authentication Succeeded (User: 张老师, Role: Teacher) >>> [3/6] Testing Whitelist Enforcement (Rejection of Non-Whitelisted Commands)... [PASS] Server Strictly Rejects Arbitrary / Non-Whitelisted Commands (rm -rf, powershell, etc.) >>> [4/6] Dispatching 'SelfCheck' Remote Command via Live SignalR... [PASS] Live 'SelfCheck' Executed & Reported Succeeded by Windows Service ResultCode=0, Message: Self-check completed: overall=Healthy... >>> [5/6] Dispatching 'RestartClient' Remote Command (Physical Process Relaunch)... [PASS] Physical Client Process Restarted via Remote Command Old PID: 41604 -> New PID: 36168, Status: Succeeded, Code: 0 >>> [6/6] Verifying Remote Command Audit Trail & History... [PASS] Audit Trail Recorded Both Commands with Status, Timestamps, and Result Codes Found SelfCheck: True, Found RestartClient: True, Total Records: 6 ========================================================== Test Summary: 6 Passed, 0 Failed (100%) ========================================================== ``` ### 5.3 Regression Test Suites - **`ClassNotify.AuthTests`**: 12/12 Passed - **`ClassNotify.RateLimitTests`**: 3/3 Passed - **`ClassNotify.DeliveryTests`**: 14/14 Passed (InMemory) - **`ClassNotify.EdgeSecurityTests`**: 13/13 Passed - **`ClassNotify.sln`**: Release Build 0 Errors, 0 Warnings