@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 +1 -1
- package/src/domain/report.ts +5 -2
- package/src/domain/user.ts +8 -1
- package/src/http/auth.ts +2 -0
- package/src/index.ts +23 -0
- package/src/protocol/agent.ts +100 -3
- package/src/sdk/server.ts +14 -0
- package/src/sdk/testing.ts +11 -0
package/package.json
CHANGED
package/src/domain/report.ts
CHANGED
|
@@ -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)
|
package/src/domain/user.ts
CHANGED
|
@@ -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([
|
|
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,
|
package/src/protocol/agent.ts
CHANGED
|
@@ -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,
|
|
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,
|
package/src/sdk/testing.ts
CHANGED
|
@@ -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. */
|