@deveye/types 0.21.0 → 0.21.1

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.0",
3
+ "version": "0.21.1",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -224,7 +224,9 @@ export const agentPolicySchema = z.object({
224
224
  /** Deployments (`composeDeploy`), on top of `docker`. */
225
225
  dockerDeploy: z.boolean().default(true),
226
226
  /** CloudSync shares: the server reading and writing a synced folder. */
227
- sync: z.boolean().default(true)
227
+ sync: z.boolean().default(true),
228
+ /** Tunnels (`tunnel.open`): a module reaching a service of the machine, such as a database. */
229
+ tunnel: z.boolean().default(true)
228
230
  });
229
231
  export type AgentPolicy = z.infer<typeof agentPolicySchema>;
230
232
 
@@ -258,7 +260,8 @@ export const agentInfoSchema = z.object({
258
260
  destroy: true,
259
261
  docker: true,
260
262
  dockerDeploy: true,
261
- sync: true
263
+ sync: true,
264
+ tunnel: true
262
265
  }),
263
266
  /** The agent reaches this server over plain http/ws (opted in locally): everything, shell included, travels in clear. */
264
267
  insecureTransport: z.boolean().default(false)
@@ -95,8 +95,15 @@ export type UserSecurity = z.infer<typeof userSecuritySchema>;
95
95
  * - `feedbackHintDismissed` : la bulle qui présente le bouton de signalement a
96
96
  * été vue. Posée par sa croix comme par l'ouverture du formulaire, elle ne
97
97
  * se retire jamais : la bulle se montre une fois dans la vie d'un compte.
98
+ * - `homeLayoutHintDismissed`, `aboutHintDismissed` : de même pour les bulles
99
+ * du bouton d'organisation de l'accueil et du numéro de version.
98
100
  */
99
- export const userSettingFlagSchema = z.enum(['hideLiveCursors', 'feedbackHintDismissed']);
101
+ export const userSettingFlagSchema = z.enum([
102
+ 'hideLiveCursors',
103
+ 'feedbackHintDismissed',
104
+ 'homeLayoutHintDismissed',
105
+ 'aboutHintDismissed'
106
+ ]);
100
107
  export type UserSettingFlag = z.infer<typeof userSettingFlagSchema>;
101
108
 
102
109
  export const userSchema = z.object({
package/src/http/auth.ts CHANGED
@@ -32,6 +32,8 @@ export const sessionBundleSchema = z.object({
32
32
  feedbackEnabled: z.boolean(),
33
33
  /** The marketing site (`SITE_URL`), for the legal links. `null`: none. */
34
34
  siteUrl: z.string().url().nullable(),
35
+ /** Where this server's source code is offered (`SOURCE_URL`), as the AGPL requires. `null`: none. */
36
+ sourceUrl: z.string().url().nullable(),
35
37
  /**
36
38
  * Admin only: the process booted with `MAINTENANCE=1` and no admin has
37
39
  * closed the reminder. Shown once the site maintenance is lifted. Read at
package/src/index.ts CHANGED
@@ -80,6 +80,15 @@ export {
80
80
  AGENT_TERM_OPEN,
81
81
  AGENT_TERM_OUTPUT,
82
82
  AGENT_TERM_RESIZE,
83
+ AGENT_TUNNEL_CLOSE,
84
+ AGENT_TUNNEL_CLOSED,
85
+ AGENT_TUNNEL_CREDIT,
86
+ AGENT_TUNNEL_DATA,
87
+ AGENT_TUNNEL_OPEN,
88
+ AGENT_TUNNEL_OPENED,
89
+ AGENT_TUNNEL_PIECE_BYTES,
90
+ AGENT_TUNNEL_PROBE,
91
+ AGENT_TUNNEL_WRITE,
83
92
  AGENT_UPDATE,
84
93
  AGENT_UPDATED,
85
94
  agentClientMessageSchema,
@@ -147,6 +156,13 @@ export {
147
156
  agentTermOpenPayloadSchema,
148
157
  agentTermOutputPayloadSchema,
149
158
  agentTermResizePayloadSchema,
159
+ agentTunnelClosedPayloadSchema,
160
+ agentTunnelClosePayloadSchema,
161
+ agentTunnelCreditPayloadSchema,
162
+ agentTunnelDataPayloadSchema,
163
+ agentTunnelOpenedPayloadSchema,
164
+ agentTunnelOpenPayloadSchema,
165
+ agentTunnelWritePayloadSchema,
150
166
  agentUpdatedMessagePayloadSchema,
151
167
  agentUpdatePayloadSchema,
152
168
  CLOUD_SYNC_CHUNK_EVENT,
@@ -251,6 +267,13 @@ export type {
251
267
  AgentTermInputPayload,
252
268
  AgentTermOpenPayload,
253
269
  AgentTermResizePayload,
270
+ AgentTunnelClosedPayload,
271
+ AgentTunnelClosePayload,
272
+ AgentTunnelCreditPayload,
273
+ AgentTunnelDataPayload,
274
+ AgentTunnelOpenedPayload,
275
+ AgentTunnelOpenPayload,
276
+ AgentTunnelWritePayload,
254
277
  AgentUpdatePayload,
255
278
  CloudSyncChunkPush,
256
279
  CloudSyncProgressPush,
@@ -345,6 +345,37 @@ export const agentFilesArchiveEndPayloadSchema = z.object({
345
345
  });
346
346
  export type AgentFilesArchiveEndPayload = z.infer<typeof agentFilesArchiveEndPayloadSchema>;
347
347
 
348
+ const tunnelId = z.string().min(1).max(64);
349
+ /** Raw bytes per `tunnel.data` or `tunnel.write` frame, before base64. */
350
+ export const AGENT_TUNNEL_PIECE_BYTES = 64 * 1024;
351
+ const tunnelData = z.string().max(90_000);
352
+
353
+ /** Agent → server: the TCP connection of a `tunnel.open` is up; bytes may flow. */
354
+ export const AGENT_TUNNEL_OPENED = 'tunnel.opened' as const;
355
+ export const agentTunnelOpenedPayloadSchema = z.object({ deviceId: z.uuid(), tunnelId });
356
+ export type AgentTunnelOpenedPayload = z.infer<typeof agentTunnelOpenedPayloadSchema>;
357
+
358
+ /** Agent → server: bytes read from the target (`data` base64). Spends one credit. */
359
+ export const AGENT_TUNNEL_DATA = 'tunnel.data' as const;
360
+ export const agentTunnelDataPayloadSchema = z.object({
361
+ deviceId: z.uuid(),
362
+ tunnelId,
363
+ data: tunnelData
364
+ });
365
+ export type AgentTunnelDataPayload = z.infer<typeof agentTunnelDataPayloadSchema>;
366
+
367
+ /**
368
+ * Agent → server: the tunnel ended, the last frame for its id. `error` when it
369
+ * did not end with the target closing (refused, unreachable, cut).
370
+ */
371
+ export const AGENT_TUNNEL_CLOSED = 'tunnel.closed' as const;
372
+ export const agentTunnelClosedPayloadSchema = z.object({
373
+ deviceId: z.uuid(),
374
+ tunnelId,
375
+ error: z.string().max(500).optional()
376
+ });
377
+ export type AgentTunnelClosedPayload = z.infer<typeof agentTunnelClosedPayloadSchema>;
378
+
348
379
  const syncOpId = z.string().min(1).max(64);
349
380
  const syncRelPath = z.string().min(1).max(SYNC_REL_PATH_MAX);
350
381
 
@@ -605,6 +636,18 @@ export const agentClientMessageSchema = z.discriminatedUnion('command', [
605
636
  command: z.literal(AGENT_FILES_ARCHIVE_END),
606
637
  payload: agentFilesArchiveEndPayloadSchema
607
638
  }),
639
+ z.object({
640
+ command: z.literal(AGENT_TUNNEL_OPENED),
641
+ payload: agentTunnelOpenedPayloadSchema
642
+ }),
643
+ z.object({
644
+ command: z.literal(AGENT_TUNNEL_DATA),
645
+ payload: agentTunnelDataPayloadSchema
646
+ }),
647
+ z.object({
648
+ command: z.literal(AGENT_TUNNEL_CLOSED),
649
+ payload: agentTunnelClosedPayloadSchema
650
+ }),
608
651
  z.object({
609
652
  command: z.literal(AGENT_SYNC_CHANGED),
610
653
  payload: agentSyncChangedPayloadSchema
@@ -871,6 +914,43 @@ export const AGENT_FILES_ARCHIVE_CANCEL = 'files.archiveCancel' as const;
871
914
  export const agentFilesArchiveCancelPayloadSchema = z.object({ opId: filesOpId });
872
915
  export type AgentFilesArchiveCancelPayload = z.infer<typeof agentFilesArchiveCancelPayloadSchema>;
873
916
 
917
+ /**
918
+ * Open a TCP connection from the machine to `host:port` and relay it: what
919
+ * lets a module reach a service only the machine can see (a database on its
920
+ * loopback). The agent answers `tunnel.opened` then `tunnel.data` frames under
921
+ * credits, or `tunnel.closed` with the reason. It only reaches its own
922
+ * loopback, plus the hosts its operator lists in `tunnel_targets`.
923
+ */
924
+ export const AGENT_TUNNEL_OPEN = 'tunnel.open' as const;
925
+ /** What an agent that knows `tunnel.open` declares in `report.agent.probes`. */
926
+ export const AGENT_TUNNEL_PROBE = 'tunnel';
927
+ export const agentTunnelOpenPayloadSchema = z.object({
928
+ tunnelId,
929
+ host: z.string().min(1).max(255),
930
+ port: z.number().int().min(1).max(65535),
931
+ /** Credits granted up front. */
932
+ window: z.number().int().min(1).max(64)
933
+ });
934
+ export type AgentTunnelOpenPayload = z.infer<typeof agentTunnelOpenPayloadSchema>;
935
+
936
+ /** Bytes for the target (`data` base64). */
937
+ export const AGENT_TUNNEL_WRITE = 'tunnel.write' as const;
938
+ export const agentTunnelWritePayloadSchema = z.object({ tunnelId, data: tunnelData });
939
+ export type AgentTunnelWritePayload = z.infer<typeof agentTunnelWritePayloadSchema>;
940
+
941
+ /** More credits for a tunnel, as the server consumes its `tunnel.data` frames. */
942
+ export const AGENT_TUNNEL_CREDIT = 'tunnel.credit' as const;
943
+ export const agentTunnelCreditPayloadSchema = z.object({
944
+ tunnelId,
945
+ credits: z.number().int().min(1).max(64)
946
+ });
947
+ export type AgentTunnelCreditPayload = z.infer<typeof agentTunnelCreditPayloadSchema>;
948
+
949
+ /** Close a tunnel. The agent sends nothing back: the server has already forgotten it. */
950
+ export const AGENT_TUNNEL_CLOSE = 'tunnel.close' as const;
951
+ export const agentTunnelClosePayloadSchema = z.object({ tunnelId });
952
+ export type AgentTunnelClosePayload = z.infer<typeof agentTunnelClosePayloadSchema>;
953
+
874
954
  /**
875
955
  * CloudSync, serveur → agent. Le serveur orchestre tout : l'agent reçoit ses
876
956
  * assignations (`sync.config`), scanne sur ordre, transfère sur ordre.
@@ -1217,6 +1297,22 @@ export const agentServerMessageSchema = z.discriminatedUnion('command', [
1217
1297
  command: z.literal(AGENT_FILES_ARCHIVE_CANCEL),
1218
1298
  payload: agentFilesArchiveCancelPayloadSchema
1219
1299
  }),
1300
+ z.object({
1301
+ command: z.literal(AGENT_TUNNEL_OPEN),
1302
+ payload: agentTunnelOpenPayloadSchema
1303
+ }),
1304
+ z.object({
1305
+ command: z.literal(AGENT_TUNNEL_WRITE),
1306
+ payload: agentTunnelWritePayloadSchema
1307
+ }),
1308
+ z.object({
1309
+ command: z.literal(AGENT_TUNNEL_CREDIT),
1310
+ payload: agentTunnelCreditPayloadSchema
1311
+ }),
1312
+ z.object({
1313
+ command: z.literal(AGENT_TUNNEL_CLOSE),
1314
+ payload: agentTunnelClosePayloadSchema
1315
+ }),
1220
1316
  z.object({
1221
1317
  command: z.literal(AGENT_SYNC_CONFIG),
1222
1318
  payload: agentSyncConfigPayloadSchema
@@ -1266,8 +1362,8 @@ export type OrderSignature = z.infer<typeof orderSignatureSchema>;
1266
1362
  /**
1267
1363
  * The orders the server signs (`ORDER_SIGNING_KEY`) and the agent refuses
1268
1364
  * unsigned: what runs code, writes or deletes files, changes the agent's
1269
- * privileges or its life, or drives its containers. Mirror of
1270
- * `SIGNED_COMMANDS` in `agent/src/protocol.rs`.
1365
+ * privileges or its life, drives its containers, or reaches into its network.
1366
+ * Mirror of `SIGNED_COMMANDS` in `agent/src/protocol.rs`.
1271
1367
  */
1272
1368
  export const SIGNED_AGENT_COMMANDS: ReadonlySet<string> = new Set([
1273
1369
  AGENT_TERM_OPEN,
@@ -1278,7 +1374,8 @@ export const SIGNED_AGENT_COMMANDS: ReadonlySet<string> = new Set([
1278
1374
  AGENT_DESTROY,
1279
1375
  AGENT_PKG_UPGRADE,
1280
1376
  AGENT_LIFECYCLE,
1281
- AGENT_DOCKER_ACTION
1377
+ AGENT_DOCKER_ACTION,
1378
+ AGENT_TUNNEL_OPEN
1282
1379
  ]);
1283
1380
 
1284
1381
  /**
package/src/sdk/server.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { Duplex } from 'node:stream';
1
2
  import type { FeatureAccountExport } from './accountExport';
2
3
  import type { ItemTree, ItemTreeRows } from './copy';
3
4
  import type { z, ZodType } from 'zod';
@@ -655,6 +656,19 @@ export interface AgentsFacade {
655
656
  request: AgentFolderArchiveRequest,
656
657
  options?: { signal?: AbortSignal }
657
658
  ): AgentFolderArchive;
659
+ /**
660
+ * A TCP connection opened BY THE DEVICE to `host:port` and relayed by its
661
+ * agent: a service only the machine can reach (a database on its
662
+ * loopback) becomes a stream here, read at the consumer's pace. The agent
663
+ * only reaches its own loopback, plus the hosts its operator lists in
664
+ * `tunnel_targets`, and refuses everything under `allow_tunnel = false`.
665
+ * Rejects with the reason (offline, refused, unreachable, an agent that
666
+ * predates the order: check `report.agent.probes` for
667
+ * `AGENT_TUNNEL_PROBE` first to say so plainly). Once open, the stream is
668
+ * destroyed with an error when the device goes offline; ending or
669
+ * destroying it closes the connection on the machine.
670
+ */
671
+ openTcp(deviceId: string, target: { host: string; port: number }): Promise<Duplex>;
658
672
  /**
659
673
  * Bytes queued on the agent's socket, not yet on the wire. A sender that
660
674
  * streams towards an agent must watch it: the socket accepts everything,
@@ -242,6 +242,7 @@ interface TestAgents {
242
242
  dockerInventory?: DevEyeFacade['agents']['dockerInventory'];
243
243
  /** By device id. A device without an entry answers nothing: its stream throws. */
244
244
  archives?: Readonly<Record<string, TestFolderArchive | Error>>;
245
+ openTcp?: DevEyeFacade['agents']['openTcp'];
245
246
  /** The plan `metricIntervals` applies. Default paid. */
246
247
  paid?: boolean;
247
248
  }
@@ -334,6 +335,12 @@ function recordingAgents(recorded: RecordedCalls, docker: TestAgents = {}): DevE
334
335
  recorded.agentRequests.push({ method: 'archiveFolder', deviceId });
335
336
  recorded.archiveRequests.push({ deviceId, ...request });
336
337
  return replayedArchive(docker.archives?.[deviceId]);
338
+ },
339
+ openTcp(deviceId, target) {
340
+ recorded.agentRequests.push({ method: 'openTcp', deviceId });
341
+ return docker.openTcp
342
+ ? docker.openTcp(deviceId, target)
343
+ : Promise.reject(new Error('La machine n’est pas connectée.'));
337
344
  }
338
345
  };
339
346
  }
@@ -481,6 +488,8 @@ export interface TestContextOverrides<Repo> {
481
488
  dockerInventory?: DevEyeFacade['agents']['dockerInventory'];
482
489
  /** What `deveye.agents.archiveFolder` streams, by device id. Default none: the stream throws. */
483
490
  archives?: Readonly<Record<string, TestFolderArchive | Error>>;
491
+ /** What `deveye.agents.openTcp` resolves. Default a rejection, as for an offline device. */
492
+ openTcp?: DevEyeFacade['agents']['openTcp'];
484
493
  /** Instants `deveye.telemetry.snapshot` answers (matched within a second). Default none. */
485
494
  snapshots?: readonly SdkTelemetrySnapshot[];
486
495
  /** Override facade members entirely when the defaults are not enough. */
@@ -758,6 +767,8 @@ export interface TestServiceOverrides<Repo> {
758
767
  dockerInventory?: DevEyeFacade['agents']['dockerInventory'];
759
768
  /** What `deps.agents.archiveFolder` streams, by device id. Default none: the stream throws. */
760
769
  archives?: Readonly<Record<string, TestFolderArchive | Error>>;
770
+ /** What `deps.agents.openTcp` resolves. Default a rejection, as for an offline device. */
771
+ openTcp?: DevEyeFacade['agents']['openTcp'];
761
772
  /** What `deps.access` answers. Default: every member holds every right. */
762
773
  access?: Partial<FeatureServiceDeps['access']>;
763
774
  /** The accounts `deps.accounts` knows, and `deps.accountMail` writes to. Default none. */