mirror of
https://github.com/binaricat/Netcatty.git
synced 2026-11-16 20:11:08 +00:00
* feat: add a global default proxy with an explicit direct override Resolve the proxy as the host setting, then the nearest group default, then one optional saved profile from synced settings, then a direct connection. A host can choose direct and skip both inherited defaults. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> * fix: keep global default proxy persistence across settings instances Unregister only the setter owned by the unmounting useSettingsState instance so closing Settings still writes the cleared default through the remaining AppLockGate setter. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> * fix: round-trip explicit direct mode in vault CSV Write the Proxy cell as direct when a host sets directProxy, and import that literal back as an explicit direct connection. An empty Proxy cell still inherits. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> * fix: keep CSV proxy export from embedding the global default Grouped hosts ran through applyGroupDefaults and picked up the ambient global proxy, while ungrouped hosts exported an empty inheriting cell. Both paths now opt out of that default so inheritance stays inheritance. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> * fix: follow global default proxy changes in peer session windows Session windows disable settings IPC sync, which also skipped the storage listener and left the resolver singleton at its mount-time id. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> * refactor: clear a deleted global default proxy at the call site Drop the pass-through field on removeProxyProfileReferences. The profile manager already knows the active id and clears it directly. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> * test: share the global default proxy settings harness The peer-window case and the multi-instance cleanup case were mounting the same JSDOM fixture twice. Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com> --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: 陈大猫 <binaricat@users.noreply.github.com>
925 lines
30 KiB
TypeScript
925 lines
30 KiB
TypeScript
/**
|
|
* Cloud Sync Domain Types & Interfaces
|
|
*
|
|
* Zero-Knowledge Encrypted Multi-Cloud Sync System
|
|
* Supports: GitHub Gist, Google Drive, Microsoft OneDrive, WebDAV, S3 Compatible
|
|
*/
|
|
|
|
import type { ShrinkFinding } from './syncGuards';
|
|
import type {
|
|
ConvergentFieldConflict,
|
|
ConvergentSyncEnvelopeV2,
|
|
ConvergentSyncStateV2,
|
|
} from './convergentSync';
|
|
import {
|
|
BUILTIN_CLOUD_PROVIDERS,
|
|
isBuiltinCloudProvider,
|
|
providerConnectionStorageKey,
|
|
type BuiltinCloudProvider,
|
|
type CloudProviderId,
|
|
} from './cloudProviderIds';
|
|
|
|
export type {
|
|
ConvergentFieldConflict,
|
|
ConvergentSyncEnvelopeV2,
|
|
ConvergentSyncStateV2,
|
|
} from './convergentSync';
|
|
|
|
export {
|
|
BUILTIN_CLOUD_PROVIDERS,
|
|
isBuiltinCloudProvider,
|
|
providerConnectionStorageKey,
|
|
type BuiltinCloudProvider,
|
|
};
|
|
|
|
/** Built-in short IDs or namespaced plugin contribution IDs. */
|
|
export type CloudProvider = CloudProviderId;
|
|
|
|
// ============================================================================
|
|
// Security State Machine
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Global Security State Machine
|
|
* Controls access to sync operations based on master key status
|
|
*/
|
|
export type SecurityState =
|
|
| 'NO_KEY' // User has not set up a master key - block all sync
|
|
| 'LOCKED' // Master key exists but not in memory - show unlock screen
|
|
| 'UNLOCKED'; // Master key in memory - sync operations allowed
|
|
|
|
/**
|
|
* Sync Operation State Machine
|
|
* Tracks the current sync operation status
|
|
*/
|
|
export type SyncState =
|
|
| 'IDLE' // Waiting for sync trigger
|
|
| 'SYNCING' // Active sync operation in progress
|
|
| 'CONFLICT' // Version conflict detected - needs resolution
|
|
| 'BLOCKED' // Outgoing payload would delete too much — user must choose restore or force-push
|
|
| 'ERROR'; // Operation failed - needs attention
|
|
|
|
/**
|
|
* Conflict Resolution Strategy
|
|
*/
|
|
export type ConflictResolution =
|
|
| 'USE_REMOTE' // Download cloud data, overwrite local
|
|
| 'USE_LOCAL' // Upload local data, overwrite cloud
|
|
| 'AUTO_MERGED'; // Three-way merge was applied automatically
|
|
|
|
// ============================================================================
|
|
// Cloud Provider Types
|
|
// ============================================================================
|
|
|
|
export type WebDAVAuthType = 'basic' | 'digest' | 'token';
|
|
|
|
export interface WebDAVConfig {
|
|
endpoint: string;
|
|
authType: WebDAVAuthType;
|
|
username?: string;
|
|
password?: string;
|
|
token?: string;
|
|
allowInsecure?: boolean;
|
|
}
|
|
|
|
export interface S3Config {
|
|
endpoint: string;
|
|
region: string;
|
|
bucket: string;
|
|
accessKeyId: string;
|
|
secretAccessKey: string;
|
|
sessionToken?: string;
|
|
prefix?: string;
|
|
forcePathStyle?: boolean;
|
|
allowInsecure?: boolean;
|
|
}
|
|
|
|
/**
|
|
* Provider-specific connection status
|
|
*/
|
|
type ProviderConnectionStatus =
|
|
| 'disconnected'
|
|
| 'connecting'
|
|
| 'connected'
|
|
| 'syncing'
|
|
| 'error';
|
|
|
|
/**
|
|
* OAuth token storage structure
|
|
*/
|
|
export interface OAuthTokens {
|
|
accessToken: string;
|
|
refreshToken?: string;
|
|
expiresAt?: number; // Unix timestamp
|
|
tokenType: string;
|
|
scope?: string;
|
|
}
|
|
|
|
/**
|
|
* Marker prefixed onto OneDrive refresh errors when Microsoft reports the
|
|
* refresh token can no longer be used (expired / revoked / consent withdrawn).
|
|
* Only an error's `message` survives the Electron IPC boundary, so the marker is
|
|
* the stable signal that the OneDrive session must be re-authorized. It is added
|
|
* in the bridge (electron/bridges/onedriveAuthBridge.cjs) and detected/cleaned
|
|
* here so the same logic is shared by infrastructure and UI layers.
|
|
*/
|
|
export const ONEDRIVE_REAUTH_REQUIRED_MARKER = 'ONEDRIVE_REAUTH_REQUIRED';
|
|
|
|
/**
|
|
* True when an error indicates the OneDrive refresh token is dead and the user
|
|
* must reconnect. Robust to the error being re-wrapped (e.g. `new
|
|
* Error(String(err))`) as it bubbles through the provider-agnostic pipeline.
|
|
*/
|
|
export const isOneDriveReauthRequiredMessage = (message: string): boolean =>
|
|
message.includes(ONEDRIVE_REAUTH_REQUIRED_MARKER);
|
|
|
|
/**
|
|
* Produce a clean, user-facing message from a (possibly multiply-wrapped) error
|
|
* string by dropping everything up to and including the internal reauth marker,
|
|
* e.g. "Error: OneDriveReauthRequiredError: ONEDRIVE_REAUTH_REQUIRED: OneDrive
|
|
* session expired..." -> "OneDrive session expired...". Returns the original
|
|
* string unchanged when the marker is absent.
|
|
*/
|
|
export const cleanOneDriveErrorMessage = (message: string): string => {
|
|
const token = `${ONEDRIVE_REAUTH_REQUIRED_MARKER}:`;
|
|
const markerIndex = message.lastIndexOf(token);
|
|
if (markerIndex === -1) return message;
|
|
return message.slice(markerIndex + token.length).trim();
|
|
};
|
|
|
|
/**
|
|
* Provider account information
|
|
*/
|
|
export interface ProviderAccount {
|
|
id: string;
|
|
email?: string;
|
|
name?: string;
|
|
avatarUrl?: string;
|
|
}
|
|
|
|
/**
|
|
* Cloud provider connection state
|
|
*/
|
|
/**
|
|
* Opaque host-owned sync credential reference (SecretRef / CredentialRef shape).
|
|
* Never stores plaintext secrets — only the reference the plugin connect path needs.
|
|
* Secret leases are one-shot and must not be persisted for reconnect.
|
|
*/
|
|
export interface PluginSyncCredentialRef {
|
|
kind: 'secret' | 'credential';
|
|
id: string;
|
|
key?: string;
|
|
}
|
|
|
|
/** Reasonable upper bounds for durable opaque ref strings persisted at rest. */
|
|
const MAX_PLUGIN_SYNC_CREDENTIAL_ID_CHARS = 512;
|
|
const MAX_PLUGIN_SYNC_CREDENTIAL_KEY_CHARS = 256;
|
|
|
|
/**
|
|
* Normalize a value into a durable PluginSyncCredentialRef for reconnect
|
|
* persistence. Rejects arrays, leases, and oversized / malformed shapes.
|
|
*/
|
|
export function normalizeDurablePluginSyncCredentialRef(
|
|
value: unknown,
|
|
): PluginSyncCredentialRef | undefined {
|
|
if (value == null || typeof value !== 'object' || Array.isArray(value)) {
|
|
return undefined;
|
|
}
|
|
const record = value as Record<string, unknown>;
|
|
const kind = record.kind;
|
|
const id = record.id;
|
|
if (kind !== 'secret' && kind !== 'credential') return undefined;
|
|
if (typeof id !== 'string' || id.length < 1 || id.length > MAX_PLUGIN_SYNC_CREDENTIAL_ID_CHARS) {
|
|
return undefined;
|
|
}
|
|
if (!Object.prototype.hasOwnProperty.call(record, 'key') || record.key === undefined) {
|
|
return { kind, id };
|
|
}
|
|
const key = record.key;
|
|
if (typeof key !== 'string' || key.length < 1 || key.length > MAX_PLUGIN_SYNC_CREDENTIAL_KEY_CHARS) {
|
|
return undefined;
|
|
}
|
|
return { kind, id, key };
|
|
}
|
|
|
|
export interface ProviderConnection {
|
|
provider: CloudProvider;
|
|
status: ProviderConnectionStatus;
|
|
account?: ProviderAccount;
|
|
tokens?: OAuthTokens;
|
|
config?: WebDAVConfig | S3Config;
|
|
/** Plugin sync providers: persisted SyncConnectPayload.credential for reconnect. */
|
|
credential?: PluginSyncCredentialRef;
|
|
lastSync?: number; // Unix timestamp
|
|
lastSyncVersion?: number;
|
|
resourceId?: string; // gistId / fileId / itemId
|
|
error?: string;
|
|
}
|
|
|
|
/**
|
|
* Whether a connection still has usable credentials/config to retry.
|
|
* Plugin configs may be valid falsy JSON scalars (`false`, `0`, `""`) or even
|
|
* JSON `null` when a schema uses `type: "null"`. Presence is property
|
|
* existence for `config`; do not use truthiness (`||` / `Boolean`).
|
|
*/
|
|
export const hasProviderConnectionData = (
|
|
connection: Pick<ProviderConnection, 'tokens' | 'config' | 'credential'>,
|
|
): boolean =>
|
|
connection.tokens != null
|
|
|| Object.prototype.hasOwnProperty.call(connection, 'config')
|
|
|| connection.credential != null;
|
|
|
|
export const isProviderReadyForSync = (
|
|
connection: Pick<ProviderConnection, 'status' | 'tokens' | 'config'>,
|
|
): boolean =>
|
|
connection.status === 'connected'
|
|
|| connection.status === 'syncing'
|
|
|| (connection.status === 'error' && hasProviderConnectionData(connection));
|
|
|
|
// ============================================================================
|
|
// Encrypted Sync File Schema
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Sync file metadata (stored in plaintext for version control)
|
|
*/
|
|
export interface SyncFileMeta {
|
|
version: number; // Incremental version number
|
|
updatedAt: number; // Unix timestamp (ms)
|
|
deviceId: string; // UUID identifying the device
|
|
deviceName?: string; // Human-readable device name
|
|
appVersion: string; // App version that created this sync
|
|
iv: string; // AES-GCM initialization vector (Base64)
|
|
salt: string; // KDF salt for key derivation (Base64)
|
|
algorithm: 'AES-256-GCM'; // Encryption algorithm identifier
|
|
kdf: 'PBKDF2' | 'Argon2id'; // Key derivation function
|
|
kdfIterations?: number; // PBKDF2 iterations (if applicable)
|
|
/** Present only for convergent-sync payloads. Unknown future versions fail closed. */
|
|
syncSchemaVersion?: 2;
|
|
}
|
|
|
|
/**
|
|
* Complete synced file structure
|
|
* The payload contains all encrypted user data
|
|
*/
|
|
export interface SyncedFile {
|
|
meta: SyncFileMeta;
|
|
payload: string; // Base64 encrypted ciphertext
|
|
}
|
|
|
|
/**
|
|
* Decrypted payload structure - contains all syncable data
|
|
*/
|
|
export interface SyncPayload {
|
|
// Core vault data
|
|
hosts: import('./models').Host[];
|
|
keys: import('./models').SSHKey[];
|
|
identities?: import('./models').Identity[];
|
|
proxyProfiles?: import('./models').ProxyProfile[];
|
|
snippets: import('./models').Snippet[];
|
|
customGroups: string[];
|
|
snippetPackages?: string[];
|
|
notes?: import('./models').VaultNote[];
|
|
noteGroups?: string[];
|
|
|
|
monitorPanels?: import('./monitorPanels').MonitorPanel[];
|
|
|
|
// Group configs (connection defaults per host group)
|
|
groupConfigs?: import('./models').GroupConfig[];
|
|
|
|
// Port forwarding rules
|
|
portForwardingRules?: import('./models').PortForwardingRule[];
|
|
|
|
/**
|
|
* AI chat sessions (optional).
|
|
*
|
|
* Opt-in: only present when the user enabled `cloudSync.aiSessions`.
|
|
* Messages are merged append-only (never dropped), and attachment payloads
|
|
* are stripped — only their metadata travels.
|
|
*/
|
|
aiSessions?: import('../infrastructure/ai/types').AISession[];
|
|
browserBookmarks?: import('./browserBookmark').BrowserBookmark[];
|
|
|
|
// Known hosts
|
|
knownHosts?: import('./models').KnownHost[];
|
|
|
|
// Settings
|
|
settings?: {
|
|
// Theme & Appearance
|
|
theme?: 'light' | 'dark' | 'system';
|
|
lightUiThemeId?: string;
|
|
darkUiThemeId?: string;
|
|
accentMode?: 'theme' | 'custom';
|
|
customAccent?: string;
|
|
uiFontFamilyId?: string;
|
|
uiLanguage?: string;
|
|
customCSS?: string;
|
|
noteFontFamily?: string;
|
|
noteFontSize?: number;
|
|
noteCodeFontSize?: number;
|
|
// Terminal
|
|
terminalTheme?: string;
|
|
followAppTerminalTheme?: boolean;
|
|
terminalThemeDark?: string;
|
|
terminalThemeLight?: string;
|
|
terminalFontFamily?: string;
|
|
terminalFontSize?: number;
|
|
terminalSettings?: Record<string, unknown>;
|
|
/**
|
|
* Present once the sender has run the autoCloseOnExit default migration.
|
|
* Legacy payloads omit it; a materialized `true` in those payloads is the
|
|
* old default, not an explicit opt-in.
|
|
*/
|
|
autoCloseOnExitDefaultMigrated?: boolean;
|
|
terminalSidePanelAutoOpen?: boolean;
|
|
terminalSidePanelAutoOpenTab?: import('./terminalSidePanelAutoOpen').TerminalSidePanelAutoOpenTab;
|
|
localShellSidePanelAutoOpen?: boolean;
|
|
localShellSidePanelAutoOpenTab?: import('./terminalSidePanelAutoOpen').TerminalSidePanelAutoOpenTab;
|
|
customTerminalThemes?: Array<{ id: string; name: string; colors: Record<string, string> }>;
|
|
// Keyboard
|
|
customKeyBindings?: Record<string, { mac?: string; pc?: string }>;
|
|
// Editor
|
|
editorWordWrap?: boolean;
|
|
// SFTP
|
|
sftpDoubleClickBehavior?: 'open' | 'transfer';
|
|
sftpAutoSync?: boolean;
|
|
sftpShowHiddenFiles?: boolean;
|
|
sftpUseCompressedUpload?: boolean;
|
|
sftpSkipUnchanged?: boolean;
|
|
sftpAutoOpenSidebar?: boolean;
|
|
sftpFollowTerminalCwd?: boolean;
|
|
sftpDefaultViewMode?: 'list' | 'tree';
|
|
sftpGlobalBookmarks?: import('./models').SftpBookmark[];
|
|
// Vault: show recently connected hosts
|
|
showRecentHosts?: boolean;
|
|
// Vault: host click activates immediately, or select-then-click-again
|
|
hostClickBehavior?: 'connect' | 'select';
|
|
// Vault: root list shows only ungrouped hosts
|
|
showOnlyUngroupedHostsInRoot?: boolean;
|
|
// Top tabs: show standalone SFTP view tab
|
|
showSftpTab?: boolean;
|
|
// Shortcuts: Cmd/Ctrl+[1...9] and Ctrl+Tab skip pinned Vault/SFTP tabs
|
|
shellOnlyTabNumberShortcuts?: boolean;
|
|
// Shortcuts: show 1...9 badges on tabs matching number switch shortcuts
|
|
showTabNumberBadges?: boolean;
|
|
// Shortcuts: disable terminal font zoom shortcuts
|
|
disableTerminalFontZoom?: boolean;
|
|
// Terminal/editor tabs: show left host list sidebar
|
|
showHostTreeSidebar?: boolean;
|
|
// Workspace focus indicator style
|
|
workspaceFocusStyle?: 'dim' | 'border';
|
|
/**
|
|
* Saved proxy profile for hosts that do not set a proxy and do not inherit
|
|
* one from a group. An empty string is an explicit direct default.
|
|
*/
|
|
defaultProxyProfileId?: string;
|
|
// AI configuration
|
|
ai?: {
|
|
providers?: Array<Record<string, unknown>>;
|
|
activeProviderId?: string;
|
|
activeModelId?: string;
|
|
globalPermissionMode?: 'observer' | 'confirm' | 'auto';
|
|
toolIntegrationMode?: 'mcp' | 'skills';
|
|
hostPermissions?: Array<Record<string, unknown>>;
|
|
// externalAgents intentionally omitted: command/args/env are device-local
|
|
// (binary paths, OS-specific values) and don't survive cross-device sync.
|
|
defaultAgentId?: string;
|
|
commandBlocklist?: string[];
|
|
commandTimeout?: number;
|
|
responseIdleTimeout?: number;
|
|
maxIterations?: number;
|
|
agentModelMap?: Record<string, string>;
|
|
agentProviderMap?: Record<string, string>;
|
|
agentThinkingMap?: Record<string, string>;
|
|
webSearchConfig?: Record<string, unknown> | null;
|
|
quickMessages?: Array<Record<string, unknown>>;
|
|
showTerminalSelectionAction?: boolean;
|
|
};
|
|
};
|
|
|
|
/**
|
|
* Encrypted-sidecar envelope for plugin user data that must survive missing
|
|
* plugins (sync:true settings, account/CRDT baselines). Secrets never appear here.
|
|
*/
|
|
pluginSidecars?: import('./pluginSyncSidecar').PluginSyncSidecarBundle;
|
|
|
|
// Sync metadata
|
|
syncedAt: number; // When this payload was created
|
|
|
|
// Reliability metadata used to make sync decisions auditable across devices.
|
|
syncMeta?: SyncReliabilityMeta;
|
|
|
|
/** Encrypted convergent-sync metadata. The adjacent fields remain a complete v1 snapshot. */
|
|
convergentSync?: ConvergentSyncEnvelopeV2;
|
|
}
|
|
|
|
/**
|
|
* Pre-migration snapshots stored autoCloseOnExit: true as the default and do
|
|
* not carry `autoCloseOnExitDefaultMigrated`. Rewrite that legacy true to
|
|
* false. A payload that records the migration keeps an explicit true.
|
|
*/
|
|
export function reconcileInboundAutoCloseOnExit(
|
|
autoCloseOnExit: unknown,
|
|
payloadRecordsMigratedChoice: unknown,
|
|
): unknown {
|
|
if (autoCloseOnExit === true && payloadRecordsMigratedChoice !== true) return false;
|
|
return autoCloseOnExit;
|
|
}
|
|
|
|
/** True when this side both migrated and explicitly enabled auto-close. */
|
|
export function payloadOptsIntoAutoClose(
|
|
settings: SyncPayload['settings'] | undefined,
|
|
): boolean {
|
|
return settings?.autoCloseOnExitDefaultMigrated === true
|
|
&& settings.terminalSettings?.autoCloseOnExit === true;
|
|
}
|
|
|
|
/**
|
|
* Strip device-local connection telemetry from hosts before any sync
|
|
* comparison or upload (#2629). `lastConnectedAt` updates on every successful
|
|
* SSH connect and must not dirty auto-sync hashes, three-way merges, or
|
|
* inflate cloud versions. Legacy stored bases / remote payloads still carry
|
|
* the field, so all three merge sides are normalized with this helper.
|
|
*/
|
|
export function sanitizeHostsForSync(
|
|
hosts: import('./models').Host[] | undefined,
|
|
): import('./models').Host[] | undefined {
|
|
if (!hosts) return hosts;
|
|
return hosts.map((host) => ({ ...host, lastConnectedAt: undefined }));
|
|
}
|
|
|
|
/** Copy a payload with device-local host telemetry stripped for compare/convert. */
|
|
export function withHostsSanitizedForSync(payload: SyncPayload): SyncPayload {
|
|
return {
|
|
...payload,
|
|
hosts: sanitizeHostsForSync(payload.hosts) ?? payload.hosts,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Re-attach this device's Recently Connected timestamps when a cloud payload
|
|
* omits `lastConnectedAt`. Incoming timestamps (local backups, legacy cloud
|
|
* snapshots) still win when present.
|
|
*/
|
|
export function retainLocalHostLastConnectedAt(
|
|
incoming: import('./models').Host[] | undefined,
|
|
local: import('./models').Host[] | undefined,
|
|
): import('./models').Host[] | undefined {
|
|
if (!incoming) return incoming;
|
|
if (!local?.length) return incoming;
|
|
const localById = new Map(local.map((host) => [host.id, host.lastConnectedAt]));
|
|
return incoming.map((host) => {
|
|
if (host.lastConnectedAt != null) return host;
|
|
const localTs = localById.get(host.id);
|
|
if (localTs == null) return host;
|
|
return { ...host, lastConnectedAt: localTs };
|
|
});
|
|
}
|
|
|
|
export const SYNC_PAYLOAD_ENTITY_KEYS = [
|
|
'hosts',
|
|
'keys',
|
|
'identities',
|
|
'proxyProfiles',
|
|
'snippets',
|
|
'customGroups',
|
|
'snippetPackages',
|
|
'notes',
|
|
'noteGroups',
|
|
'portForwardingRules',
|
|
'browserBookmarks',
|
|
'knownHosts',
|
|
'groupConfigs',
|
|
'monitorPanels',
|
|
] as const;
|
|
|
|
export const CLOUD_SYNC_PAYLOAD_ENTITY_KEYS = [
|
|
'hosts',
|
|
'keys',
|
|
'identities',
|
|
'proxyProfiles',
|
|
'snippets',
|
|
'customGroups',
|
|
'snippetPackages',
|
|
'notes',
|
|
'noteGroups',
|
|
'portForwardingRules',
|
|
'browserBookmarks',
|
|
'groupConfigs',
|
|
'monitorPanels',
|
|
'aiSessions',
|
|
] as const;
|
|
|
|
export type SyncPayloadEntityKey = typeof SYNC_PAYLOAD_ENTITY_KEYS[number];
|
|
export type CloudSyncPayloadEntityKey = typeof CLOUD_SYNC_PAYLOAD_ENTITY_KEYS[number];
|
|
export type SyncChangeEntityKey = CloudSyncPayloadEntityKey | 'settings';
|
|
|
|
export interface SyncEntityChangeCounts {
|
|
added: { local: number; remote: number };
|
|
modified: { local: number; remote: number };
|
|
deleted: { local: number; remote: number };
|
|
}
|
|
|
|
export interface SyncConflictDetail {
|
|
entityType: SyncChangeEntityKey;
|
|
id?: string;
|
|
kind:
|
|
| 'both-added'
|
|
| 'both-modified'
|
|
| 'local-deleted-remote-modified'
|
|
| 'remote-deleted-local-modified';
|
|
}
|
|
|
|
export interface SyncChangeSummary {
|
|
hasLocalChanges: boolean;
|
|
hasRemoteChanges: boolean;
|
|
hasConflicts: boolean;
|
|
byEntity: Partial<Record<SyncChangeEntityKey, SyncEntityChangeCounts>>;
|
|
conflicts: SyncConflictDetail[];
|
|
}
|
|
|
|
export interface SyncDeletionRecord {
|
|
entityType: CloudSyncPayloadEntityKey;
|
|
id: string;
|
|
deletedAt: number;
|
|
deviceId?: string;
|
|
}
|
|
|
|
export interface SyncReliabilityMeta {
|
|
schemaVersion: 1;
|
|
generatedAt: number;
|
|
deviceId?: string;
|
|
baseSyncedAt?: number;
|
|
localChanged: boolean;
|
|
deletions: SyncDeletionRecord[];
|
|
changeSummary: SyncChangeSummary;
|
|
}
|
|
|
|
export interface SyncSnapshotEntry {
|
|
id: string;
|
|
timestamp: number;
|
|
provider?: CloudProvider;
|
|
payload: SyncPayload;
|
|
}
|
|
|
|
export interface ConvergentProviderMigrationStatus {
|
|
provider: CloudProvider;
|
|
status: 'ready' | 'empty' | 'unavailable' | 'blocked';
|
|
schemaVersion: 1 | 2 | 'future' | 'invalid';
|
|
entityCount: number;
|
|
hasTrustedBaseline: boolean;
|
|
message?: string;
|
|
}
|
|
|
|
export interface ConvergentMigrationPreview {
|
|
schemaVersion: 2;
|
|
canInitialize: boolean;
|
|
entityCounts: Partial<Record<CloudSyncPayloadEntityKey, number>>;
|
|
settingsLeafCount: number;
|
|
conflictCount: number;
|
|
conflicts: ConvergentFieldConflict[];
|
|
shrinkFindings: Array<{ provider: CloudProvider; finding: Extract<ShrinkFinding, { suspicious: true }> }>;
|
|
providers: ConvergentProviderMigrationStatus[];
|
|
oldClientCompatibility: 'materialized-v1-snapshot';
|
|
blockedReasons: string[];
|
|
}
|
|
|
|
export interface ConvergentReplicaRecordV2 {
|
|
schemaVersion: 2;
|
|
state: ConvergentSyncStateV2;
|
|
updatedAt: number;
|
|
}
|
|
|
|
export interface ConvergentProviderBaselineV2 {
|
|
schemaVersion: 2;
|
|
provider: CloudProvider;
|
|
remoteVersion: number;
|
|
remoteUpdatedAt: number;
|
|
remoteDeviceId: string;
|
|
materializedPayload: SyncPayload;
|
|
state: ConvergentSyncStateV2;
|
|
}
|
|
|
|
export function hasSyncPayloadEntityData(
|
|
payload: SyncPayload,
|
|
keys: readonly (SyncPayloadEntityKey | CloudSyncPayloadEntityKey)[] = SYNC_PAYLOAD_ENTITY_KEYS,
|
|
): boolean {
|
|
return keys.some((key) => {
|
|
const value = payload[key];
|
|
return Array.isArray(value) && value.length > 0;
|
|
});
|
|
}
|
|
|
|
// ============================================================================
|
|
// Encryption Types
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Encryption result
|
|
*/
|
|
export interface EncryptionResult {
|
|
ciphertext: Uint8Array;
|
|
iv: Uint8Array;
|
|
salt: Uint8Array;
|
|
algorithm: 'AES-256-GCM';
|
|
kdf: 'PBKDF2' | 'Argon2id';
|
|
kdfIterations?: number;
|
|
}
|
|
|
|
/**
|
|
* Decryption input
|
|
*/
|
|
export interface DecryptionInput {
|
|
ciphertext: Uint8Array;
|
|
iv: Uint8Array;
|
|
salt: Uint8Array;
|
|
kdf: 'PBKDF2' | 'Argon2id';
|
|
kdfIterations?: number;
|
|
}
|
|
|
|
// ============================================================================
|
|
// Master Key Types
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Master key configuration stored in safeStorage
|
|
*/
|
|
export interface MasterKeyConfig {
|
|
// Verification hash to confirm correct password
|
|
verificationHash: string; // Base64 of hash(derived_key)
|
|
salt: string; // Base64 KDF salt
|
|
kdf: 'PBKDF2' | 'Argon2id';
|
|
kdfIterations?: number;
|
|
createdAt: number;
|
|
}
|
|
|
|
/**
|
|
* Unlocked master key state (in memory only)
|
|
*/
|
|
export interface UnlockedMasterKey {
|
|
derivedKey: CryptoKey; // AES-256-GCM key
|
|
salt: Uint8Array;
|
|
unlockedAt: number;
|
|
}
|
|
|
|
// ============================================================================
|
|
// Sync Manager Types
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Sync operation result
|
|
*/
|
|
export interface SyncResult {
|
|
success: boolean;
|
|
provider: CloudProvider;
|
|
action: 'upload' | 'download' | 'merge' | 'none';
|
|
version?: number;
|
|
error?: string;
|
|
conflictDetected?: boolean;
|
|
/** Present when sync produced or selected a payload that caller should apply locally */
|
|
mergedPayload?: import('./sync').SyncPayload;
|
|
/** True when convergent sync already applied mergedPayload and committed its replica atomically. */
|
|
mergedPayloadApplied?: boolean;
|
|
/** Present with a downloaded payload so callers can commit the remote anchor after local apply succeeds. */
|
|
remoteFile?: SyncedFile;
|
|
/** True when a shrink-detection guard blocked the upload */
|
|
shrinkBlocked?: boolean;
|
|
/** The finding that triggered the shrink block or force-push */
|
|
finding?: ShrinkFinding;
|
|
/** Field-level conflicts retained by convergent sync v2. */
|
|
convergentConflicts?: ConvergentFieldConflict[];
|
|
/** Number of retained v2 conflicts; duplicated for lightweight status views. */
|
|
convergentConflictCount?: number;
|
|
}
|
|
|
|
export interface RemoteSyncPayload {
|
|
provider: CloudProvider;
|
|
payload: SyncPayload;
|
|
remoteFile: SyncedFile;
|
|
}
|
|
|
|
/**
|
|
* Conflict information for UI
|
|
*/
|
|
export interface ConflictInfo {
|
|
provider: CloudProvider;
|
|
localVersion: number;
|
|
localUpdatedAt: number;
|
|
localDeviceName?: string;
|
|
remoteVersion: number;
|
|
remoteUpdatedAt: number;
|
|
remoteDeviceName?: string;
|
|
changeSummary?: SyncChangeSummary;
|
|
}
|
|
|
|
/**
|
|
* Sync history record entry
|
|
*/
|
|
export interface SyncHistoryEntry {
|
|
id: string;
|
|
timestamp: number;
|
|
provider: CloudProvider;
|
|
action: 'upload' | 'download' | 'merge' | 'conflict_resolved';
|
|
success: boolean;
|
|
localVersion: number;
|
|
remoteVersion?: number;
|
|
deviceName?: string;
|
|
error?: string;
|
|
}
|
|
|
|
// ============================================================================
|
|
// OAuth Flow Types
|
|
// ============================================================================
|
|
|
|
/**
|
|
* GitHub Device Flow response
|
|
*/
|
|
export interface GitHubDeviceCodeResponse {
|
|
device_code: string;
|
|
user_code: string;
|
|
verification_uri: string;
|
|
expires_in: number;
|
|
interval: number;
|
|
}
|
|
|
|
/**
|
|
* OAuth PKCE challenge
|
|
*/
|
|
export interface PKCEChallenge {
|
|
codeVerifier: string;
|
|
codeChallenge: string;
|
|
state: string;
|
|
}
|
|
|
|
// ============================================================================
|
|
// Event Types
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Sync event for UI updates
|
|
*/
|
|
export type SyncEvent =
|
|
| { type: 'SYNC_STARTED'; provider: CloudProvider }
|
|
| { type: 'SYNC_PROGRESS'; provider: CloudProvider; progress: number; message: string }
|
|
| { type: 'SYNC_COMPLETED'; provider: CloudProvider; result: SyncResult }
|
|
| { type: 'SYNC_ERROR'; provider: CloudProvider; error: string }
|
|
| { type: 'CONFLICT_DETECTED'; conflict: ConflictInfo }
|
|
| { type: 'SYNC_BLOCKED_SHRINK'; provider: CloudProvider; finding: ShrinkFinding }
|
|
| { type: 'SYNC_FORCED'; provider: CloudProvider; finding: ShrinkFinding }
|
|
| { type: 'CONFLICT_RESOLVED'; resolution: ConflictResolution }
|
|
| { type: 'AUTH_REQUIRED'; provider: CloudProvider }
|
|
| { type: 'AUTH_COMPLETED'; provider: CloudProvider; account: ProviderAccount }
|
|
| { type: 'SECURITY_STATE_CHANGED'; state: SecurityState }
|
|
| { type: 'SYNC_BLOCKED_CLEARED' }
|
|
| {
|
|
type: 'PROVIDERS_DIVERGED';
|
|
summaries: Array<{
|
|
provider: CloudProvider;
|
|
hosts: number;
|
|
keys: number;
|
|
snippets: number;
|
|
}>;
|
|
};
|
|
|
|
// ============================================================================
|
|
// Storage Keys
|
|
// ============================================================================
|
|
|
|
export const SYNC_STORAGE_KEYS = {
|
|
MASTER_KEY_CONFIG: 'netcatty_master_key_config_v1',
|
|
DEVICE_ID: 'netcatty_device_id_v1',
|
|
DEVICE_NAME: 'netcatty_device_name_v1',
|
|
SYNC_CONFIG: 'netcatty_sync_config_v2',
|
|
/** Auto-sync prefs (autoSync / interval / syncStrategy); kept separate from version stamps. */
|
|
SYNC_PREFERENCES: 'netcatty_sync_preferences_v1',
|
|
PROVIDER_GITHUB: 'netcatty_provider_github_v1',
|
|
PROVIDER_GOOGLE: 'netcatty_provider_google_v1',
|
|
PROVIDER_ONEDRIVE: 'netcatty_provider_onedrive_v1',
|
|
PROVIDER_WEBDAV: 'netcatty_provider_webdav_v1',
|
|
PROVIDER_S3: 'netcatty_provider_s3_v1',
|
|
PROVIDER_SMB: 'netcatty_provider_smb_v1',
|
|
/** Registry of connected namespaced plugin sync provider IDs. */
|
|
PLUGIN_CLOUD_PROVIDERS: 'netcatty_plugin_cloud_providers_v1',
|
|
/** Contribution-available plugin sync provider IDs (live catalog membership). */
|
|
AVAILABLE_PLUGIN_SYNC_PROVIDERS: 'netcatty_available_plugin_sync_providers_v1',
|
|
/** Last successful sidecar collect (upload fallback when host is offline). */
|
|
PLUGIN_SIDECARS_LAST_KNOWN: 'netcatty_plugin_sidecars_last_known_v1',
|
|
/** Remote sidecar apply queued while the plugin host was unavailable. */
|
|
PLUGIN_SIDECARS_PENDING_REMOTE: 'netcatty_plugin_sidecars_pending_remote_v1',
|
|
LOCAL_SYNC_META: 'netcatty_local_sync_meta_v1',
|
|
SYNC_BASE_PAYLOAD: 'netcatty_sync_base_payload_v1',
|
|
CONVERGENT_REPLICA: 'netcatty_convergent_sync_replica_v2',
|
|
CONVERGENT_PROVIDER_BASELINE: 'netcatty_convergent_sync_provider_baseline_v2',
|
|
} as const;
|
|
|
|
// ============================================================================
|
|
// Constants
|
|
// ============================================================================
|
|
|
|
const readBuildEnv = (key: string): string | undefined => {
|
|
const env = (import.meta as { env?: Record<string, string | undefined> }).env;
|
|
const value = env?.[key];
|
|
return value && value.trim().length ? value : undefined;
|
|
};
|
|
|
|
export const SYNC_CONSTANTS = {
|
|
// Encryption
|
|
AES_KEY_LENGTH: 256,
|
|
GCM_IV_LENGTH: 12, // bytes
|
|
GCM_TAG_LENGTH: 128, // bits
|
|
SALT_LENGTH: 32, // bytes
|
|
|
|
// PBKDF2
|
|
PBKDF2_ITERATIONS: 600000, // OWASP recommended minimum
|
|
PBKDF2_HASH: 'SHA-256',
|
|
|
|
// Sync
|
|
SYNC_FILE_NAME: 'netcatty-vault.json',
|
|
GIST_DESCRIPTION: 'Netcatty Encrypted Vault (DO NOT EDIT MANUALLY)',
|
|
|
|
// Auto-sync
|
|
DEFAULT_AUTO_SYNC_INTERVAL: 5, // minutes
|
|
MIN_SYNC_INTERVAL: 1, // minutes
|
|
MAX_SYNC_INTERVAL: 60, // minutes
|
|
|
|
// OAuth
|
|
GITHUB_CLIENT_ID: readBuildEnv('VITE_SYNC_GITHUB_CLIENT_ID') || '', // Public client ID for Device Flow
|
|
GOOGLE_CLIENT_ID: readBuildEnv('VITE_SYNC_GOOGLE_CLIENT_ID') || '',
|
|
GOOGLE_CLIENT_SECRET: readBuildEnv('VITE_SYNC_GOOGLE_CLIENT_SECRET') || '',
|
|
ONEDRIVE_CLIENT_ID: readBuildEnv('VITE_SYNC_ONEDRIVE_CLIENT_ID') || '',
|
|
|
|
// API endpoints
|
|
GITHUB_DEVICE_CODE_URL: 'https://github.com/login/device/code',
|
|
GITHUB_ACCESS_TOKEN_URL: 'https://github.com/login/oauth/access_token',
|
|
GITHUB_API_BASE: 'https://api.github.com',
|
|
|
|
GOOGLE_AUTH_URL: 'https://accounts.google.com/o/oauth2/v2/auth',
|
|
GOOGLE_TOKEN_URL: 'https://oauth2.googleapis.com/token',
|
|
GOOGLE_DRIVE_API: 'https://www.googleapis.com/drive/v3',
|
|
|
|
ONEDRIVE_AUTH_URL: 'https://login.microsoftonline.com/consumers/oauth2/v2.0/authorize',
|
|
ONEDRIVE_TOKEN_URL: 'https://login.microsoftonline.com/consumers/oauth2/v2.0/token',
|
|
ONEDRIVE_GRAPH_API: 'https://graph.microsoft.com/v1.0',
|
|
} as const;
|
|
|
|
// ============================================================================
|
|
// Helper Functions
|
|
// ============================================================================
|
|
|
|
/**
|
|
* Generate a unique device ID
|
|
*/
|
|
export const generateDeviceId = (): string => {
|
|
return crypto.randomUUID();
|
|
};
|
|
|
|
/**
|
|
* Get default device name based on OS
|
|
*/
|
|
export const getDefaultDeviceName = (): string => {
|
|
const platform = navigator.platform || 'Unknown';
|
|
const hostname = 'Netcatty';
|
|
return `${hostname} (${platform})`;
|
|
};
|
|
|
|
/**
|
|
* Format a sync timestamp as `yyyymmdd hhmm` (e.g. `20250628 1430`).
|
|
*/
|
|
export const formatSyncDateTime = (timestamp: number): string => {
|
|
const date = new Date(timestamp);
|
|
const year = date.getFullYear();
|
|
const month = String(date.getMonth() + 1).padStart(2, '0');
|
|
const day = String(date.getDate()).padStart(2, '0');
|
|
const hours = String(date.getHours()).padStart(2, '0');
|
|
const minutes = String(date.getMinutes()).padStart(2, '0');
|
|
return `${year}${month}${day} ${hours}${minutes}`;
|
|
};
|
|
|
|
/**
|
|
* Format last sync time for display
|
|
*/
|
|
export const formatLastSync = (timestamp?: number): string => {
|
|
if (!timestamp) return 'Never synced';
|
|
|
|
const now = Date.now();
|
|
const diff = now - timestamp;
|
|
|
|
if (diff < 60000) return 'Just now';
|
|
if (diff < 3600000) return `${Math.floor(diff / 60000)} min ago`;
|
|
|
|
return formatSyncDateTime(timestamp);
|
|
};
|
|
|
|
/**
|
|
* Get status dot color class
|
|
*/
|
|
export const getSyncDotColor = (status: ProviderConnectionStatus): string => {
|
|
switch (status) {
|
|
case 'connected': return 'bg-green-500';
|
|
case 'syncing': return 'bg-blue-500';
|
|
case 'error': return 'bg-red-500';
|
|
case 'connecting': return 'bg-yellow-500';
|
|
default: return 'bg-muted-foreground';
|
|
}
|
|
};
|