@deveye/types 0.16.0 → 0.17.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.16.0",
3
+ "version": "0.17.0",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -25,6 +25,15 @@ export type DeviceStatus = z.infer<typeof deviceStatusSchema>;
25
25
  export const devicePlatformSchema = z.enum(['linux', 'macos', 'windows']);
26
26
  export type DevicePlatform = z.infer<typeof devicePlatformSchema>;
27
27
 
28
+ /**
29
+ * OS account a terminal session opens under. Restricted to safe username
30
+ * characters (no shell metacharacters), since it reaches a `su` on the device.
31
+ */
32
+ export const terminalUser = z
33
+ .string()
34
+ .regex(/^[A-Za-z0-9._-]+$/, 'Nom d’utilisateur invalide')
35
+ .max(32);
36
+
28
37
  /**
29
38
  * Client-facing device. Secrets (token hash, public key) are never exposed.
30
39
  * `online` is live presence, derived from an active agent connection.
@@ -70,10 +79,20 @@ export const deviceSchema = z.object({
70
79
  */
71
80
  retentionDays: z.number().int().positive().nullable().default(null),
72
81
  /**
73
- * Workspaces this device is shared with. A device is reachable from every
74
- * workspace listed here; its pairing workspace is always among them.
82
+ * Account new terminal sessions open under (`su -l`); null → the account the
83
+ * agent itself runs as.
84
+ */
85
+ terminalDefaultUser: terminalUser.nullable().default(null),
86
+ /**
87
+ * On shell exit: `true` closes the terminal straight away, `false` keeps it
88
+ * open with a "Relancer"/"Fermer" banner.
89
+ */
90
+ terminalCloseOnExit: z.boolean().default(true),
91
+ /**
92
+ * Seen from a workspace it was projected into, not the one it was paired
93
+ * in: read-only marks and a "shared" badge hang on it.
75
94
  */
76
- workspaceIds: z.array(z.number().int().positive()).default([]),
95
+ foreign: z.boolean().default(false),
77
96
  /**
78
97
  * Last self-destruct failure message: set when an agent failed to wipe itself
79
98
  * during deletion, so the UI can surface it and the deletion is aborted.
@@ -91,12 +110,12 @@ export interface DeviceRow {
91
110
  id: string;
92
111
  owner_id: number;
93
112
  /**
94
- * Espace d'appairage (celui du code de liaison) : porte l'unicité de
95
- * l'empreinte (`uniq_workspace_fingerprint`) et sert le ré-enrôlement par la
96
- * route publique. La frontière d'accès est `device_workspaces`, où il figure
97
- * toujours. `null` si cet espace a été supprimé : l'appareil survit.
113
+ * Le domicile de l'appareil, celui du code de liaison : il porte l'unicité
114
+ * de l'empreinte (`uniq_workspace_fingerprint`), sert le ré-enrôlement par
115
+ * la route publique, et c'est depuis lui que l'appareil se projette
116
+ * ailleurs (`item_shares`).
98
117
  */
99
- workspace_id: number | null;
118
+ workspace_id: number;
100
119
  name: string;
101
120
  fingerprint: string;
102
121
  platform: string;
@@ -119,21 +138,15 @@ export interface DeviceRow {
119
138
  process_capture: string | null;
120
139
  /** History retention in days (metrics, presence, processes); null → server default. */
121
140
  retention_days: number | null;
141
+ /** Account terminal sessions open under; null → the agent's own account. */
142
+ terminal_default_user: string | null;
143
+ /** 1 = closing the shell closes the terminal, 0 = it stays open on a banner. */
144
+ terminal_close_on_exit: number;
122
145
  /** Status to restore if a pending deletion is cancelled; null otherwise. */
123
146
  status_before_delete: string | null;
124
147
  /** Last self-destruct failure message (deletion aborted); null otherwise. */
125
148
  delete_error: string | null;
126
- }
127
-
128
- /**
129
- * Un appareil rangé dans un espace (`device_workspaces`). Le rang est porté par
130
- * la jonction et non par l'appareil : le même appareil est rangé
131
- * indépendamment dans chaque espace qui y a accès.
132
- */
133
- export interface DeviceWorkspaceRow {
134
- device_id: string;
135
- workspace_id: number;
136
- /** Rank in *that* workspace's list, entirely the user's (`device.reorder`). */
149
+ /** Rang chez lui ; celui des espaces qui ne font que le voir vit dans `item_shares`. */
137
150
  sort_order: number;
138
151
  }
139
152
 
@@ -58,7 +58,18 @@ export const deviceLogLineSchema = z.object({
58
58
  export type DeviceLogLine = z.infer<typeof deviceLogLineSchema>;
59
59
 
60
60
  export const DEVICE_LOG_PAGE_MAX = 1000;
61
- export const DEVICE_LOG_PAGE_DEFAULT = 200;
61
+ export const DEVICE_LOG_PAGE_DEFAULT = 500;
62
+ /** How far back a query may skip, so a runaway offset can't drive an unbounded read. */
63
+ export const DEVICE_LOG_OFFSET_MAX = 20_000;
64
+
65
+ /**
66
+ * Which end of the log `offset` counts from. A query returns the window
67
+ * `[offset, offset + limit)` walking back from the newest line, or forward from the
68
+ * oldest one — the latter is how the viewer jumps straight to a log's beginning
69
+ * without paging through everything in between.
70
+ */
71
+ export const deviceLogAnchorSchema = z.enum(['newest', 'oldest']);
72
+ export type DeviceLogAnchor = z.infer<typeof deviceLogAnchorSchema>;
62
73
 
63
74
  /**
64
75
  * Advanced search surface for a query. Every field is optional and combines as
@@ -75,7 +75,7 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
75
75
  notifies: false,
76
76
  hasItems: true,
77
77
  itemNoun: 'appareil',
78
- shareTier: 'never'
78
+ shareTier: 'open'
79
79
  },
80
80
  {
81
81
  id: 'sentinel',
@@ -247,6 +247,19 @@ export const FEATURE_REGISTRY: readonly (FeatureDescriptor & { id: WorkspaceFeat
247
247
  sources: {
248
248
  hint: 'Les clés d’API des fournisseurs, toutes facultatives : chaque sonde libre fonctionne déjà, une clé ne fait qu’enrichir la sienne.'
249
249
  }
250
+ },
251
+ {
252
+ id: 'cve',
253
+ label: 'Veille CVE',
254
+ description:
255
+ 'Lecture : le fil des vulnérabilités et la recherche. Écriture : épingler, et poser la clé du NVD.',
256
+ icon: 'bug',
257
+ notifies: false,
258
+ hasItems: false,
259
+ shareTier: 'never',
260
+ sources: {
261
+ hint: 'La clé d’API du NVD, facultative : sans elle le catalogue se remplit quand même, elle ne fait que relever le quota de requêtes.'
262
+ }
250
263
  }
251
264
  ];
252
265
 
@@ -267,7 +280,7 @@ export function registerExternalFeature(desc: FeatureDescriptor & { id: External
267
280
  EXTERNAL_BY_ID.set(desc.id, desc);
268
281
  }
269
282
 
270
- /** Le registre fusionné : les seize natives puis les modules, dans l'ordre d'enregistrement. */
283
+ /** Le registre fusionné : les natives puis les modules, dans l'ordre d'enregistrement. */
271
284
  export function allFeatureDescriptors(): readonly FeatureDescriptor[] {
272
285
  return EXTERNAL_BY_ID.size === 0
273
286
  ? FEATURE_REGISTRY
@@ -297,10 +310,9 @@ export function featureLabel(id: FeatureId): string {
297
310
  }
298
311
 
299
312
  /**
300
- * Les trois `never` : `devices` a déjà son partage inter-espaces, d'une autre
301
- * nature (`device_workspaces` est une adhésion, pas une projection) ;
302
- * `password` vit toujours à l'étage gardé ; `cloudsync` range ses contenus
303
- * dans un magasin de blobs chiffrés par la BMK, pas par une clé d'espace.
313
+ * Les deux `never` : `password` vit toujours à l'étage gardé ; `cloudsync`
314
+ * range ses contenus dans un magasin de blobs chiffrés par la BMK, pas par une
315
+ * clé d'espace.
304
316
  */
305
317
 
306
318
  /** Les fonctionnalités dont un élément **pourrait** voyager, côté chiffrement. */
@@ -16,9 +16,9 @@ import {
16
16
  */
17
17
 
18
18
  /**
19
- * Les seize tuiles de fonctionnalités natives. Une tuile porte l'id de sa
20
- * feature : la tuile Monitoring est celle de la feature `devices`, dont le
21
- * module fournit la carte et la vue.
19
+ * Les tuiles de fonctionnalités natives. Une tuile porte l'id de sa feature :
20
+ * la tuile Monitoring est celle de la feature `devices`, dont le module
21
+ * fournit la carte et la vue.
22
22
  */
23
23
  export const nativeHomeFeatureIdSchema = z.enum([
24
24
  'devices',
@@ -36,7 +36,8 @@ export const nativeHomeFeatureIdSchema = z.enum([
36
36
  'backup',
37
37
  'finance',
38
38
  'audience',
39
- 'osint'
39
+ 'osint',
40
+ 'cve'
40
41
  ]);
41
42
  export type NativeHomeFeatureId = z.infer<typeof nativeHomeFeatureIdSchema>;
42
43
 
@@ -55,10 +56,11 @@ export type HomeFeatureId = NativeHomeFeatureId | ExternalFeatureId;
55
56
  * - `weather` → current temperature of the primary city.
56
57
  * - `secrecy` → password-encryption lock state + re-validation countdown.
57
58
  * - `live` → qui d'autre est dans l'espace, et où (bulles cliquables).
59
+ * - `publicIp` → l'adresse publique par laquelle CE navigateur sort.
58
60
  * A module's widget is declared by its manifest (`topbarWidget`) and keyed by
59
61
  * its feature id (`homeTopbarWidgetIdSchema`).
60
62
  */
61
- export const nativeHomeTopbarWidgetIdSchema = z.enum(['weather', 'secrecy', 'live']);
63
+ export const nativeHomeTopbarWidgetIdSchema = z.enum(['weather', 'secrecy', 'live', 'publicIp']);
62
64
  export type NativeHomeTopbarWidgetId = z.infer<typeof nativeHomeTopbarWidgetIdSchema>;
63
65
 
64
66
  /**
@@ -186,6 +186,7 @@ export const TOPIC_FEATURE: Record<NativeLiveTopic, WorkspaceFeatureId | null> =
186
186
  finance: 'finance',
187
187
  audience: 'audience',
188
188
  osint: 'osint',
189
+ cve: 'cve',
189
190
  workspace: null,
190
191
  home: null,
191
192
  account: null,
@@ -39,6 +39,14 @@ export const reportProcessSchema = z.object({
39
39
  * l'expose pas (macOS, Windows).
40
40
  */
41
41
  deleted: z.boolean().nullable().default(null),
42
+ /**
43
+ * Fil du noyau (`PF_KTHREAD`), qui n'a par nature ni exécutable ni durée de
44
+ * vie stable : son nom encode un CPU et un index que le noyau recycle. Les
45
+ * règles de dérive l'écartent, sans quoi ce recyclage passerait pour des
46
+ * programmes qui apparaissent et disparaissent. `null` là où la plateforme
47
+ * ne l'expose pas (macOS, Windows) ou sur un agent trop ancien.
48
+ */
49
+ kernel: z.boolean().nullable().default(null),
42
50
  /** Number of PIDs aggregated under this name. */
43
51
  instances: z.number().int().positive().default(1),
44
52
  /** Summed CPU%, cumulative across cores (can exceed 100 — divide by `os.cores`). */
@@ -62,12 +62,16 @@ export const itemShareStateSchema = z.object({
62
62
  export type ItemShareState = z.infer<typeof itemShareStateSchema>;
63
63
 
64
64
  /**
65
- * Ce qu'un rôle peut faire sur un élément. Restrictif seulement : `none` ou
66
- * `read` abaissent ce que le rôle a sur la fonctionnalité, jamais l'inverse ;
67
- * le droit de feature reste le plafond, et l'écran des rôles dit à lui seul
68
- * qui voit quoi.
65
+ * Ce qu'un rôle peut faire sur un élément, **en surcharge** de ce que la
66
+ * fonctionnalité lui donne : `none` masque, `read` passe en lecture seule,
67
+ * `write` ouvre l'écriture à un rôle qui ne l'a qu'en lecture ailleurs.
68
+ *
69
+ * Un plancher demeure : sans au moins la LECTURE sur la fonctionnalité, aucun
70
+ * élément n'existe pour le rôle et rien ne se surcharge. C'est ce qui garde à
71
+ * l'écran des rôles sa réponse à « qui a accès à Uptime ? » ; sous ce plancher,
72
+ * il faudrait parcourir tous les éléments de l'espace pour le savoir.
69
73
  */
70
- export const itemAccessSchema = z.enum(['none', 'read']);
74
+ export const itemAccessSchema = z.enum(['none', 'read', 'write']);
71
75
  export type ItemAccess = z.infer<typeof itemAccessSchema>;
72
76
 
73
77
  export const itemRoleGrantSchema = z.object({
@@ -75,6 +79,15 @@ export const itemRoleGrantSchema = z.object({
75
79
  /** Absent de la liste = le rôle garde ce que la fonctionnalité lui donne. */
76
80
  access: itemAccessSchema
77
81
  });
82
+
83
+ /**
84
+ * Les permissions propres surchargées sur un élément : `true` accorde, `false`
85
+ * retire, une clé absente suit la fonctionnalité. Les deux sens, contrairement
86
+ * au niveau d'antan : confier le terminal sur UNE machine à un rôle qui ne l'a
87
+ * pas partout est le cas qui a fait sauter la règle du « restrictif seulement ».
88
+ */
89
+ export const itemExtraOverridesSchema = z.record(z.string().max(24), z.boolean());
90
+ export type ItemExtraOverrides = z.infer<typeof itemExtraOverridesSchema>;
78
91
  export type ItemRoleGrant = z.infer<typeof itemRoleGrantSchema>;
79
92
 
80
93
  /**
@@ -91,8 +104,12 @@ export const itemRoleGrantViewSchema = z.object({
91
104
  * effective quand `access` est `null`.
92
105
  */
93
106
  featureAccess: z.enum(['none', 'read', 'write']),
94
- /** L'exception posée sur cet élément, ou `null` : « comme la fonctionnalité ». */
95
- access: itemAccessSchema.nullable()
107
+ /** La surcharge posée sur cet élément, ou `null` : « comme la fonctionnalité ». */
108
+ access: itemAccessSchema.nullable(),
109
+ /** Les permissions propres que le rôle tient sur la **fonctionnalité** : l'héritage. */
110
+ featureExtras: z.array(z.string().max(24)).default([]),
111
+ /** Celles que cet élément-ci accorde (`true`) ou retire (`false`) au rôle. */
112
+ extraOverrides: itemExtraOverridesSchema.default({})
96
113
  });
97
114
  export type ItemRoleGrantView = z.infer<typeof itemRoleGrantViewSchema>;
98
115
 
@@ -100,6 +117,12 @@ export type ItemRoleGrantView = z.infer<typeof itemRoleGrantViewSchema>;
100
117
  export const itemGrantStateSchema = z.object({
101
118
  workspaceId: z.number().int().positive(),
102
119
  workspaceName: z.string(),
120
+ /**
121
+ * Les permissions propres de la fonctionnalité qui se surchargent élément par
122
+ * élément, intitulés compris : les booléens seulement. Un choix borné n'a
123
+ * pas d'ordre que le socle connaisse, et reste réglé sur le rôle.
124
+ */
125
+ extras: z.array(z.object({ key: z.string().max(24), label: z.string() })).default([]),
103
126
  roles: z.array(itemRoleGrantViewSchema)
104
127
  });
105
128
  export type ItemGrantState = z.infer<typeof itemGrantStateSchema>;
@@ -110,7 +133,8 @@ export type ItemGrantState = z.infer<typeof itemGrantStateSchema>;
110
133
  */
111
134
  export const itemRefSchema = z.object({
112
135
  feature: featureIdSchema,
113
- itemId: z.number().int().positive()
136
+ /** Texte : une feature choisit la clé de sa table, entière ou non (un appareil est un UUID). */
137
+ itemId: z.string().min(1).max(64)
114
138
  });
115
139
  export type ItemRef = z.infer<typeof itemRefSchema>;
116
140
 
@@ -131,19 +155,24 @@ export type ForeignRef = z.infer<typeof foreignRefSchema>;
131
155
  export interface ItemShareRow {
132
156
  workspace_id: number;
133
157
  feature: string;
134
- item_id: number;
158
+ item_id: string;
135
159
  home_workspace_id: number;
136
160
  shared_by_user_id: number;
137
161
  created: number;
162
+ /** Le rang de l'élément dans l'espace qui le reçoit, propre à cet espace. */
163
+ sort_order: number;
138
164
  }
139
165
 
140
166
  /** Ligne de `item_role_grants` (serveur uniquement). */
141
167
  export interface ItemRoleGrantRow {
142
168
  workspace_id: number;
143
169
  feature: string;
144
- item_id: number;
170
+ item_id: string;
145
171
  role_id: number;
146
- access: ItemAccess;
172
+ /** `null` quand la ligne n'existe que pour des permissions surchargées. */
173
+ access: ItemAccess | null;
174
+ /** Objet JSON `clé → booléen` des permissions surchargées ; `null` = aucune. */
175
+ extra_overrides: string | null;
147
176
  }
148
177
 
149
178
  export { featureAccessSchema };
@@ -83,7 +83,12 @@ export const workspaceFeatureIdSchema = z.enum([
83
83
  * OSINT. `read` = chercher et consulter l'historique de l'espace, `write` =
84
84
  * effacer l'historique et poser les clés d'API des fournisseurs.
85
85
  */
86
- 'osint'
86
+ 'osint',
87
+ /**
88
+ * Veille CVE. `read` = lire le fil et chercher dans le catalogue, `write` =
89
+ * épingler une CVE pour tout l'espace et poser la clé d'API du NVD.
90
+ */
91
+ 'cve'
87
92
  ]);
88
93
 
89
94
  export type WorkspaceFeatureId = z.infer<typeof workspaceFeatureIdSchema>;
@@ -142,6 +147,17 @@ export const workspaceFeatureGrantSchema = z.object({
142
147
  * n'émet pas de notifications.
143
148
  */
144
149
  channels: z.boolean(),
150
+ /**
151
+ * Régler ce que chaque rôle peut faire d'un élément pris séparément (l'onglet
152
+ * Permissions d'un élément). Distinct de `access` : surcharger un appareil
153
+ * n'est pas gérer la flotte, et distinct de la capacité `workspace.roles`,
154
+ * qui gouverne les rôles eux-mêmes — on peut confier le réglage par élément
155
+ * d'une fonctionnalité sans ouvrir l'écran des rôles.
156
+ *
157
+ * Ce droit-ci ne se surcharge PAS par élément, sans quoi il servirait à
158
+ * s'accorder tout le reste. Sans effet sur une fonctionnalité sans éléments.
159
+ */
160
+ itemPermissions: z.boolean().default(false),
145
161
  /**
146
162
  * Permissions déclarées par la feature elle-même (`extraPermissions` du
147
163
  * manifest) : booléen pour un `toggle`, valeur d'un `choice`. Une clé
@@ -187,6 +203,21 @@ export interface WorkspaceRoleRow {
187
203
  created: number;
188
204
  }
189
205
 
206
+ /**
207
+ * Une surcharge d'élément, du point de vue de l'appelant : ce que CE rôle-là
208
+ * obtient sur cette ligne, en remplacement de ce que la fonctionnalité donne.
209
+ */
210
+ export const itemGrantOverrideSchema = z.object({
211
+ feature: featureIdSchema,
212
+ itemId: z.string().min(1).max(64),
213
+ /** `null` : le niveau suit la fonctionnalité, seules les permissions changent. */
214
+ access: z.enum(['none', 'read', 'write']).nullable(),
215
+ /** `true` accorde, `false` retire ; une clé absente suit la fonctionnalité. */
216
+ extras: z.record(z.string().max(24), z.boolean()).default({})
217
+ });
218
+
219
+ export type ItemGrantOverride = z.infer<typeof itemGrantOverrideSchema>;
220
+
190
221
  /**
191
222
  * Droits effectifs de l'appelant dans l'espace actif, tels que le client les
192
223
  * reçoit pour n'afficher que ce qui est réellement accessible.
@@ -197,7 +228,15 @@ export interface WorkspaceRoleRow {
197
228
  export const workspacePermissionsSchema = z.object({
198
229
  isOwner: z.boolean(),
199
230
  capabilities: z.array(workspaceCapabilitySchema),
200
- features: z.array(workspaceFeatureGrantSchema)
231
+ features: z.array(workspaceFeatureGrantSchema),
232
+ /**
233
+ * Les surcharges posées sur des éléments précis pour le rôle de l'appelant.
234
+ * Elles voyagent avec ses droits parce que l'interface en a besoin élément
235
+ * par élément — griser le terminal d'UNE machine, ouvrir l'écriture sur une
236
+ * autre — et que `features` seule ne peut pas y répondre. Seules les
237
+ * exceptions y figurent ; l'absence vaut « comme la fonctionnalité ».
238
+ */
239
+ itemOverrides: z.array(itemGrantOverrideSchema).default([])
201
240
  });
202
241
 
203
242
  export type WorkspacePermissions = z.infer<typeof workspacePermissionsSchema>;
@@ -1,7 +1,12 @@
1
1
  import { z } from 'zod';
2
- import { deviceSchema } from '../domain/device';
2
+ import { deviceSchema, terminalUser } from '../domain/device';
3
3
  import { fileMutateOpSchema, fileSearchFilterSchema } from '../domain/deviceFiles';
4
- import { deviceLogFilterSchema, DEVICE_LOG_PAGE_MAX } from '../domain/deviceLogs';
4
+ import {
5
+ deviceLogAnchorSchema,
6
+ deviceLogFilterSchema,
7
+ DEVICE_LOG_OFFSET_MAX,
8
+ DEVICE_LOG_PAGE_MAX
9
+ } from '../domain/deviceLogs';
5
10
  import { packageManagerIdSchema } from '../domain/packages';
6
11
  import { agentLifecycleActionSchema, agentPowerActionSchema } from '../protocol/agent';
7
12
 
@@ -44,7 +49,8 @@ export const agentCollect = {
44
49
 
45
50
  /**
46
51
  * Run a system power action on the device (shutdown / reboot / suspend / hibernate
47
- * / lock). Owner-or-admin; the agent must be online. The command only acknowledges
52
+ * / lock). Needs the `system` permission on Appareils; the agent must be online.
53
+ * The command only acknowledges
48
54
  * the request — the agent applies it best-effort and the outcome streams back as a
49
55
  * `device.powerResult` push event (the caller must be subscribed to the device).
50
56
  */
@@ -58,8 +64,8 @@ export const agentPower = {
58
64
  * Stop or cleanly restart the agent process on the device (not the machine).
59
65
  * `stop`: a supervised agent is relaunched by its manager, a standalone one
60
66
  * stays offline until relaunched on the machine. `restart`: exit-and-relaunch.
61
- * Owner-or-admin; the agent must be online. Fire-and-forget: the outcome is
62
- * observed through presence.
67
+ * Needs `devices: write`; the agent must be online. Fire-and-forget: the outcome
68
+ * is observed through presence.
63
69
  */
64
70
  export const agentLifecycle = {
65
71
  command: 'agent.lifecycle' as const,
@@ -132,7 +138,8 @@ export const agentUpgradePackages = {
132
138
 
133
139
  /**
134
140
  * Ask the agent to enumerate the log sources present on the device (system journal,
135
- * Docker containers, log files…). Owner-or-admin + agent online. The command only
141
+ * Docker containers, log files…). Needs the `logs` permission on Appareils +
142
+ * agent online. The command only
136
143
  * acknowledges; the list arrives as a `device.logSources` push event (the caller
137
144
  * must be subscribed to the device).
138
145
  */
@@ -146,6 +153,10 @@ export const agentLogSources = {
146
153
  * Query one source with an advanced filter. `queryId` correlates the streamed
147
154
  * result back to this request (results have no requestId). Lines arrive as one or
148
155
  * more `device.logLines` push events, the last carrying `done: true`.
156
+ *
157
+ * `offset` and `anchor` page through the history: the agent returns the window
158
+ * `[offset, offset + limit)` counted from the anchor end. A short page means the
159
+ * source held nothing more in that direction.
149
160
  */
150
161
  export const agentLogQuery = {
151
162
  command: 'agent.logQuery' as const,
@@ -155,7 +166,9 @@ export const agentLogQuery = {
155
166
  /** Client-generated id echoed back on every `device.logLines` for this query. */
156
167
  queryId: z.string().min(1).max(64),
157
168
  filter: deviceLogFilterSchema.optional(),
158
- limit: z.number().int().positive().max(DEVICE_LOG_PAGE_MAX).optional()
169
+ limit: z.number().int().positive().max(DEVICE_LOG_PAGE_MAX).optional(),
170
+ offset: z.number().int().nonnegative().max(DEVICE_LOG_OFFSET_MAX).optional(),
171
+ anchor: deviceLogAnchorSchema.optional()
159
172
  }),
160
173
  output: z.object({ ok: z.boolean() })
161
174
  };
@@ -166,16 +179,8 @@ const rows = z.number().int().min(1).max(2000);
166
179
  /** Base64-encoded terminal bytes, capped per frame (~1.5 MB). */
167
180
  const termData = z.string().max(2_000_000);
168
181
  /**
169
- * Optional OS account to open the session under. Restricted to safe username
170
- * characters (no shell metacharacters), since it reaches a `su` on the device.
171
- */
172
- export const terminalUser = z
173
- .string()
174
- .regex(/^[A-Za-z0-9._-]+$/, 'Nom d’utilisateur invalide')
175
- .max(32);
176
-
177
- /**
178
- * Open an interactive terminal (PTY) on the device. Owner-or-admin + agent online.
182
+ * Open an interactive terminal (PTY) on the device. Needs the `terminal`
183
+ * permission on Appareils + agent online.
179
184
  * `sessionId` is client-generated and ties every later input/resize/close and the
180
185
  * streamed `device.termOutput` / `device.termExit` push events together (the caller
181
186
  * must be subscribed). `user` runs the shell under that account (`su -l`); omitted
@@ -213,7 +218,8 @@ const opId = z.string().min(1).max(64);
213
218
  const path = z.string().min(1).max(4096);
214
219
 
215
220
  /**
216
- * List a directory. Owner-or-admin + agent online. The listing arrives as a
221
+ * List a directory. Needs the `files` permission on Appareils + agent online.
222
+ * The listing arrives as a
217
223
  * `device.filesListing` push event keyed by `opId` (the caller must be subscribed).
218
224
  */
219
225
  export const agentFilesList = {
@@ -2,6 +2,7 @@ import { z } from 'zod';
2
2
 
3
3
  import {
4
4
  itemAccessSchema,
5
+ itemExtraOverridesSchema,
5
6
  itemGrantStateSchema,
6
7
  itemRefSchema,
7
8
  itemShareStateSchema
@@ -48,17 +49,31 @@ export const itemGrantList = {
48
49
  };
49
50
 
50
51
  /**
51
- * Abaisse (ou rétablit) ce qu'un rôle peut faire sur cet élément, dans l'espace
52
- * visé (`workspaceId` absent = l'actif). `access: null` retire la restriction :
53
- * le rôle reprend ce que la fonctionnalité lui donne.
52
+ * Surcharge ce qu'un rôle peut faire sur cet élément, dans l'espace visé
53
+ * (`workspaceId` absent = l'actif). Les deux volets se règlent seuls : un champ
54
+ * omis reste inchangé, comme pour la configuration d'un appareil.
55
+ *
56
+ * `access: null` et `extraOverrides: {}` rendent l'élément à l'héritage : le
57
+ * rôle reprend ce que la fonctionnalité lui donne. Une surcharge va dans les
58
+ * deux sens, le plancher de visibilité mis à part : il faut au moins la lecture
59
+ * sur la fonctionnalité pour que l'élément existe (cf. `itemAccessSchema`).
60
+ *
61
+ * Écrire exige `workspace.roles` sur l'espace visé, ou le champ
62
+ * `itemPermissions` du grant de cette fonctionnalité.
54
63
  */
55
64
  export const itemGrantSet = {
56
65
  command: 'share.grantSet' as const,
57
- input: itemRefSchema.extend({
58
- workspaceId: z.number().int().positive().optional(),
59
- roleId: z.number().int().positive(),
60
- access: itemAccessSchema.nullable()
61
- }),
66
+ input: itemRefSchema
67
+ .extend({
68
+ workspaceId: z.number().int().positive().optional(),
69
+ roleId: z.number().int().positive(),
70
+ access: itemAccessSchema.nullable().optional(),
71
+ /** Remplace l'ensemble des permissions surchargées sur cet élément. */
72
+ extraOverrides: itemExtraOverridesSchema.optional()
73
+ })
74
+ .refine((v) => v.access !== undefined || v.extraOverrides !== undefined, {
75
+ message: 'No grant field provided'
76
+ }),
62
77
  output: itemGrantStateSchema
63
78
  };
64
79
 
@@ -26,13 +26,7 @@ export const linkCodeRequestSchema = z.object({
26
26
  * Approve the device the moment it enrols with this code, instead of
27
27
  * leaving it `pending` for manual approval. Defaults to `false`.
28
28
  */
29
- autoApprove: z.boolean().default(false),
30
- /**
31
- * Espace dans lequel la machine sera rangée à l'enrôlement. Omis → l'espace
32
- * actif de l'émetteur. Explicite (n'importe quel espace existant) : réservé
33
- * à l'administrateur global.
34
- */
35
- workspaceId: z.number().int().positive().optional()
29
+ autoApprove: z.boolean().default(false)
36
30
  });
37
31
 
38
32
  export type LinkCodeRequest = z.infer<typeof linkCodeRequestSchema>;
package/src/index.ts CHANGED
@@ -241,8 +241,10 @@ export {
241
241
  export type { LogCategory, LogEntry, LogLevelName, LogRow, LogSource } from './domain/logs';
242
242
  export {
243
243
  DEVICE_LOG_LEVELS,
244
+ DEVICE_LOG_OFFSET_MAX,
244
245
  DEVICE_LOG_PAGE_DEFAULT,
245
246
  DEVICE_LOG_PAGE_MAX,
247
+ deviceLogAnchorSchema,
246
248
  deviceLogFilterSchema,
247
249
  deviceLogLevelSchema,
248
250
  deviceLogLineSchema,
@@ -280,6 +282,7 @@ export type {
280
282
  SyncShareStatus
281
283
  } from './domain/syncProtocol';
282
284
  export type {
285
+ DeviceLogAnchor,
283
286
  DeviceLogFilter,
284
287
  DeviceLogLevel,
285
288
  DeviceLogLine,
@@ -437,6 +440,7 @@ export type {
437
440
  ExternalFeatureId,
438
441
  FeatureAccess,
439
442
  FeatureId,
443
+ ItemGrantOverride,
440
444
  WorkspaceCapability,
441
445
  WorkspaceFeatureGrant,
442
446
  WorkspaceFeatureId,
@@ -456,15 +460,10 @@ export {
456
460
  DEFAULT_RETENTION_DAYS,
457
461
  devicePlatformSchema,
458
462
  deviceSchema,
459
- deviceStatusSchema
460
- } from './domain/device';
461
- export type {
462
- Device,
463
- DevicePlatform,
464
- DeviceRow,
465
- DeviceStatus,
466
- DeviceWorkspaceRow
463
+ deviceStatusSchema,
464
+ terminalUser
467
465
  } from './domain/device';
466
+ export type { Device, DevicePlatform, DeviceRow, DeviceStatus } from './domain/device';
468
467
  export { packageManagerIdSchema, packageManagerSchema } from './domain/packages';
469
468
  export type { PackageManager, PackageManagerId } from './domain/packages';
470
469
  export {
@@ -560,6 +559,7 @@ export type { FeatureDescriptor } from './domain/featureRegistry';
560
559
  export {
561
560
  foreignRefSchema,
562
561
  itemAccessSchema,
562
+ itemExtraOverridesSchema,
563
563
  itemGrantStateSchema,
564
564
  itemRefSchema,
565
565
  itemRoleGrantSchema,
@@ -571,6 +571,7 @@ export {
571
571
  export type {
572
572
  ForeignRef,
573
573
  ItemAccess,
574
+ ItemExtraOverrides,
574
575
  ItemGrantState,
575
576
  ItemRef,
576
577
  ItemRoleGrant,
@@ -689,8 +690,7 @@ export {
689
690
  agentTermResize,
690
691
  agentUnsubscribe,
691
692
  agentUpdate,
692
- agentUpgradePackages,
693
- terminalUser
693
+ agentUpgradePackages
694
694
  } from './features/agent';
695
695
  export {
696
696
  notifyChannelAdd,
@@ -22,6 +22,7 @@ import {
22
22
  fileUsageEntrySchema
23
23
  } from '../domain/deviceFiles';
24
24
  import {
25
+ deviceLogAnchorSchema,
25
26
  deviceLogFilterSchema,
26
27
  deviceLogLineSchema,
27
28
  deviceLogSourceSchema
@@ -589,7 +590,9 @@ export const agentLogQueryPayloadSchema = z.object({
589
590
  queryId: z.string().max(64),
590
591
  sourceId: z.string().min(1).max(512),
591
592
  filter: deviceLogFilterSchema.optional(),
592
- limit: z.number().int().positive().optional()
593
+ limit: z.number().int().positive().optional(),
594
+ offset: z.number().int().nonnegative().optional(),
595
+ anchor: deviceLogAnchorSchema.optional()
593
596
  });
594
597
  export type AgentLogQueryPayload = z.infer<typeof agentLogQueryPayloadSchema>;
595
598
 
@@ -156,7 +156,7 @@ declare module 'deveye-sdk-client' {
156
156
  | {
157
157
  kind: 'item';
158
158
  feature: FeatureId;
159
- itemId: number | string;
159
+ itemId: string;
160
160
  itemLabel: string;
161
161
  shareable?: boolean;
162
162
  };
@@ -171,6 +171,37 @@ declare module 'deveye-sdk-client' {
171
171
  */
172
172
  onOpenChange?: (open: boolean) => void;
173
173
  }>;
174
+ /**
175
+ * One provider of a feature and the key it wants. The row carries the state
176
+ * and the gesture; the key itself is typed in a dialog.
177
+ */
178
+ export interface ProviderKeyRow {
179
+ id: string;
180
+ label: string;
181
+ /** What the key unlocks, or what the provider brings. */
182
+ hint: string;
183
+ /** A key is on file for this provider. */
184
+ held: boolean;
185
+ /** `false` for a provider that needs none (Open-Meteo): shown, nothing to set. */
186
+ needsKey?: boolean;
187
+ /** Where to get one. Only offered while no key is held. */
188
+ signupUrl?: string;
189
+ /** Icon class suffix, without the `icon-` prefix. */
190
+ icon?: string;
191
+ }
192
+ /**
193
+ * The `sources` tab of a feature whose providers are a fixed list, each
194
+ * wanting one key. Renders the rows, the add/edit button on each, and the
195
+ * dialog. `onSave` / `onRemove` reject to keep the dialog open on the error.
196
+ */
197
+ export const ProviderKeys: ComponentType<{
198
+ rows: ProviderKeyRow[];
199
+ canWrite: boolean;
200
+ onSave: (id: string, key: string) => Promise<void>;
201
+ onRemove: (id: string) => Promise<void>;
202
+ /** Shown to a caller without write access. */
203
+ readOnlyHint: string;
204
+ }>;
174
205
  /** The canonical settings row classes (channelRow, field, sectionHint...). */
175
206
  export const settingsStyles: Readonly<Record<string, string>>;
176
207
  /** A plain count on a home card: a big number, a noun, a secondary line. */
@@ -385,9 +416,12 @@ declare module 'deveye-sdk-client' {
385
416
  export function useWorkspacePermissions(): {
386
417
  isOwner: boolean;
387
418
  can: (c: WorkspaceCapability) => boolean;
388
- canFeature: (f: FeatureId, level?: FeatureAccess) => boolean;
419
+ /** `itemId` répond pour CET élément, surcharge comprise. */
420
+ canFeature: (f: FeatureId, level?: FeatureAccess, itemId?: string) => boolean;
389
421
  canChannels: (f: FeatureId) => boolean;
390
- canExtra: (f: FeatureId, key: string) => boolean;
422
+ canManageItemGrants: (f: FeatureId) => boolean;
423
+ /** `itemId` répond pour CET élément, surcharge comprise. */
424
+ canExtra: (f: FeatureId, key: string, itemId?: string) => boolean;
391
425
  extraValue: (
392
426
  f: FeatureId,
393
427
  key: string,
@@ -446,7 +480,7 @@ declare module 'deveye-sdk-client' {
446
480
  * host's teleport, the same mechanism as "join someone". The access guard
447
481
  * is the host's; a missing item is ignored after a short grace.
448
482
  */
449
- export function openFeature(feature: string, itemId?: number): void;
483
+ export function openFeature(feature: string, itemId?: number | string): void;
450
484
  /**
451
485
  * Ask the feature popup for a wider frame (px) while the calling
452
486
  * component is mounted, `null` to ask for nothing. Several requests
package/src/sdk/client.ts CHANGED
@@ -11,18 +11,24 @@ import type { ComponentType, ReactNode } from 'react';
11
11
  */
12
12
 
13
13
  /**
14
- * The scope a settings panel is opened for. An item id is a number for every
15
- * row-keyed feature (the default), a string for a device (a UUID): a module
16
- * whose items are strings types its panels `SettingsPanelProps<string>`. The
17
- * shell's own sections (sharing, permissions, notifications) key on the number.
14
+ * The scope a settings panel is opened for. An item id is text, whatever key
15
+ * the feature's own table uses: a row-keyed feature reads it back with
16
+ * `Number(...)`, a device is a UUID as it stands.
18
17
  */
19
- export type SdkSettingsScope<Id extends number | string = number> =
20
- { kind: 'feature' } | { kind: 'item'; itemId: Id; itemLabel: string };
18
+ export type SdkSettingsScope =
19
+ { kind: 'feature' } | { kind: 'item'; itemId: string; itemLabel: string };
21
20
 
22
- export interface SettingsPanelProps<Id extends number | string = number> {
23
- scope: SdkSettingsScope<Id>;
21
+ export interface SettingsPanelProps {
22
+ scope: SdkSettingsScope;
24
23
  /** Caller has `write` on the feature. Render read-only when false. */
25
24
  canWrite: boolean;
25
+ /**
26
+ * Closes the settings dialog. For a panel that removes the very item being
27
+ * configured: the scope it was opened on no longer exists, and the shell
28
+ * would otherwise fall back to the feature's own tabs under the item's name.
29
+ * Not a substitute for saving — every other change applies in place.
30
+ */
31
+ close(): void;
26
32
  }
27
33
 
28
34
  export interface FeatureViewProps {
@@ -47,10 +53,7 @@ export interface FeatureClient {
47
53
  * `'sources'`, `'encryption'`, and any custom tab id. Generic tabs
48
54
  * (`'notifications'`, `'permissions'`) need no panel.
49
55
  */
50
- // `never` as the id: a panel typed for numbers and one typed for strings
51
- // are both assignable here (props are contravariant), and the shell, which
52
- // holds a `number | string`, casts once at that boundary.
53
- settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps<never>>>>;
56
+ settingsPanels?: Readonly<Record<string, ComponentType<SettingsPanelProps>>>;
54
57
  /**
55
58
  * The compact topbar widget declared by `manifest.topbarWidget`. Rendered
56
59
  * with NO props: everything it shows must come through YOUR feature's
package/src/sdk/server.ts CHANGED
@@ -476,13 +476,13 @@ export interface SdkItems {
476
476
  * feature grants, never raise it. Empty for the owner and for a member
477
477
  * without a role. Listings filter with it.
478
478
  */
479
- restrictions(): Promise<ReadonlyMap<number, ItemAccess>>;
479
+ restrictions(): Promise<ReadonlyMap<string, ItemAccess>>;
480
480
  /**
481
481
  * Throws `forbidden` unless THIS item is open to the caller at `level`
482
482
  * (default `'read'`), role restriction included. Commands that target one
483
483
  * item call it first.
484
484
  */
485
- assert(itemId: number, level?: FeatureAccess): Promise<void>;
485
+ assert(itemId: string, level?: FeatureAccess): Promise<void>;
486
486
  /**
487
487
  * The item no longer exists: drops its projections, its role restrictions
488
488
  * and its notification route. Call it from your delete handler; nothing
@@ -490,7 +490,7 @@ export interface SdkItems {
490
490
  * feature), so without this call the next item to inherit the id would
491
491
  * inherit them too.
492
492
  */
493
- forget(itemId: number): Promise<void>;
493
+ forget(itemId: string): Promise<void>;
494
494
  }
495
495
 
496
496
  /**
@@ -504,11 +504,17 @@ export interface SdkItems {
504
504
  */
505
505
  export interface SdkShareScope {
506
506
  /** The ids of the items projected into the active workspace from elsewhere. */
507
- readonly foreignIds: ReadonlySet<number>;
507
+ readonly foreignIds: ReadonlySet<string>;
508
508
  /** The home workspace of a projected item, or null when it is at home. */
509
- homeOf(itemId: number): number | null;
509
+ homeOf(itemId: string): number | null;
510
510
  /** The open cipher of the workspace the item lives in (the active one when it is at home). */
511
- cipherFor(itemId: number): Promise<SdkCipher>;
511
+ cipherFor(itemId: string): Promise<SdkCipher>;
512
+ /**
513
+ * The rank a projected item holds in the ACTIVE workspace, or null when it
514
+ * is at home (its own table carries the rank there). Each workspace orders
515
+ * what it sees independently.
516
+ */
517
+ orderOf(itemId: string): number | null;
512
518
  }
513
519
 
514
520
  /** Cross-workspace projection of your items (manifest `shareTier` other than `'never'`). */
@@ -518,6 +524,11 @@ export interface SdkSharing {
518
524
  * read command; the result does not outlive the command.
519
525
  */
520
526
  scope(): Promise<SdkShareScope>;
527
+ /**
528
+ * Sets the rank of a projected item in the ACTIVE workspace. For an item
529
+ * at home, rank belongs to your own table: write it there instead.
530
+ */
531
+ setOrder(itemId: string, order: number): Promise<void>;
521
532
  }
522
533
 
523
534
  /** Live invalidation from a background service, which writes without a command. */
@@ -802,7 +813,7 @@ export interface FeatureItemsEntry<Repo = unknown> {
802
813
  * (its own, or one it is projected into); null when it does not exist
803
814
  * there. The sharing commands rely on it to tell a home from a window.
804
815
  */
805
- homeOf(repo: Repo, itemId: number, workspaceId: number): Promise<number | null>;
816
+ homeOf(repo: Repo, itemId: string, workspaceId: number): Promise<number | null>;
806
817
  /**
807
818
  * The item's display name, decrypted with `cipher` (the open cipher of
808
819
  * `workspaceId`), or null when the item is gone or unreadable. Names the
@@ -812,7 +823,7 @@ export interface FeatureItemsEntry<Repo = unknown> {
812
823
  labelOf(
813
824
  repo: Repo,
814
825
  cipher: SdkCipher,
815
- itemId: number,
826
+ itemId: string,
816
827
  workspaceId: number
817
828
  ): Promise<string | null>;
818
829
  /**
@@ -823,7 +834,7 @@ export interface FeatureItemsEntry<Repo = unknown> {
823
834
  * moment it is asked, with a message that says why. Called with the item's
824
835
  * HOME workspace.
825
836
  */
826
- shareable?(repo: Repo, itemId: number, workspaceId: number): Promise<boolean>;
837
+ shareable?(repo: Repo, itemId: string, workspaceId: number): Promise<boolean>;
827
838
  }
828
839
 
829
840
  // Le conteneur chiffré que CloudSync et Backup partagent (voir `devb.ts`).
@@ -243,7 +243,7 @@ export interface TestContext<Repo> extends SdkFeatureContext<Repo> {
243
243
  recorded: RecordedCalls;
244
244
  store: TestFeatureStore;
245
245
  /** Item ids passed to `items.forget`, in order. */
246
- forgotten: number[];
246
+ forgotten: string[];
247
247
  }
248
248
 
249
249
  export interface TestContextOverrides<Repo> {
@@ -287,13 +287,13 @@ export interface TestContextOverrides<Repo> {
287
287
  */
288
288
  unlocked?: boolean;
289
289
  /** The caller's role restrictions on items, by item id. Default none. */
290
- itemRestrictions?: Readonly<Record<number, ItemAccess>>;
290
+ itemRestrictions?: Readonly<Record<string, ItemAccess>>;
291
291
  /**
292
292
  * Items projected INTO the workspace, as `itemId → home workspace id`.
293
293
  * Default none: every item is at home. `sharing.scope().cipherFor` is the
294
294
  * identity cipher either way.
295
295
  */
296
- shares?: Readonly<Record<number, number>>;
296
+ shares?: Readonly<Record<string, number>>;
297
297
  /** The named contracts the host holds (`ctx.providers.get(key)`). */
298
298
  providers?: Readonly<Record<string, unknown>>;
299
299
  }
@@ -331,13 +331,12 @@ export function createTestContext<Repo = undefined>(
331
331
  agents: recordingAgents(recorded),
332
332
  ...overrides.deveye
333
333
  };
334
- const restrictions = new Map<number, ItemAccess>(
335
- Object.entries(overrides.itemRestrictions ?? {}).map(([id, access]) => [Number(id), access])
334
+ const restrictions = new Map<string, ItemAccess>(
335
+ Object.entries(overrides.itemRestrictions ?? {})
336
336
  );
337
- const homes = new Map<number, number>(
338
- Object.entries(overrides.shares ?? {}).map(([id, home]) => [Number(id), home])
339
- );
340
- const forgotten: number[] = [];
337
+ const homes = new Map<string, number>(Object.entries(overrides.shares ?? {}));
338
+ const forgotten: string[] = [];
339
+ const orders: { itemId: string; order: number }[] = [];
341
340
  return {
342
341
  recorded,
343
342
  forgotten,
@@ -382,8 +381,16 @@ export function createTestContext<Repo = undefined>(
382
381
  Promise.resolve({
383
382
  foreignIds: new Set(homes.keys()),
384
383
  homeOf: (itemId) => homes.get(itemId) ?? null,
385
- cipherFor: () => Promise.resolve(identityCipher)
386
- })
384
+ cipherFor: () => Promise.resolve(identityCipher),
385
+ orderOf: (itemId) =>
386
+ homes.has(itemId)
387
+ ? (orders.find((o) => o.itemId === itemId)?.order ?? 0)
388
+ : null
389
+ }),
390
+ setOrder: (itemId, order) => {
391
+ orders.push({ itemId, order });
392
+ return Promise.resolve();
393
+ }
387
394
  },
388
395
  userId: overrides.userId ?? 1,
389
396
  workspaceId,