@deveye/types 0.17.1 → 0.18.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/src/http/auth.ts CHANGED
@@ -20,7 +20,13 @@ export const sessionBundleSchema = z.object({
20
20
  theme: themeStateSchema.nullable(),
21
21
  homeLayout: homeLayoutSchema.nullable(),
22
22
  /** Droits de l'appelant dans l'espace actif, pour que l'UI masque le reste. */
23
- permissions: workspacePermissionsSchema
23
+ permissions: workspacePermissionsSchema,
24
+ /**
25
+ * Ce serveur accepte-t-il les signalements (`FEEDBACK_ENABLED`) ? Porté par
26
+ * le bundle plutôt que par une requête à part : le client doit le savoir
27
+ * avant son premier rendu, pour ne pas faire clignoter le bouton.
28
+ */
29
+ feedbackEnabled: z.boolean()
24
30
  });
25
31
 
26
32
  export type SessionBundle = z.infer<typeof sessionBundleSchema>;
package/src/index.ts CHANGED
@@ -31,6 +31,13 @@ export {
31
31
  AGENT_LOG_LINES,
32
32
  AGENT_LOG_QUERY,
33
33
  AGENT_LOG_SOURCES,
34
+ AGENT_DOCKER_ACTION,
35
+ AGENT_DOCKER_DONE,
36
+ AGENT_DOCKER_INVENTORY,
37
+ AGENT_DOCKER_INVENTORY_RESULT,
38
+ AGENT_DOCKER_PROGRESS,
39
+ AGENT_DOCKER_STATS,
40
+ AGENT_DOCKER_STATS_RESULT,
34
41
  AGENT_LOG_SOURCES_RESULT,
35
42
  AGENT_METRICS_BATCH,
36
43
  AGENT_PKG_DONE,
@@ -84,6 +91,11 @@ export {
84
91
  agentLifecyclePayloadSchema,
85
92
  agentLogLinesPayloadSchema,
86
93
  agentLogQueryPayloadSchema,
94
+ agentDockerActionPayloadSchema,
95
+ agentDockerDonePayloadSchema,
96
+ agentDockerInventoryResultPayloadSchema,
97
+ agentDockerProgressPayloadSchema,
98
+ agentDockerStatsResultPayloadSchema,
87
99
  agentLogSourcesResultPayloadSchema,
88
100
  agentPkgDonePayloadSchema,
89
101
  agentPkgListResultPayloadSchema,
@@ -133,6 +145,10 @@ export {
133
145
  DEVICE_FILES_OP_EVENT,
134
146
  DEVICE_FILES_USAGE_EVENT,
135
147
  DEVICE_LOG_LINES_EVENT,
148
+ DEVICE_DOCKER_DONE_EVENT,
149
+ DEVICE_DOCKER_INVENTORY_EVENT,
150
+ DEVICE_DOCKER_PROGRESS_EVENT,
151
+ DEVICE_DOCKER_STATS_EVENT,
136
152
  DEVICE_LOG_SOURCES_EVENT,
137
153
  DEVICE_POWER_EVENT,
138
154
  DEVICE_PRESENCE_EVENT,
@@ -146,6 +162,10 @@ export {
146
162
  deviceFilesOpPushSchema,
147
163
  deviceFilesUsagePushSchema,
148
164
  deviceLogLinesPushSchema,
165
+ deviceDockerDonePushSchema,
166
+ deviceDockerInventoryPushSchema,
167
+ deviceDockerProgressPushSchema,
168
+ deviceDockerStatsPushSchema,
149
169
  deviceLogSourcesPushSchema,
150
170
  devicePowerPushSchema,
151
171
  devicePresenceSchema,
@@ -212,6 +232,11 @@ export type {
212
232
  DeviceFilesOpPush,
213
233
  DeviceFilesUsagePush,
214
234
  DeviceLogLinesPush,
235
+ AgentDockerActionPayload,
236
+ DeviceDockerDonePush,
237
+ DeviceDockerInventoryPush,
238
+ DeviceDockerProgressPush,
239
+ DeviceDockerStatsPush,
215
240
  DeviceLogSourcesPush,
216
241
  DevicePowerPush,
217
242
  DevicePresence,
@@ -239,6 +264,29 @@ export {
239
264
  logSourceSchema
240
265
  } from './domain/logs';
241
266
  export type { LogCategory, LogEntry, LogLevelName, LogRow, LogSource } from './domain/logs';
267
+ export {
268
+ FEEDBACK_ERRORS_KEPT,
269
+ FEEDBACK_MESSAGE_MAX,
270
+ FEEDBACK_REQUESTS_KEPT,
271
+ FEEDBACK_VIEWS_KEPT,
272
+ feedbackEntrySchema,
273
+ feedbackErrorTraceSchema,
274
+ feedbackKindSchema,
275
+ feedbackRequestTraceSchema,
276
+ feedbackSnapshotSchema,
277
+ feedbackStatusSchema,
278
+ feedbackViewTraceSchema
279
+ } from './domain/feedback';
280
+ export type {
281
+ FeedbackEntry,
282
+ FeedbackErrorTrace,
283
+ FeedbackKind,
284
+ FeedbackRequestTrace,
285
+ FeedbackRow,
286
+ FeedbackSnapshot,
287
+ FeedbackStatus,
288
+ FeedbackViewTrace
289
+ } from './domain/feedback';
242
290
  export {
243
291
  DEVICE_LOG_LEVELS,
244
292
  DEVICE_LOG_OFFSET_MAX,
@@ -251,6 +299,34 @@ export {
251
299
  deviceLogSourceKindSchema,
252
300
  deviceLogSourceSchema
253
301
  } from './domain/deviceLogs';
302
+ export {
303
+ containerEngineSchema,
304
+ containerStateSchema,
305
+ DOCKER_LONG_ACTIONS,
306
+ DOCKER_UNTARGETED_ACTIONS,
307
+ dockerActionSchema,
308
+ dockerContainerSchema,
309
+ dockerEngineStatusSchema,
310
+ dockerImageSchema,
311
+ dockerInventorySchema,
312
+ dockerNetworkSchema,
313
+ dockerStatSchema,
314
+ dockerVolumeSchema,
315
+ isLongDockerAction,
316
+ isUntargetedDockerAction
317
+ } from './domain/deviceDocker';
318
+ export type {
319
+ ContainerEngine,
320
+ ContainerState,
321
+ DockerAction,
322
+ DockerContainer,
323
+ DockerEngineStatus,
324
+ DockerImage,
325
+ DockerInventory,
326
+ DockerNetwork,
327
+ DockerStat,
328
+ DockerVolume
329
+ } from './domain/deviceDocker';
254
330
  export {
255
331
  cloudSyncProgressSchema,
256
332
  cloudSyncShareStateSchema,
@@ -380,6 +456,8 @@ export {
380
456
  LIVE_CURSOR_COMMAND,
381
457
  LIVE_CURSORS_EVENT,
382
458
  LIVE_PEERS_EVENT,
459
+ LIVE_SAY_COMMAND,
460
+ LIVE_SAYS_EVENT,
383
461
  LIVE_TYPERS_EVENT,
384
462
  LIVE_TYPING_COMMAND,
385
463
  liveChangedPushSchema,
@@ -388,14 +466,20 @@ export {
388
466
  liveCursorsPushSchema,
389
467
  liveHere,
390
468
  livePeersPushSchema,
469
+ liveSayFrameSchema,
470
+ liveSaysPushSchema,
391
471
  liveTypersPushSchema,
392
- liveTypingFrameSchema
472
+ liveTypingFrameSchema,
473
+ SAY_MAX_LENGTH,
474
+ SAY_MAX_LINES
393
475
  } from './features/live';
394
476
  export type {
395
477
  LiveChangedPush,
396
478
  LiveCursorFrame,
397
479
  LiveCursorsPush,
398
480
  LivePeersPush,
481
+ LiveSayFrame,
482
+ LiveSaysPush,
399
483
  LiveTypersPush,
400
484
  LiveTypingFrame
401
485
  } from './features/live';
@@ -552,6 +636,7 @@ export {
552
636
  allFeatureDescriptors,
553
637
  featureDescriptor,
554
638
  featureLabel,
639
+ itemNounForms,
555
640
  maybeFeatureDescriptor,
556
641
  registerExternalFeature
557
642
  } from './domain/featureRegistry';
@@ -683,6 +768,9 @@ export {
683
768
  agentFilesMutate,
684
769
  agentFilesSearch,
685
770
  agentFilesUpload,
771
+ agentDockerAction,
772
+ agentDockerInventory,
773
+ agentDockerStats,
686
774
  agentLifecycle,
687
775
  agentListPackages,
688
776
  agentLogQuery,
@@ -742,6 +830,17 @@ export {
742
830
  logsList
743
831
  } from './features/logs';
744
832
  export type { LogFilter } from './features/logs';
833
+ export {
834
+ FEEDBACK_PAGE_DEFAULT,
835
+ FEEDBACK_PAGE_MAX,
836
+ feedbackCommands,
837
+ feedbackDelete,
838
+ feedbackFilterSchema,
839
+ feedbackList,
840
+ feedbackSetStatus,
841
+ feedbackSubmit
842
+ } from './features/feedback';
843
+ export type { FeedbackFilter } from './features/feedback';
745
844
 
746
845
  export {
747
846
  changePasswordRequestSchema,
@@ -27,6 +27,12 @@ import {
27
27
  deviceLogLineSchema,
28
28
  deviceLogSourceSchema
29
29
  } from '../domain/deviceLogs';
30
+ import {
31
+ containerEngineSchema,
32
+ dockerActionSchema,
33
+ dockerInventorySchema,
34
+ dockerStatSchema
35
+ } from '../domain/deviceDocker';
30
36
  import { metricsBatchSchema, metricSnapshotSchema } from '../domain/metrics';
31
37
  import { packageManagerIdSchema, packageManagerSchema } from '../domain/packages';
32
38
  import {
@@ -129,6 +135,43 @@ export const agentPkgDonePayloadSchema = z.object({
129
135
  error: z.string().max(500).optional()
130
136
  });
131
137
 
138
+ /** Agent's reply to `docker.inventory`: the host's whole container inventory. */
139
+ export const AGENT_DOCKER_INVENTORY_RESULT = 'docker.inventoryResult' as const;
140
+
141
+ export const agentDockerInventoryResultPayloadSchema = z.object({
142
+ deviceId: z.uuid(),
143
+ inventory: dockerInventorySchema
144
+ });
145
+
146
+ /** Agent's reply to `docker.stats`: a one-shot resource sample per running container. */
147
+ export const AGENT_DOCKER_STATS_RESULT = 'docker.statsResult' as const;
148
+
149
+ export const agentDockerStatsResultPayloadSchema = z.object({
150
+ deviceId: z.uuid(),
151
+ stats: z.array(dockerStatSchema)
152
+ });
153
+
154
+ /** Live output line of a long `docker.action` (pull, prune, recreate). */
155
+ export const AGENT_DOCKER_PROGRESS = 'docker.progress' as const;
156
+
157
+ export const agentDockerProgressPayloadSchema = z.object({
158
+ deviceId: z.uuid(),
159
+ /** Correlates back to the originating `docker.action` (echoed verbatim). */
160
+ opId: z.string().max(64),
161
+ line: z.string().max(2000)
162
+ });
163
+
164
+ /** Final outcome of a `docker.action`. */
165
+ export const AGENT_DOCKER_DONE = 'docker.done' as const;
166
+
167
+ export const agentDockerDonePayloadSchema = z.object({
168
+ deviceId: z.uuid(),
169
+ opId: z.string().max(64),
170
+ action: dockerActionSchema,
171
+ ok: z.boolean(),
172
+ error: z.string().max(500).optional()
173
+ });
174
+
132
175
  /** Agent's reply to `agent.service`: outcome of a persistence/privilege change. */
133
176
  export const AGENT_SERVICE_RESULT = 'agent.serviceResult' as const;
134
177
 
@@ -448,6 +491,22 @@ export const agentClientMessageSchema = z.discriminatedUnion('command', [
448
491
  command: z.literal(AGENT_POWER_RESULT),
449
492
  payload: agentPowerResultPayloadSchema
450
493
  }),
494
+ z.object({
495
+ command: z.literal(AGENT_DOCKER_INVENTORY_RESULT),
496
+ payload: agentDockerInventoryResultPayloadSchema
497
+ }),
498
+ z.object({
499
+ command: z.literal(AGENT_DOCKER_STATS_RESULT),
500
+ payload: agentDockerStatsResultPayloadSchema
501
+ }),
502
+ z.object({
503
+ command: z.literal(AGENT_DOCKER_PROGRESS),
504
+ payload: agentDockerProgressPayloadSchema
505
+ }),
506
+ z.object({
507
+ command: z.literal(AGENT_DOCKER_DONE),
508
+ payload: agentDockerDonePayloadSchema
509
+ }),
451
510
  z.object({
452
511
  command: z.literal(AGENT_LOG_SOURCES_RESULT),
453
512
  payload: agentLogSourcesResultPayloadSchema
@@ -574,6 +633,28 @@ export const AGENT_PKG_UPGRADE = 'pkg.upgrade' as const;
574
633
  export const agentPkgUpgradePayloadSchema = z.object({ manager: packageManagerIdSchema });
575
634
  export type AgentPkgUpgradePayload = z.infer<typeof agentPkgUpgradePayloadSchema>;
576
635
 
636
+ /** Ask the agent for its container inventory (`docker.inventoryResult`). */
637
+ export const AGENT_DOCKER_INVENTORY = 'docker.inventory' as const;
638
+
639
+ /** Ask the agent for a one-shot resource sample of the running containers. */
640
+ export const AGENT_DOCKER_STATS = 'docker.stats' as const;
641
+
642
+ /**
643
+ * Ask the agent to act on a container, image, volume or network. `opId`
644
+ * correlates the streamed output and the outcome back to this order. `target`
645
+ * is the object's own identifier, and it is the ONLY caller-supplied value that
646
+ * reaches a command line; the untargeted actions (the prunes) carry none.
647
+ */
648
+ export const AGENT_DOCKER_ACTION = 'docker.action' as const;
649
+
650
+ export const agentDockerActionPayloadSchema = z.object({
651
+ opId: z.string().min(1).max(64),
652
+ engine: containerEngineSchema,
653
+ action: dockerActionSchema,
654
+ target: z.string().max(512).nullable()
655
+ });
656
+ export type AgentDockerActionPayload = z.infer<typeof agentDockerActionPayloadSchema>;
657
+
577
658
  /** Ask the agent to perform a system power action (`agent.powerResult` reports the outcome). */
578
659
  export const AGENT_POWER = 'agent.power' as const;
579
660
 
@@ -943,6 +1024,18 @@ export const agentServerMessageSchema = z.discriminatedUnion('command', [
943
1024
  command: z.literal(AGENT_PKG_UPGRADE),
944
1025
  payload: agentPkgUpgradePayloadSchema
945
1026
  }),
1027
+ z.object({
1028
+ command: z.literal(AGENT_DOCKER_INVENTORY),
1029
+ payload: z.object({})
1030
+ }),
1031
+ z.object({
1032
+ command: z.literal(AGENT_DOCKER_STATS),
1033
+ payload: z.object({})
1034
+ }),
1035
+ z.object({
1036
+ command: z.literal(AGENT_DOCKER_ACTION),
1037
+ payload: agentDockerActionPayloadSchema
1038
+ }),
946
1039
  z.object({
947
1040
  command: z.literal(AGENT_POWER),
948
1041
  payload: agentPowerPayloadSchema
@@ -1043,6 +1136,11 @@ export const DEVICE_POWER_EVENT = 'device.powerResult' as const;
1043
1136
  * subscribers exactly like the power result.
1044
1137
  */
1045
1138
  export const DEVICE_SERVICE_EVENT = 'device.serviceResult' as const;
1139
+ /** Container inventory, live stats sample, and action progress/outcome. */
1140
+ export const DEVICE_DOCKER_INVENTORY_EVENT = 'device.dockerInventory' as const;
1141
+ export const DEVICE_DOCKER_STATS_EVENT = 'device.dockerStats' as const;
1142
+ export const DEVICE_DOCKER_PROGRESS_EVENT = 'device.dockerProgress' as const;
1143
+ export const DEVICE_DOCKER_DONE_EVENT = 'device.dockerDone' as const;
1046
1144
  /** Device log sources inventory + queried log lines, fanned to subscribers. */
1047
1145
  export const DEVICE_LOG_SOURCES_EVENT = 'device.logSources' as const;
1048
1146
  export const DEVICE_LOG_LINES_EVENT = 'device.logLines' as const;
@@ -1080,6 +1178,17 @@ export const packageProgressPushSchema = agentPkgProgressPayloadSchema;
1080
1178
  export const packageDonePushSchema = agentPkgDonePayloadSchema;
1081
1179
  export const devicePowerPushSchema = agentPowerResultPayloadSchema;
1082
1180
  export const deviceServicePushSchema = agentServiceResultPayloadSchema;
1181
+ /**
1182
+ * L'inventaire, enrichi par le serveur de ce que l'agent ignore : l'action
1183
+ * longue déjà en cours sur cet appareil. Sans ce champ, un second écran
1184
+ * relancerait le même `prune`.
1185
+ */
1186
+ export const deviceDockerInventoryPushSchema = agentDockerInventoryResultPayloadSchema.extend({
1187
+ running: z.string().max(64).nullable().default(null)
1188
+ });
1189
+ export const deviceDockerStatsPushSchema = agentDockerStatsResultPayloadSchema;
1190
+ export const deviceDockerProgressPushSchema = agentDockerProgressPayloadSchema;
1191
+ export const deviceDockerDonePushSchema = agentDockerDonePayloadSchema;
1083
1192
  export const deviceLogSourcesPushSchema = agentLogSourcesResultPayloadSchema;
1084
1193
  export const deviceLogLinesPushSchema = agentLogLinesPayloadSchema;
1085
1194
  export const deviceTermOutputPushSchema = agentTermOutputPayloadSchema;
@@ -1105,6 +1214,11 @@ export type CloudSyncProgressPush = z.infer<typeof cloudSyncProgressPushSchema>;
1105
1214
  export type CloudSyncStatePush = z.infer<typeof cloudSyncStatePushSchema>;
1106
1215
  export type CloudSyncChunkPush = z.infer<typeof cloudSyncChunkPushSchema>;
1107
1216
 
1217
+ export type DeviceDockerInventoryPush = z.infer<typeof deviceDockerInventoryPushSchema>;
1218
+ export type DeviceDockerStatsPush = z.infer<typeof deviceDockerStatsPushSchema>;
1219
+ export type DeviceDockerProgressPush = z.infer<typeof deviceDockerProgressPushSchema>;
1220
+ export type DeviceDockerDonePush = z.infer<typeof deviceDockerDonePushSchema>;
1221
+
1108
1222
  export type PackageListPush = z.infer<typeof packageListPushSchema>;
1109
1223
  export type PackageStartedPush = z.infer<typeof packageStartedPushSchema>;
1110
1224
  export type PackageProgressPush = z.infer<typeof packageProgressPushSchema>;
@@ -66,10 +66,25 @@ declare module 'deveye-sdk-client' {
66
66
  value: T;
67
67
  options: readonly { value: T; label: string; title?: string }[];
68
68
  onChange: (value: T) => void;
69
+ /** Étire le groupe sur la ligne, chaque choix en prenant une part égale. */
70
+ fullWidth?: boolean;
69
71
  className?: string;
70
72
  'aria-label'?: string;
71
73
  disabled?: boolean;
72
74
  }): ReactNode;
75
+ /**
76
+ * Le bouton d'enregistrement d'un panneau de réglages : « Enregistrement… »
77
+ * pendant l'aller-retour, « Enregistré » quelques secondes, puis l'intitulé
78
+ * de départ. Les erreurs restent au panneau, elles ne s'effacent pas seules.
79
+ */
80
+ export const SaveButton: ComponentType<{
81
+ onSave: () => Promise<unknown> | unknown;
82
+ children?: string;
83
+ disabled?: boolean;
84
+ variant?: 'primary' | 'secondary' | 'danger' | 'ghost';
85
+ icon?: string;
86
+ title?: string;
87
+ }>;
73
88
  export const Dialog: ComponentType<{
74
89
  open: boolean;
75
90
  onClose: () => void;
@@ -202,6 +217,13 @@ declare module 'deveye-sdk-client' {
202
217
  /** Shown to a caller without write access. */
203
218
  readOnlyHint: string;
204
219
  }>;
220
+ /**
221
+ * A read-only refusal inside a settings panel: one silhouette for every
222
+ * feature, lock glyph included. Pass the sentence as children, nothing
223
+ * else. What blocks for another reason (an archived device, an item that
224
+ * cannot be projected) keeps its own wording.
225
+ */
226
+ export const ReadOnlyNotice: ComponentType<{ children: ReactNode }>;
205
227
  /** The canonical settings row classes (channelRow, field, sectionHint...). */
206
228
  export const settingsStyles: Readonly<Record<string, string>>;
207
229
  /** A plain count on a home card: a big number, a noun, a secondary line. */
package/src/sdk/client.ts CHANGED
@@ -48,6 +48,19 @@ export interface FeatureClient {
48
48
  Widget: ComponentType;
49
49
  /** The full view, opened when the card expands. */
50
50
  Full: ComponentType<FeatureViewProps>;
51
+ /**
52
+ * The vignette shown on your card in the home grid's add market and on
53
+ * your "About" sheet. Without one, the host draws a neutral module mark:
54
+ * a card with no vignette among cards that have one reads as broken.
55
+ *
56
+ * Return SVG CHILDREN, not an `<svg>`: the host supplies the frame, a
57
+ * 160 x 90 viewBox with the useful area at x 16 to 144 centred on y 45, so
58
+ * every vignette shares one set of margins. Colour with the theme's CSS
59
+ * variables (`var(--accent)`, `var(--text-muted)`), never a literal: an
60
+ * accent colour is per-workspace, and a hardcoded one ignores the theme.
61
+ * Draw the SHAPE of your screen, not your icon enlarged.
62
+ */
63
+ Art?: ComponentType;
51
64
  /**
52
65
  * Panels for the manifest's settings tabs that need one: `'general'`,
53
66
  * `'sources'`, `'encryption'`, and any custom tab id. Generic tabs
@@ -41,7 +41,12 @@ test('validateManifest rejects the classic mistakes', () => {
41
41
 
42
42
  test('externalDescriptorOf projects the identity fields only, and refuses a native id', () => {
43
43
  assert.deepEqual(
44
- externalDescriptorOf({ ...base, itemNoun: 'thing', sources: { hint: 'keys' } }),
44
+ externalDescriptorOf({
45
+ ...base,
46
+ itemNoun: 'thing',
47
+ itemNounGender: 'f',
48
+ sources: { hint: 'keys' }
49
+ }),
45
50
  {
46
51
  id: 'x-demo',
47
52
  label: 'Demo',
@@ -50,6 +55,7 @@ test('externalDescriptorOf projects the identity fields only, and refuses a nati
50
55
  notifies: false,
51
56
  hasItems: false,
52
57
  itemNoun: 'thing',
58
+ itemNounGender: 'f',
53
59
  sources: { hint: 'keys' },
54
60
  shareTier: 'never'
55
61
  }
@@ -60,7 +60,7 @@ export type ExtraPermissionSpec =
60
60
  };
61
61
 
62
62
  /** Hard cap on `extraPermissions`: keeps role editors legible. */
63
- export const MAX_EXTRA_PERMISSIONS = 4;
63
+ export const MAX_EXTRA_PERMISSIONS = 10;
64
64
 
65
65
  const EXTRA_KEY_PATTERN = /^[a-z][a-zA-Z0-9]{1,23}$/;
66
66
 
@@ -99,7 +99,15 @@ export type NativeCapability =
99
99
  * Declared, because opening a door is the one thing a module must not do
100
100
  * quietly. See `FeatureService.publicRoutes`.
101
101
  */
102
- | 'routes.public';
102
+ | 'routes.public'
103
+ /**
104
+ * Push frames of your own to the workspace's connected members
105
+ * (`ctx.live.publish`, `deps.live.publish`). The lane for state that must
106
+ * be seen AS it changes rather than re-fetched: a shared board, a cursor
107
+ * of your own. Declared, because it lets a module put bytes on someone
108
+ * else's socket without them asking. See `SdkLive.publish`.
109
+ */
110
+ | 'live.publish';
103
111
 
104
112
  /**
105
113
  * Settings tabs the shell can render for you.
@@ -123,6 +131,13 @@ export interface CustomTabRef {
123
131
  label: string;
124
132
  /** Icon class suffix; defaults to `settings`. */
125
133
  icon?: string;
134
+ /**
135
+ * Drop the tab entirely without write access, instead of rendering it
136
+ * read-only. For a tab holding nothing but gestures (Mail's cache
137
+ * rebuild): one that shows values stays visible and read-only, since the
138
+ * values are worth reading.
139
+ */
140
+ requiresWrite?: boolean;
126
141
  }
127
142
 
128
143
  const CUSTOM_TAB_PATTERN = /^[a-z][a-z0-9]{1,23}$/;
@@ -184,6 +199,12 @@ export interface FeatureManifest<Id extends FeatureId = FeatureId> {
184
199
  hasItems: boolean;
185
200
  /** Singular noun for item-scope screen titles. Required when `hasItems`. */
186
201
  itemNoun?: string;
202
+ /**
203
+ * Its gender, without which the French titles that precede it with a
204
+ * determiner cannot agree (« cette cible » against « ce dépôt »).
205
+ * Masculine by default.
206
+ */
207
+ itemNounGender?: 'm' | 'f';
187
208
  /** Feature-scope reusable settings (API keys, destinations). Opens the Sources tab. */
188
209
  sources?: { hint: string };
189
210
  /**
@@ -416,6 +437,7 @@ export function externalDescriptorOf(
416
437
  notifies: m.notifies,
417
438
  hasItems: m.hasItems,
418
439
  itemNoun: m.itemNoun,
440
+ itemNounGender: m.itemNounGender,
419
441
  sources: m.sources,
420
442
  shareTier: m.shareTier
421
443
  };
@@ -0,0 +1,51 @@
1
+ import assert from 'node:assert/strict';
2
+ import test from 'node:test';
3
+
4
+ import { isPublicIp, isSafePublicUrl } from './net';
5
+
6
+ test('isPublicIp: the private ranges of both families read as false', () => {
7
+ for (const ip of ['8.8.8.8', '1.1.1.1', '2001:4860:4860::8888']) {
8
+ assert.equal(isPublicIp(ip), true, ip);
9
+ }
10
+ for (const ip of [
11
+ '127.0.0.1',
12
+ '10.0.0.1',
13
+ '172.16.0.1',
14
+ '172.31.255.255',
15
+ '192.168.1.1',
16
+ '169.254.169.254',
17
+ '100.64.0.1',
18
+ '0.0.0.0',
19
+ '224.0.0.1',
20
+ '::1',
21
+ 'fd00::1',
22
+ 'fe80::1',
23
+ // IPv4-mapped: judged on the v4 part, not on the v6 prefix.
24
+ '::ffff:127.0.0.1',
25
+ 'not-an-ip'
26
+ ]) {
27
+ assert.equal(isPublicIp(ip), false, ip);
28
+ }
29
+ });
30
+
31
+ test('isSafePublicUrl: only public http(s) hosts, string or URL', () => {
32
+ assert.equal(isSafePublicUrl('https://github.com/owner/repo.git'), true);
33
+ assert.equal(isSafePublicUrl(new URL('http://example.com')), true);
34
+
35
+ for (const url of [
36
+ 'http://localhost:3000',
37
+ 'https://db.internal/x',
38
+ 'https://printer.local',
39
+ 'https://app.localhost',
40
+ 'http://192.168.1.10/admin',
41
+ 'http://[::1]:8080',
42
+ // Anything but http(s): a git `ext::` or a `file://` would run a
43
+ // command or read the server's disk.
44
+ 'file:///etc/passwd',
45
+ 'ext::sh -c whoami',
46
+ 'ssh://git@github.com/owner/repo.git',
47
+ 'not a url at all'
48
+ ]) {
49
+ assert.equal(isSafePublicUrl(url), false, url);
50
+ }
51
+ });
package/src/sdk/net.ts ADDED
@@ -0,0 +1,76 @@
1
+ /**
2
+ * The SSRF guard, in the published package.
3
+ *
4
+ * Any feature that follows a URL a member typed needs it, and a guard written
5
+ * twice is a guard that gets fixed once. It lives here rather than in the app
6
+ * because an external module has no import path into the app: without this, a
7
+ * third-party module either reimplements the ranges or ships no guard at all.
8
+ *
9
+ * Pure predicates, no I/O: a hostname is NOT resolved. DNS would change under
10
+ * the caller's feet between the check and the connection anyway, so the answer
11
+ * is about the URL, and a caller that must also bound the address it finally
12
+ * connects to has to say so at connection time.
13
+ */
14
+ import { isIP } from 'node:net';
15
+
16
+ /**
17
+ * Is this a public, routable IP address? Loopback, private ranges, link-local,
18
+ * CGNAT and multicast all read as false, in both families.
19
+ */
20
+ export function isPublicIp(raw: string): boolean {
21
+ const ip = raw.replace(/^\[|\]$/g, '').toLowerCase();
22
+ const v = isIP(ip);
23
+ if (v === 0) return false;
24
+
25
+ if (v === 4) return isPublicIpv4(ip);
26
+
27
+ // IPv4-mapped or compatible: judge the real v4 part.
28
+ const mapped = ip.match(/^::(?:ffff:)?(\d+\.\d+\.\d+\.\d+)$/);
29
+ if (mapped) return isPublicIpv4(mapped[1]);
30
+
31
+ if (ip === '::' || ip === '::1') return false;
32
+ // fc00::/7 (unique-local), fe80::/10 (link-local), ff00::/8 (multicast).
33
+ if (/^f[cd]/.test(ip)) return false;
34
+ if (/^fe[89ab]/.test(ip)) return false;
35
+ if (/^ff/.test(ip)) return false;
36
+ return true;
37
+ }
38
+
39
+ function isPublicIpv4(ip: string): boolean {
40
+ const o = ip.split('.').map(Number);
41
+ if (o.length !== 4 || o.some((n) => !Number.isInteger(n) || n < 0 || n > 255)) return false;
42
+ if (o[0] === 0 || o[0] === 10 || o[0] === 127) return false;
43
+ if (o[0] === 169 && o[1] === 254) return false; // link-local
44
+ if (o[0] === 172 && o[1] >= 16 && o[1] <= 31) return false;
45
+ if (o[0] === 192 && o[1] === 168) return false;
46
+ if (o[0] === 100 && o[1] >= 64 && o[1] <= 127) return false; // CGNAT
47
+ if (o[0] >= 224) return false; // multicast and reserved
48
+ return true;
49
+ }
50
+
51
+ /**
52
+ * May the server fetch this URL? Only public http(s) hosts, so a pasted
53
+ * address cannot probe the network the server sits in. Accepts a `URL` or the
54
+ * raw string a user typed, which may not parse at all.
55
+ */
56
+ export function isSafePublicUrl(input: URL | string): boolean {
57
+ let u: URL;
58
+ try {
59
+ u = typeof input === 'string' ? new URL(input) : input;
60
+ } catch {
61
+ return false;
62
+ }
63
+ if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
64
+ const h = u.hostname.toLowerCase();
65
+ if (
66
+ h === 'localhost' ||
67
+ h.endsWith('.local') ||
68
+ h.endsWith('.internal') ||
69
+ h.endsWith('.localhost')
70
+ ) {
71
+ return false;
72
+ }
73
+ const bare = h.replace(/^\[|\]$/g, '');
74
+ if (isIP(bare) !== 0) return isPublicIp(bare);
75
+ return true;
76
+ }