feat: complete account-bound profile switching and hardening (#78)
This commit is contained in:
31 files changed
+3612
-197
No files matched your search
@@ -0,0 +1,40 @@
|
||||
# Device Fingerprint Capability Acceptance Checklist
|
||||
|
||||
## Backend Capabilities
|
||||
|
||||
- `get_storage_path / get_storage_dir / get_state_db_path`
|
||||
- `read_profile / write_profile`
|
||||
- `generate_profile`
|
||||
- `sync_service_machine_id / sync_service_machine_id_from_storage`
|
||||
- `load_global_original / save_global_original`
|
||||
- `get_device_profiles`
|
||||
- `bind_device_profile / bind_device_profile_with_profile`
|
||||
- `restore_device_version / delete_device_version`
|
||||
- `restore_original_device`
|
||||
- `open_device_folder`
|
||||
|
||||
## UI Capabilities
|
||||
|
||||
- Show current storage / account binding / history / baseline
|
||||
- Generate and bind
|
||||
- Capture and bind
|
||||
- Restore original fingerprint
|
||||
- Restore history revision
|
||||
- Delete history revision
|
||||
- Open storage folder
|
||||
|
||||
## Switching Behavior
|
||||
|
||||
- Local account switching applies bound fingerprint
|
||||
- Cloud account switching applies bound fingerprint
|
||||
- Concurrent switch requests use queued serial semantics
|
||||
- Failure semantics are fail-fast (no extra transaction orchestration)
|
||||
|
||||
## Compatibility Scope
|
||||
|
||||
- Legacy data missing optional fields: fill defaults
|
||||
- Corrupted structure/type mismatch: explicit failure
|
||||
|
||||
## Status Marking
|
||||
|
||||
Please mark each item as: `Passed / Failed / Diverged (with reason)`.
|
||||
@@ -0,0 +1,50 @@
|
||||
## Context
|
||||
|
||||
Device-fingerprint capability spans the data layer, switch-orchestration layer, and UI management layer.
|
||||
Historical proposals split the same capability across multiple change IDs, which fragmented implementation and acceptance criteria.
|
||||
This design combines "feature completeness + robustness" into a single constraint set to keep implementation, verification, and release aligned.
|
||||
|
||||
## Goals / Non-Goals
|
||||
|
||||
- Goals:
|
||||
- Unify scope and acceptance criteria for device-fingerprint capability.
|
||||
- Ensure behavioral consistency and diagnosability for local/cloud switching.
|
||||
- Keep consistent behavior on default paths across Windows/macOS/Linux.
|
||||
- Keep legacy-data compatibility predictable and verifiable.
|
||||
- Non-Goals:
|
||||
- Support for non-default runtime configuration paths.
|
||||
- Business strategy expansion unrelated to this capability.
|
||||
|
||||
## Decisions
|
||||
|
||||
- Decision: Use a single change ID to manage the complete capability.
|
||||
- Rationale: Reduce governance overhead caused by duplicate proposals.
|
||||
- Decision: Apply fingerprint using a two-phase flow with strict pre-commit verification.
|
||||
- Rationale: Reduce mixed-state risk caused by partial success.
|
||||
- Decision: Use versioned payload + boundary validation for fingerprint/history data.
|
||||
- Rationale: Avoid silent data contamination and define clear compatibility/failure boundaries.
|
||||
- Decision: Use fail-fast semantics for switch failures and return structured failure reasons.
|
||||
- Rationale: Make failure behavior predictable and observable.
|
||||
- Decision: Trigger safe mode for temporary degradation after consecutive failures.
|
||||
- Rationale: Keep switching flow available during fault windows.
|
||||
|
||||
## Risks / Trade-offs
|
||||
|
||||
- Risk: Stricter validation may reject legacy dirty data.
|
||||
- Mitigation: Normalize missing optional fields; fail-fast only for critical structure errors.
|
||||
- Risk: Validation and diagnostic extensions add minor performance cost.
|
||||
- Mitigation: Keep validation lightweight and limited to critical boundaries.
|
||||
- Risk: More UI management actions may increase user misoperations.
|
||||
- Mitigation: Add confirmation interactions and unit-test coverage for failure branches.
|
||||
|
||||
## Migration Plan
|
||||
|
||||
1. Use `update-device-fingerprint-hardening` as the single active proposal.
|
||||
2. Merge historical duplicate proposal content into this proposal (`proposal`/`design`/`tasks`/`spec`).
|
||||
3. Close and remove duplicate proposal directories.
|
||||
4. Deliver with unified task checklist and acceptance checklist.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- Should safe mode exit only by time window, or also allow manual recovery?
|
||||
- Should diagnostic snapshots be exposed in the renderer as a visual panel?
|
||||
@@ -0,0 +1,39 @@
|
||||
# Change: Device Fingerprint Consolidation and Hardening
|
||||
|
||||
## What Changes
|
||||
|
||||
- Unify backend scope:
|
||||
- Fingerprint read/write with synchronized updates to `storage.json` and `state.vscdb`
|
||||
- Account-level binding, revision history, and baseline restore
|
||||
- Fingerprint apply orchestration during switch flows (local/cloud)
|
||||
- Unify management scope:
|
||||
- Device fingerprint management dialog
|
||||
- Generate-and-bind, capture-and-bind, restore revision, delete revision, restore baseline, and open storage folder
|
||||
- Unify robustness scope:
|
||||
- Two-phase apply (`prepare -> verify -> commit`)
|
||||
- Deterministic rollback before commit on failure
|
||||
- Failure reason classification, safe mode, degradation strategy, and diagnostics snapshots
|
||||
- Versioned payload with boundary validation (lenient compatibility + strict failure for critical structure)
|
||||
- Path scope: this stage focuses on the default runtime configuration path.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not promise any anti-detection, anti-ban, or risk-control bypass outcome.
|
||||
- Do not introduce token/protobuf semantic changes unrelated to device fingerprinting.
|
||||
- Do not perform ORM or large database refactors in this change.
|
||||
|
||||
## Impact
|
||||
|
||||
- Affected specs: `device-fingerprint-hardening`
|
||||
- Affected code:
|
||||
- `src/ipc/device/handler.ts`
|
||||
- `src/ipc/account/handler.ts`
|
||||
- `src/ipc/cloud/handler.ts`
|
||||
- `src/ipc/switchFlow.ts`
|
||||
- `src/ipc/switchMetrics.ts`
|
||||
- `src/ipc/database/cloudHandler.ts`
|
||||
- `src/components/DeviceFingerprintDialog.tsx`
|
||||
- `src/actions/account.ts`
|
||||
- `src/actions/cloud.ts`
|
||||
- `src/tests/unit/account.test.ts`
|
||||
- `src/tests/unit/cloudHandler-sync.test.ts`
|
||||
+109
@@ -0,0 +1,109 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Complete Device Fingerprint Management Capability
|
||||
|
||||
The system SHALL provide complete device-fingerprint management capability: view current storage fingerprint, account-bound fingerprint, history revisions, and baseline fingerprint, and execute generate/capture/bind/restore/delete operations.
|
||||
|
||||
#### Scenario: Open device fingerprint management
|
||||
|
||||
- **WHEN** an operator opens device fingerprint management for a specific account
|
||||
- **THEN** the system returns current storage fingerprint, account-bound fingerprint, history revisions, and baseline fingerprint (if present)
|
||||
|
||||
#### Scenario: Generate and bind a new fingerprint
|
||||
|
||||
- **WHEN** the operator confirms "Generate and Bind"
|
||||
- **THEN** the system generates a valid new fingerprint and binds it to the target account
|
||||
- **AND** the new revision is appended to history and marked as current
|
||||
|
||||
#### Scenario: Capture current and bind
|
||||
|
||||
- **WHEN** the operator confirms "Capture Current and Bind"
|
||||
- **THEN** the system reads the current storage fingerprint and binds it to the target account
|
||||
- **AND** a new revision is appended to history
|
||||
|
||||
### Requirement: Switch Flow Must Apply Account-Bound Fingerprint
|
||||
|
||||
The system SHALL ensure the target account has a valid bound fingerprint before continuing switch flow for both local-account and cloud-account switching.
|
||||
|
||||
#### Scenario: Target account has no bound fingerprint during switching
|
||||
|
||||
- **GIVEN** the target account exists and has no bound fingerprint
|
||||
- **WHEN** account switching is initiated
|
||||
- **THEN** the system automatically generates and binds a usable fingerprint
|
||||
- **AND** then continues with the switch flow
|
||||
|
||||
#### Scenario: Concurrent switch requests
|
||||
|
||||
- **WHEN** multiple switch requests are triggered while a switch is in progress
|
||||
- **THEN** requests are queued and processed serially
|
||||
- **AND** no concurrent write conflicts occur
|
||||
|
||||
### Requirement: Fingerprint Apply Must Preserve Storage Consistency
|
||||
|
||||
The system SHALL update `storage.json` and `state.vscdb` in sync when applying device fingerprint, and SHALL ensure `storage.serviceMachineId` equals `devDeviceId`.
|
||||
|
||||
#### Scenario: Normal fingerprint apply
|
||||
|
||||
- **WHEN** the system applies a device fingerprint
|
||||
- **THEN** telemetry fields in `storage.json` are updated
|
||||
- **AND** `storage.serviceMachineId` is updated to `devDeviceId`
|
||||
- **AND** `ItemTable['storage.serviceMachineId']` in `state.vscdb` is updated accordingly
|
||||
|
||||
### Requirement: Device Fingerprint Apply Uses Two-Phase Protocol
|
||||
|
||||
The system SHALL execute device-fingerprint apply with a two-phase protocol (`prepare -> verify -> commit`), and SHALL perform deterministic rollback when failure occurs before commit.
|
||||
|
||||
#### Scenario: Failure during verify phase
|
||||
|
||||
- **WHEN** prepare writes succeed but verify detects inconsistent state
|
||||
- **THEN** the system rolls back to pre-apply state
|
||||
- **AND** returns a classifiable failure reason
|
||||
|
||||
#### Scenario: Write failure before commit
|
||||
|
||||
- **WHEN** any critical write fails before commit completes
|
||||
- **THEN** the system performs rollback
|
||||
- **AND** post-operation state equals pre-operation state
|
||||
|
||||
### Requirement: Fingerprint Data Uses Versioned Structure and Boundary Validation
|
||||
|
||||
The system SHALL use explicit schema versions for fingerprint and history data, and SHALL validate at read/write boundaries.
|
||||
|
||||
#### Scenario: Missing optional fields
|
||||
|
||||
- **WHEN** history payload lacks optional fields
|
||||
- **THEN** the system fills default values and continues
|
||||
|
||||
#### Scenario: Critical structure corruption or type mismatch
|
||||
|
||||
- **WHEN** payload has critical structure corruption or critical field type mismatch
|
||||
- **THEN** the system fails fast and returns a readable error
|
||||
|
||||
### Requirement: Consecutive Failures Trigger Safe Degradation
|
||||
|
||||
The system SHALL enter safe mode when consecutive device-fingerprint apply failures reach a threshold, temporarily disable fingerprint apply, keep switching available, and emit warnings.
|
||||
|
||||
#### Scenario: Consecutive-failure threshold reached
|
||||
|
||||
- **WHEN** consecutive failures reach the threshold
|
||||
- **THEN** safe mode is activated and fingerprint apply is temporarily disabled
|
||||
- **AND** switch flow remains available under warning conditions
|
||||
|
||||
### Requirement: Provide Observable Diagnostic Snapshot
|
||||
|
||||
The system SHALL expose a read-only diagnostics interface returning switch-guard state, switch counters, failure-reason counters, latest failure metadata, and safe-mode state.
|
||||
|
||||
#### Scenario: Query diagnostics after failures
|
||||
|
||||
- **WHEN** diagnostics are queried after one or more failures
|
||||
- **THEN** reason-classified failure counters are returned
|
||||
- **AND** latest failure details and safe-mode state are returned
|
||||
|
||||
### Requirement: Path Resolution Scope Constraint
|
||||
|
||||
The system SHALL use default runtime configuration paths for path resolution in this capability.
|
||||
|
||||
#### Scenario: Use default runtime configuration paths
|
||||
|
||||
- **WHEN** the system performs device-fingerprint-related path resolution
|
||||
- **THEN** resolution is completed based on default runtime configuration paths
|
||||
@@ -0,0 +1,44 @@
|
||||
## 1. Proposal Consolidation
|
||||
|
||||
- [x] 1.1 Merge duplicate device-fingerprint proposals into `update-device-fingerprint-hardening`.
|
||||
- [x] 1.2 Unify scope and terminology across proposal/design/spec.
|
||||
- [ ] 1.3 Complete proposal archival strategy (archive after release).
|
||||
|
||||
## 2. Feature Completeness (Backend)
|
||||
|
||||
- [x] 2.1 Provide APIs for querying/binding/restoring/deleting fingerprint history.
|
||||
- [x] 2.2 Provide API to restore original device fingerprint.
|
||||
- [x] 2.3 Provide API to open fingerprint storage folder.
|
||||
- [x] 2.4 Reuse unified fingerprint-apply chain for local and cloud switching.
|
||||
|
||||
## 3. Feature Completeness (UI)
|
||||
|
||||
- [x] 3.1 Provide management entry via `DeviceFingerprintDialog`.
|
||||
- [x] 3.2 Support generate-and-bind, capture-and-bind, restore history, and delete history.
|
||||
- [x] 3.3 Support restore original fingerprint and open storage folder.
|
||||
- [x] 3.4 Complete i18n copy and error messaging.
|
||||
|
||||
## 4. Robustness Hardening
|
||||
|
||||
- [x] 4.1 Implement two-phase apply in `src/ipc/device/handler.ts` (`prepare -> verify -> commit`).
|
||||
- [x] 4.2 Perform deterministic rollback on pre-commit failure.
|
||||
- [x] 4.3 Introduce failure-reason classification and integrate with `src/ipc/switchMetrics.ts`.
|
||||
- [x] 4.4 Introduce versioned payload and strict boundary validation.
|
||||
- [x] 4.5 Introduce safe mode and recovery strategy.
|
||||
- [x] 4.6 Extend diagnostics snapshot (failure-reason counts, latest failure metadata, safe-mode status).
|
||||
|
||||
## 5. Verification
|
||||
|
||||
- [x] 5.1 Run `npm run type-check`.
|
||||
- [x] 5.2 Run targeted unit tests:
|
||||
- `npm run test:unit src/tests/unit/account.test.ts`
|
||||
- `npm run test:unit src/tests/unit/cloudHandler-sync.test.ts`
|
||||
- [ ] 5.3 Add/extend rollback invariant unit tests.
|
||||
- [ ] 5.4 Add/extend abnormal history-data behavior unit tests.
|
||||
- [ ] 5.5 Add/extend unit tests for platform-constrained generation rules.
|
||||
- [ ] 5.6 Complete manual acceptance matrix across Windows/macOS/Linux.
|
||||
|
||||
## 6. Delivery Documentation
|
||||
|
||||
- [ ] 6.1 Produce a unified acceptance checklist and mark status item by item.
|
||||
- [ ] 6.2 Archive merged proposals after release.
|
||||
Reference in new issue
Block a user