@deveye/types 0.21.9 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.21.9",
3
+ "version": "0.22.0",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -81,7 +81,7 @@ export const deviceLogFilterSchema = z.object({
81
81
  search: z.string().max(500).optional(),
82
82
  /** Treat `search` as a regular expression. */
83
83
  regex: z.boolean().optional(),
84
- /** Severity floor (inclusive): only lines with level >= this. */
84
+ /** Severity floor (inclusive): only lines with level >= this. A line whose level is unknown counts as `info`. */
85
85
  levelMin: deviceLogLevelSchema.optional(),
86
86
  /** journald unit / service filter (e.g. `nginx.service`). Ignored by other kinds. */
87
87
  unit: z.string().max(256).optional(),
@@ -15,6 +15,14 @@ export const SYNC_STORAGE_PATH_MAX = 1024;
15
15
  export const SYNC_CHUNK_MAX = 1_400_000;
16
16
  /** Nombre max d'entrées d'index par frame `sync.index`. */
17
17
  export const SYNC_INDEX_BATCH_MAX = 500;
18
+ /**
19
+ * Blocks of an encrypted partial a resumed push can build on (1 MiB each). The
20
+ * server keeps no more: their nonces must fit in one `sync.push` frame, and
21
+ * past 32 GiB a broken upload restarts from there rather than from zero.
22
+ */
23
+ export const SYNC_RESUME_MAX_BLOCKS = 32_768;
24
+ /** Base64 length of {@link SYNC_RESUME_MAX_BLOCKS} 12-byte nonces. */
25
+ export const SYNC_RESUME_NONCES_MAX = Math.ceil((SYNC_RESUME_MAX_BLOCKS * 12) / 3) * 4;
18
26
  /**
19
27
  * Séparateur des champs d'une ligne d'empreinte d'index (voir
20
28
  * `src/cloudSync/fingerprint.ts` côté serveur et `sync::fingerprint` côté
@@ -58,12 +66,27 @@ export type SyncSessionState = z.infer<typeof syncSessionStateSchema>;
58
66
  */
59
67
  export const syncEntryKindSchema = z.enum(['file', 'dir']);
60
68
  export type SyncEntryKind = z.infer<typeof syncEntryKindSchema>;
69
+ /**
70
+ * Why the agent could not index a path. The server treats that path, and
71
+ * anything under it, as UNKNOWN: no deletion, no upload, no download; it
72
+ * enters neither the baseline nor the fingerprint.
73
+ */
74
+ export const syncSkipReasonSchema = z.enum([
75
+ 'unreadable',
76
+ 'unportable',
77
+ 'symlink',
78
+ 'special',
79
+ 'nonUtf8'
80
+ ]);
81
+ export type SyncSkipReason = z.infer<typeof syncSkipReasonSchema>;
61
82
  /** Volumétrie d'un partage (index + versions ; tailles logiques en clair). */
62
83
  export const cloudSyncShareStatsSchema = z.object({
63
84
  fileCount: z.number().int().nonnegative(),
64
85
  liveBytes: z.number().int().nonnegative(),
65
86
  versionCount: z.number().int().nonnegative(),
66
- versionBytes: z.number().int().nonnegative()
87
+ versionBytes: z.number().int().nonnegative(),
88
+ /** Journal errors not yet resolved: what still waits for the user. */
89
+ openProblems: z.number().int().nonnegative()
67
90
  });
68
91
  export type CloudSyncShareStats = z.infer<typeof cloudSyncShareStatsSchema>;
69
92
  /** Sens du transfert en cours (du point de vue de l'appareil). */
@@ -88,13 +111,13 @@ export const cloudSyncProgressSchema = z.object({
88
111
  error: z.string().max(500).nullable()
89
112
  });
90
113
  export type CloudSyncProgress = z.infer<typeof cloudSyncProgressSchema>;
91
- /** État agrégé d'un partage — pilote le héros « Synchronisé » de l'UI. */
114
+ /** État agrégé d'un partage : pilote le héros « Synchronisé » de l'UI. */
92
115
  export const cloudSyncShareStateSchema = z.object({
93
116
  shareId: z.number().int().positive(),
94
117
  state: z.enum(['synced', 'syncing', 'paused', 'offline', 'error']),
95
118
  /** Précision facultative (ex. nom de l'appareil hors ligne ou en erreur). */
96
119
  detail: z.string().max(200).nullable(),
97
- /** Volumétrie fraîche — l'en-tête de l'UI se met à jour sans re-fetch. */
120
+ /** Volumétrie fraîche : l'en-tête de l'UI se met à jour sans re-fetch. */
98
121
  stats: cloudSyncShareStatsSchema
99
122
  });
100
123
  export type CloudSyncShareState = z.infer<typeof cloudSyncShareStateSchema>;
package/src/index.ts CHANGED
@@ -65,6 +65,7 @@ export {
65
65
  AGENT_SYNC_APPLY_DIR,
66
66
  AGENT_SYNC_APPLY_START,
67
67
  AGENT_SYNC_APPLY_LOCAL,
68
+ AGENT_SYNC_BUSY,
68
69
  AGENT_SYNC_CHANGED,
69
70
  AGENT_SYNC_CHUNK,
70
71
  AGENT_SYNC_CONFIG,
@@ -72,6 +73,7 @@ export {
72
73
  AGENT_SYNC_MOVE,
73
74
  AGENT_SYNC_INDEX,
74
75
  AGENT_SYNC_OP_RESULT,
76
+ AGENT_SYNC_DEVICE_KEY,
75
77
  AGENT_SYNC_PUSH,
76
78
  AGENT_SYNC_PUSH_ACK,
77
79
  AGENT_SYNC_SCAN,
@@ -142,6 +144,7 @@ export {
142
144
  agentSyncApplyDirPayloadSchema,
143
145
  agentSyncApplyStartPayloadSchema,
144
146
  agentSyncApplyLocalPayloadSchema,
147
+ agentSyncBusyPayloadSchema,
145
148
  agentSyncChangedPayloadSchema,
146
149
  agentSyncChunkPayloadSchema,
147
150
  agentSyncConfigPayloadSchema,
@@ -149,6 +152,8 @@ export {
149
152
  agentSyncMovePayloadSchema,
150
153
  agentSyncIndexPayloadSchema,
151
154
  agentSyncOpResultPayloadSchema,
155
+ agentSyncDeviceKeyPayloadSchema,
156
+ syncDevicePublicKeySchema,
152
157
  agentSyncPushPayloadSchema,
153
158
  agentSyncPushAckPayloadSchema,
154
159
  agentSyncScanPayloadSchema,
@@ -224,6 +229,8 @@ export {
224
229
  orderSignatureSchema,
225
230
  SIGNED_AGENT_COMMANDS,
226
231
  syncIndexEntrySchema,
232
+ syncIndexLineSchema,
233
+ syncIndexSkippedEntrySchema,
227
234
  syncShareAssignmentSchema
228
235
  } from './protocol/agent';
229
236
  export type {
@@ -257,6 +264,7 @@ export type {
257
264
  AgentSyncApplyDirPayload,
258
265
  AgentSyncApplyStartPayload,
259
266
  AgentSyncApplyLocalPayload,
267
+ AgentSyncBusyPayload,
260
268
  AgentSyncChangedPayload,
261
269
  AgentSyncChunkPayload,
262
270
  AgentSyncConfigPayload,
@@ -264,6 +272,7 @@ export type {
264
272
  AgentSyncIndexPayload,
265
273
  AgentSyncMovePayload,
266
274
  AgentSyncOpResultPayload,
275
+ AgentSyncDeviceKeyPayload,
267
276
  AgentSyncPushPayload,
268
277
  AgentSyncPushAckPayload,
269
278
  AgentSyncScanPayload,
@@ -307,6 +316,8 @@ export type {
307
316
  PackageProgressPush,
308
317
  PackageStartedPush,
309
318
  SyncIndexEntry,
319
+ SyncIndexLine,
320
+ SyncIndexSkippedEntry,
310
321
  SyncShareAssignment
311
322
  } from './protocol/agent';
312
323
 
@@ -416,10 +427,13 @@ export {
416
427
  SYNC_CHUNK_MAX,
417
428
  SYNC_FINGERPRINT_SEP,
418
429
  SYNC_INDEX_BATCH_MAX,
430
+ SYNC_RESUME_MAX_BLOCKS,
431
+ SYNC_RESUME_NONCES_MAX,
419
432
  SYNC_REL_PATH_MAX,
420
433
  SYNC_STORAGE_PATH_MAX,
421
434
  syncDirectionSchema,
422
435
  syncEntryKindSchema,
436
+ syncSkipReasonSchema,
423
437
  syncIndexFingerprintSchema,
424
438
  syncScanModeSchema,
425
439
  syncSessionStateSchema,
@@ -439,6 +453,7 @@ export type {
439
453
  CloudSyncShareStats,
440
454
  SyncDirection,
441
455
  SyncEntryKind,
456
+ SyncSkipReason,
442
457
  SyncScanMode,
443
458
  SyncSessionState,
444
459
  SyncShareStatus
@@ -4,10 +4,12 @@ import {
4
4
  cloudSyncShareStateSchema,
5
5
  sha256HexSchema,
6
6
  SYNC_CHUNK_MAX,
7
+ SYNC_RESUME_NONCES_MAX,
7
8
  SYNC_INDEX_BATCH_MAX,
8
9
  SYNC_REL_PATH_MAX,
9
10
  SYNC_STORAGE_PATH_MAX,
10
11
  syncEntryKindSchema,
12
+ syncSkipReasonSchema,
11
13
  syncIndexFingerprintSchema,
12
14
  syncScanModeSchema,
13
15
  syncShareStatusSchema
@@ -427,13 +429,28 @@ export const syncIndexEntrySchema = z.object({
427
429
  });
428
430
  export type SyncIndexEntry = z.infer<typeof syncIndexEntrySchema>;
429
431
 
432
+ /** A path the agent saw but could not index: the server treats it, and anything under it, as unknown. */
433
+ export const syncIndexSkippedEntrySchema = z.object({
434
+ relPath: syncRelPath,
435
+ kind: z.literal('skipped'),
436
+ reason: syncSkipReasonSchema
437
+ });
438
+ export type SyncIndexSkippedEntry = z.infer<typeof syncIndexSkippedEntrySchema>;
439
+
440
+ /** One line of a `sync.index` batch: an indexed entry, or a skipped path. */
441
+ export const syncIndexLineSchema = z.discriminatedUnion('kind', [
442
+ syncIndexEntrySchema,
443
+ syncIndexSkippedEntrySchema
444
+ ]);
445
+ export type SyncIndexLine = z.infer<typeof syncIndexLineSchema>;
446
+
430
447
  /** Un lot d'index du scan (réponse à `sync.scan`, dernier lot `done: true`). */
431
448
  export const AGENT_SYNC_INDEX = 'sync.index' as const;
432
449
  export const agentSyncIndexPayloadSchema = z.object({
433
450
  deviceId: z.uuid(),
434
451
  sessionId: syncOpId,
435
452
  shareId: z.number().int().positive(),
436
- entries: z.array(syncIndexEntrySchema).max(SYNC_INDEX_BATCH_MAX),
453
+ entries: z.array(syncIndexLineSchema).max(SYNC_INDEX_BATCH_MAX),
437
454
  done: z.boolean(),
438
455
  /**
439
456
  * L'agent a-t-il réellement parcouru le disque ? `false` répond à un
@@ -446,6 +463,12 @@ export const agentSyncIndexPayloadSchema = z.object({
446
463
  scanned: z.boolean().default(true),
447
464
  /** Empreinte de l'index détenu par l'agent, quand il sait la calculer. */
448
465
  fingerprint: syncIndexFingerprintSchema.nullable().default(null),
466
+ /**
467
+ * The hashes are keyed (end-to-end encrypted share), not plain SHA-256. An
468
+ * agent that predates encrypted shares never sets it: the server refuses
469
+ * its index for such a share instead of storing readable content.
470
+ */
471
+ encrypted: z.boolean().default(false),
449
472
  /** Posé sur le lot final quand le scan a échoué (la session est abandonnée). */
450
473
  error: z.string().max(500).optional()
451
474
  });
@@ -472,7 +495,13 @@ export const agentSyncChunkPayloadSchema = z.object({
472
495
  * honours the push's `window`: the server then answers each data frame with
473
496
  * `sync.pushAck`. Absent (an older agent), nothing is acknowledged.
474
497
  */
475
- seq: z.number().int().nonnegative().optional()
498
+ seq: z.number().int().nonnegative().optional(),
499
+ /**
500
+ * Set with `error` on an encrypted push: the blocks the server kept from an
501
+ * earlier attempt do not encrypt the file as it is now. The server drops
502
+ * that partial; the next attempt starts over.
503
+ */
504
+ stalePartial: z.boolean().optional()
476
505
  });
477
506
  export type AgentSyncChunkPayload = z.infer<typeof agentSyncChunkPayloadSchema>;
478
507
 
@@ -485,6 +514,19 @@ export const agentSyncAckPayloadSchema = z.object({
485
514
  });
486
515
  export type AgentSyncAckPayload = z.infer<typeof agentSyncAckPayloadSchema>;
487
516
 
517
+ /**
518
+ * Keep-alive for a long local step of `opId` (re-reading a partial download,
519
+ * hashing a large file during a scan or before a local copy/move). The server
520
+ * only re-arms its silence timeout. Sent about every 15 s. For a scan, `opId`
521
+ * is the scan's session id.
522
+ */
523
+ export const AGENT_SYNC_BUSY = 'sync.busy' as const;
524
+ export const agentSyncBusyPayloadSchema = z.object({
525
+ deviceId: z.uuid(),
526
+ opId: syncOpId
527
+ });
528
+ export type AgentSyncBusyPayload = z.infer<typeof agentSyncBusyPayloadSchema>;
529
+
488
530
  /**
489
531
  * Issue d'une op locale : install atomique (`apply`), création de dossier vide
490
532
  * (`applyDir`), copie locale d'un contenu déjà présent (`applyLocal`), amorce
@@ -503,6 +545,26 @@ export const agentSyncOpResultPayloadSchema = z.object({
503
545
  });
504
546
  export type AgentSyncOpResultPayload = z.infer<typeof agentSyncOpResultPayloadSchema>;
505
547
 
548
+ /** Base64 of a raw X25519 public key (32 bytes). */
549
+ export const syncDevicePublicKeySchema = z
550
+ .string()
551
+ .length(44)
552
+ .regex(/^[A-Za-z0-9+/]{43}=$/);
553
+
554
+ /**
555
+ * The device's X25519 public key, sent after every `sync.config`. The key of
556
+ * an encrypted share reaches the device sealed for it (see
557
+ * `syncShareAssignmentSchema.encryption`); the private half never leaves the
558
+ * machine. A different key than the last one means the machine lost its
559
+ * private key: whatever was sealed for the old one is unreadable.
560
+ */
561
+ export const AGENT_SYNC_DEVICE_KEY = 'sync.deviceKey' as const;
562
+ export const agentSyncDeviceKeyPayloadSchema = z.object({
563
+ deviceId: z.uuid(),
564
+ publicKey: syncDevicePublicKeySchema
565
+ });
566
+ export type AgentSyncDeviceKeyPayload = z.infer<typeof agentSyncDeviceKeyPayloadSchema>;
567
+
506
568
  export const agentReportMessagePayloadSchema = z.object({
507
569
  deviceId: z.uuid(),
508
570
  report: deviceReportSchema
@@ -685,9 +747,17 @@ export const agentClientMessageSchema = z.discriminatedUnion('command', [
685
747
  command: z.literal(AGENT_SYNC_ACK),
686
748
  payload: agentSyncAckPayloadSchema
687
749
  }),
750
+ z.object({
751
+ command: z.literal(AGENT_SYNC_BUSY),
752
+ payload: agentSyncBusyPayloadSchema
753
+ }),
688
754
  z.object({
689
755
  command: z.literal(AGENT_SYNC_OP_RESULT),
690
756
  payload: agentSyncOpResultPayloadSchema
757
+ }),
758
+ z.object({
759
+ command: z.literal(AGENT_SYNC_DEVICE_KEY),
760
+ payload: agentSyncDeviceKeyPayloadSchema
691
761
  })
692
762
  ]);
693
763
 
@@ -992,7 +1062,18 @@ export const syncShareAssignmentSchema = z.object({
992
1062
  */
993
1063
  rateUpBps: z.number().int().positive().nullable().default(null),
994
1064
  /** Rétention de `.deveye-trash/`, en jours. */
995
- trashKeepDays: z.number().int().positive().max(3650).default(30)
1065
+ trashKeepDays: z.number().int().positive().max(3650).default(30),
1066
+ /**
1067
+ * Set on an end-to-end encrypted share: the agent hashes with a key,
1068
+ * encrypts what it uploads and decrypts what it installs. `wrappedKey` is
1069
+ * the share secret sealed for this device's public key (base64), `null`
1070
+ * while nobody has given it to this device: the agent then refuses every
1071
+ * operation of the share and says why.
1072
+ */
1073
+ encryption: z
1074
+ .object({ wrappedKey: z.string().max(256).nullable() })
1075
+ .nullable()
1076
+ .default(null)
996
1077
  });
997
1078
  export type SyncShareAssignment = z.infer<typeof syncShareAssignmentSchema>;
998
1079
 
@@ -1036,7 +1117,27 @@ export const agentSyncPushPayloadSchema = z.object({
1036
1117
  * window. The server acks a frame once written, and paces its acks to cap
1037
1118
  * the upload rate. Absent (an older server), the agent streams freely.
1038
1119
  */
1039
- window: z.number().int().positive().max(64).optional()
1120
+ window: z.number().int().positive().max(64).optional(),
1121
+ /**
1122
+ * The hash the scan announced. An encrypted push binds its blocks to it,
1123
+ * so the server always sends it on an encrypted share.
1124
+ */
1125
+ hash: sha256HexSchema.optional(),
1126
+ /**
1127
+ * Encrypted share, `startOffset > 0`: what the server kept of an earlier
1128
+ * attempt. `header` is the blob's 17-byte header and `nonces` the 12-byte
1129
+ * nonce of each kept block in order (both base64), `tags` the hex SHA-256
1130
+ * of their 16-byte tags laid end to end. The agent re-encrypts its own
1131
+ * prefix with those nonces and compares before sending anything: content
1132
+ * changed since then is refused (`stalePartial`).
1133
+ */
1134
+ resume: z
1135
+ .object({
1136
+ header: z.string().max(32),
1137
+ nonces: z.string().max(SYNC_RESUME_NONCES_MAX),
1138
+ tags: sha256HexSchema
1139
+ })
1140
+ .optional()
1040
1141
  });
1041
1142
  export type AgentSyncPushPayload = z.infer<typeof agentSyncPushPayloadSchema>;
1042
1143
 
package/src/sdk/server.ts CHANGED
@@ -21,9 +21,11 @@ import type {
21
21
  AgentSyncApplyDirPayload,
22
22
  AgentSyncApplyLocalPayload,
23
23
  AgentSyncApplyStartPayload,
24
+ AgentSyncBusyPayload,
24
25
  AgentSyncChangedPayload,
25
26
  AgentSyncChunkPayload,
26
27
  AgentSyncConfigPayload,
28
+ AgentSyncDeviceKeyPayload,
27
29
  AgentSyncDeletePayload,
28
30
  AgentSyncIndexPayload,
29
31
  AgentSyncMovePayload,
@@ -762,7 +764,11 @@ export interface FeatureAgentHooks {
762
764
  onSyncIndex?(deviceId: string, payload: AgentSyncIndexPayload): void;
763
765
  onSyncChunk?(deviceId: string, payload: AgentSyncChunkPayload): void;
764
766
  onSyncAck?(deviceId: string, payload: AgentSyncAckPayload): void;
767
+ /** The agent is still working on an op locally; nothing to do but let the op wait longer. */
768
+ onSyncBusy?(deviceId: string, payload: AgentSyncBusyPayload): void;
765
769
  onSyncOpResult?(deviceId: string, payload: AgentSyncOpResultPayload): void;
770
+ /** The agent's X25519 public key, sent after every `sync.config` it receives. */
771
+ onSyncDeviceKey?(deviceId: string, payload: AgentSyncDeviceKeyPayload): void;
766
772
  }
767
773
 
768
774
  /**