@deveye/types 0.17.2 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@deveye/types",
3
- "version": "0.17.2",
3
+ "version": "0.18.0",
4
4
  "description": "Shared contracts (types + zod schemas) for DevEye apps",
5
5
  "main": "src/index.ts",
6
6
  "types": "src/index.ts",
@@ -0,0 +1,159 @@
1
+ import { z } from 'zod';
2
+
3
+ /**
4
+ * User-submitted feedback: a free-form remark, or a bug report carrying the
5
+ * technical snapshot the client assembled at submit time.
6
+ *
7
+ * Stored in the clear, unlike feature data. The reader is the global admin, not
8
+ * the author: sealing a report with the author's key would make it unreadable
9
+ * by the only person meant to act on it.
10
+ */
11
+
12
+ /** What a report claims to be. Only `bug` carries a snapshot. */
13
+ export const feedbackKindSchema = z.enum(['general', 'bug']);
14
+ export type FeedbackKind = z.infer<typeof feedbackKindSchema>;
15
+
16
+ /** Where a report stands in triage. `new` until an admin touches it. */
17
+ export const feedbackStatusSchema = z.enum(['new', 'open', 'done']);
18
+ export type FeedbackStatus = z.infer<typeof feedbackStatusSchema>;
19
+
20
+ export const FEEDBACK_MESSAGE_MAX = 4000;
21
+
22
+ /**
23
+ * Ring sizes the client keeps in memory. Small on purpose: what precedes a bug
24
+ * by more than a handful of steps rarely explains it, and every entry travels.
25
+ */
26
+ export const FEEDBACK_REQUESTS_KEPT = 30;
27
+ export const FEEDBACK_ERRORS_KEPT = 10;
28
+ export const FEEDBACK_VIEWS_KEPT = 10;
29
+
30
+ /**
31
+ * One request the client saw go by. Neither its body nor its response: only
32
+ * enough to retrace a sequence. Bodies would carry passwords, decrypted content
33
+ * and secrets into a report anyone with the admin role can read.
34
+ */
35
+ export const feedbackRequestTraceSchema = z.object({
36
+ /** Milliseconds before the report was opened (0 = just now). */
37
+ ago: z.number().int().nonnegative(),
38
+ /** `ws` for a feature command, `http` for an auth route. */
39
+ channel: z.enum(['ws', 'http']),
40
+ /** Command name, or method and path. */
41
+ target: z.string().max(200),
42
+ durationMs: z.number().int().nonnegative(),
43
+ /** `ok`, or the protocol error code that came back. */
44
+ outcome: z.string().max(40)
45
+ });
46
+ export type FeedbackRequestTrace = z.infer<typeof feedbackRequestTraceSchema>;
47
+
48
+ /** An error nothing caught: a render crash, or a rejected promise. */
49
+ export const feedbackErrorTraceSchema = z.object({
50
+ ago: z.number().int().nonnegative(),
51
+ source: z.enum(['error', 'rejection']),
52
+ message: z.string().max(500),
53
+ /** File and position, when the browser gives them. */
54
+ origin: z.string().max(300).nullable(),
55
+ /** Truncated stack; null when the browser exposes none. */
56
+ stack: z.string().max(2000).nullable()
57
+ });
58
+ export type FeedbackErrorTrace = z.infer<typeof feedbackErrorTraceSchema>;
59
+
60
+ /** A view the user opened, in order: the shortest path to a reproduction. */
61
+ export const feedbackViewTraceSchema = z.object({
62
+ ago: z.number().int().nonnegative(),
63
+ /** View id (`logs`, `x-audit`, `device:…`), or `home` when it closed. */
64
+ view: z.string().max(64)
65
+ });
66
+ export type FeedbackViewTrace = z.infer<typeof feedbackViewTraceSchema>;
67
+
68
+ /**
69
+ * The technical report attached to a bug. Assembled client-side, so every field
70
+ * is what the browser was willing to say — `null` means "not exposed here", not
71
+ * "zero". The server never trusts it for identity: uid, IP and its own version
72
+ * are stamped server-side.
73
+ */
74
+ export const feedbackSnapshotSchema = z.object({
75
+ browser: z.object({
76
+ /** From `userAgentData` when present; the raw UA is always kept too. */
77
+ name: z.string().max(120).nullable(),
78
+ version: z.string().max(40).nullable(),
79
+ platform: z.string().max(80).nullable(),
80
+ mobile: z.boolean().nullable(),
81
+ userAgent: z.string().max(500),
82
+ language: z.string().max(40),
83
+ timezone: z.string().max(80),
84
+ cores: z.number().int().nonnegative().nullable(),
85
+ /** `navigator.deviceMemory`, in GiB. Chromium only. */
86
+ memoryGb: z.number().nonnegative().nullable(),
87
+ online: z.boolean()
88
+ }),
89
+ viewport: z.object({
90
+ width: z.number().int().nonnegative(),
91
+ height: z.number().int().nonnegative(),
92
+ pixelRatio: z.number().nonnegative(),
93
+ reducedMotion: z.boolean(),
94
+ colorScheme: z.enum(['light', 'dark'])
95
+ }),
96
+ app: z.object({
97
+ /**
98
+ * The bundle the tab is running. Compared to the server's own version
99
+ * on read: a tab left open across a deploy explains a class of bugs by
100
+ * itself.
101
+ */
102
+ clientVersion: z.string().max(40),
103
+ /** View open when the report was written; null on the dashboard. */
104
+ view: z.string().max(64).nullable(),
105
+ workspaceId: z.number().int().positive().nullable(),
106
+ /** WebSocket state (`open`, `closed`, `error`…). */
107
+ connection: z.string().max(24),
108
+ /** Seconds since this tab loaded. */
109
+ sessionAgeSeconds: z.number().int().nonnegative(),
110
+ /** Path only — the app carries no query but the active workspace. */
111
+ path: z.string().max(300)
112
+ }),
113
+ requests: z.array(feedbackRequestTraceSchema).max(FEEDBACK_REQUESTS_KEPT),
114
+ errors: z.array(feedbackErrorTraceSchema).max(FEEDBACK_ERRORS_KEPT),
115
+ views: z.array(feedbackViewTraceSchema).max(FEEDBACK_VIEWS_KEPT)
116
+ });
117
+ export type FeedbackSnapshot = z.infer<typeof feedbackSnapshotSchema>;
118
+
119
+ /**
120
+ * A report as served to the admin view. `username` and `handledByName` are
121
+ * resolved server-side from the ids (null when the account is gone).
122
+ */
123
+ export const feedbackEntrySchema = z.object({
124
+ id: z.number().int().positive(),
125
+ /** Submission time, unix epoch seconds. */
126
+ created: z.number().int().nonnegative(),
127
+ kind: feedbackKindSchema,
128
+ status: feedbackStatusSchema,
129
+ uid: z.number().int().nonnegative(),
130
+ username: z.string().nullable(),
131
+ /** Workspace open at submit time — context only, never a scope. */
132
+ workspaceId: z.number().int().positive().nullable(),
133
+ message: z.string(),
134
+ ip: z.string(),
135
+ /** Server version at submit time. */
136
+ appVersion: z.string(),
137
+ /** The bug report; null for a plain remark. */
138
+ snapshot: feedbackSnapshotSchema.nullable(),
139
+ handledAt: z.number().int().nonnegative().nullable(),
140
+ handledBy: z.number().int().positive().nullable(),
141
+ handledByName: z.string().nullable()
142
+ });
143
+ export type FeedbackEntry = z.infer<typeof feedbackEntrySchema>;
144
+
145
+ /** Raw `feedback` row as stored. `snapshot` is MySQL JSON (parsed by the driver). */
146
+ export interface FeedbackRow {
147
+ id: number;
148
+ uid: number;
149
+ workspace_id: number | null;
150
+ kind: string;
151
+ message: string;
152
+ snapshot: unknown;
153
+ status: string;
154
+ ip: string;
155
+ app_version: string;
156
+ created: number;
157
+ handled_at: number | null;
158
+ handled_by: number | null;
159
+ }
@@ -0,0 +1,86 @@
1
+ import { z } from 'zod';
2
+ import {
3
+ feedbackEntrySchema,
4
+ feedbackKindSchema,
5
+ feedbackSnapshotSchema,
6
+ feedbackStatusSchema,
7
+ FEEDBACK_MESSAGE_MAX
8
+ } from '../domain/feedback';
9
+
10
+ /** Upper bound on a single page of results (the server clamps to this). */
11
+ export const FEEDBACK_PAGE_MAX = 100;
12
+ export const FEEDBACK_PAGE_DEFAULT = 30;
13
+
14
+ /**
15
+ * Submit a report. Open to any signed-in account, and the only command here
16
+ * that is: reading feedback is an admin matter, writing one is not.
17
+ *
18
+ * The snapshot only makes sense on a `bug` — the server drops it otherwise, so
19
+ * a remark can never quietly carry a technical report.
20
+ */
21
+ export const feedbackSubmit = {
22
+ command: 'feedback.submit' as const,
23
+ input: z.object({
24
+ kind: feedbackKindSchema,
25
+ message: z.string().min(1).max(FEEDBACK_MESSAGE_MAX),
26
+ snapshot: feedbackSnapshotSchema.nullable().default(null)
27
+ }),
28
+ output: z.object({ id: z.number().int().positive() })
29
+ };
30
+
31
+ /**
32
+ * AND-combined filter for the admin list; every field is optional. All omitted
33
+ * → the unfiltered, newest-first feed.
34
+ */
35
+ export const feedbackFilterSchema = z.object({
36
+ kind: feedbackKindSchema.optional(),
37
+ status: feedbackStatusSchema.optional(),
38
+ /** Restrict to one author. */
39
+ uid: z.number().int().positive().optional(),
40
+ /** Case-insensitive substring over the message. */
41
+ search: z.string().max(200).optional()
42
+ });
43
+ export type FeedbackFilter = z.infer<typeof feedbackFilterSchema>;
44
+
45
+ /**
46
+ * Page through reports newest-first. Admin-only. `total` counts what matches
47
+ * the filter, ignoring paging; `hasMore` says whether a page follows.
48
+ */
49
+ export const feedbackList = {
50
+ command: 'feedback.list' as const,
51
+ input: feedbackFilterSchema.extend({
52
+ limit: z.number().int().positive().max(FEEDBACK_PAGE_MAX).optional(),
53
+ offset: z.number().int().nonnegative().optional()
54
+ }),
55
+ output: z.object({
56
+ entries: z.array(feedbackEntrySchema),
57
+ total: z.number().int().nonnegative(),
58
+ hasMore: z.boolean(),
59
+ /** How many are still untouched, whatever the filter: the badge count. */
60
+ pending: z.number().int().nonnegative()
61
+ })
62
+ };
63
+
64
+ /** Move a report through triage. Admin-only. */
65
+ export const feedbackSetStatus = {
66
+ command: 'feedback.setStatus' as const,
67
+ input: z.object({
68
+ id: z.number().int().positive(),
69
+ status: feedbackStatusSchema
70
+ }),
71
+ output: z.object({ entry: feedbackEntrySchema })
72
+ };
73
+
74
+ /** Drop a report for good. Admin-only. */
75
+ export const feedbackDelete = {
76
+ command: 'feedback.delete' as const,
77
+ input: z.object({ id: z.number().int().positive() }),
78
+ output: z.object({ deleted: z.literal(true) })
79
+ };
80
+
81
+ export const feedbackCommands = [
82
+ feedbackSubmit,
83
+ feedbackList,
84
+ feedbackSetStatus,
85
+ feedbackDelete
86
+ ] as const;
@@ -56,6 +56,53 @@ export const liveTypersPushSchema = z.object({
56
56
  });
57
57
  export type LiveTypersPush = z.infer<typeof liveTypersPushSchema>;
58
58
 
59
+ /**
60
+ * La bulle : le texte libre qu'un pair écrit à son curseur, à la Figma. Même
61
+ * voie rapide et même projection que les curseurs, mais un canal distinct du
62
+ * leur, parce que `liveCursorSchema` voyage aussi dans le roster, lequel part à
63
+ * tout l'espace alors que seul son `path` est tronqué par droits.
64
+ *
65
+ * `message: null` = plus de bulle. Le client n'émet jamais la chaîne vide.
66
+ */
67
+ export const LIVE_SAY_COMMAND = 'live.say' as const;
68
+
69
+ /**
70
+ * La voie rapide court-circuite le scope, l'audit et l'autorisation : cette
71
+ * borne est le seul rempart contre une trame abusive.
72
+ */
73
+ export const SAY_MAX_LENGTH = 140;
74
+
75
+ /**
76
+ * Et son plafond en lignes. La longueur seule ne borne pas la hauteur : cent
77
+ * retours à la ligne tiennent dans cent caractères, et la boîte descendrait
78
+ * sous le bas de l'écran. La saisie applique le même plafond.
79
+ */
80
+ export const SAY_MAX_LINES = 10;
81
+
82
+ const sayTextSchema = z
83
+ .string()
84
+ .max(SAY_MAX_LENGTH)
85
+ .refine((text) => text.split('\n').length <= SAY_MAX_LINES, {
86
+ message: `Au plus ${SAY_MAX_LINES} lignes`
87
+ });
88
+
89
+ export const liveSayFrameSchema = z.object({ message: sayTextSchema.nullable() });
90
+ export type LiveSayFrame = z.infer<typeof liveSayFrameSchema>;
91
+
92
+ /** Ce que disent les pairs situés au **même chemin exactement**. */
93
+ export const LIVE_SAYS_EVENT = 'live.says' as const;
94
+ export const liveSaysPushSchema = z.object({
95
+ workspaceId: z.number().int().positive(),
96
+ says: z.array(
97
+ z.object({
98
+ connId: z.string().min(1),
99
+ userId: z.number().int().positive(),
100
+ text: sayTextSchema
101
+ })
102
+ )
103
+ });
104
+ export type LiveSaysPush = z.infer<typeof liveSaysPushSchema>;
105
+
59
106
  /** Roster de la salle. Projeté par destinataire : les chemins y sont tronqués. */
60
107
  export const LIVE_PEERS_EVENT = 'live.peers' as const;
61
108
  export const livePeersPushSchema = z.object({
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { agentCommands } from './agent';
3
+ import { feedbackCommands } from './feedback';
3
4
  import { homeCommands } from './home';
4
5
  import { liveCommands } from './live';
5
6
  import { logsCommands } from './logs';
@@ -25,6 +26,7 @@ export const featureCommands = [
25
26
  ...twoFactorCommands,
26
27
  ...secrecyCommands,
27
28
  ...logsCommands,
29
+ ...feedbackCommands,
28
30
  ...homeCommands,
29
31
  ...notifyCommands,
30
32
  ...sharingCommands,
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
@@ -264,6 +264,29 @@ export {
264
264
  logSourceSchema
265
265
  } from './domain/logs';
266
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';
267
290
  export {
268
291
  DEVICE_LOG_LEVELS,
269
292
  DEVICE_LOG_OFFSET_MAX,
@@ -433,6 +456,8 @@ export {
433
456
  LIVE_CURSOR_COMMAND,
434
457
  LIVE_CURSORS_EVENT,
435
458
  LIVE_PEERS_EVENT,
459
+ LIVE_SAY_COMMAND,
460
+ LIVE_SAYS_EVENT,
436
461
  LIVE_TYPERS_EVENT,
437
462
  LIVE_TYPING_COMMAND,
438
463
  liveChangedPushSchema,
@@ -441,14 +466,20 @@ export {
441
466
  liveCursorsPushSchema,
442
467
  liveHere,
443
468
  livePeersPushSchema,
469
+ liveSayFrameSchema,
470
+ liveSaysPushSchema,
444
471
  liveTypersPushSchema,
445
- liveTypingFrameSchema
472
+ liveTypingFrameSchema,
473
+ SAY_MAX_LENGTH,
474
+ SAY_MAX_LINES
446
475
  } from './features/live';
447
476
  export type {
448
477
  LiveChangedPush,
449
478
  LiveCursorFrame,
450
479
  LiveCursorsPush,
451
480
  LivePeersPush,
481
+ LiveSayFrame,
482
+ LiveSaysPush,
452
483
  LiveTypersPush,
453
484
  LiveTypingFrame
454
485
  } from './features/live';
@@ -799,6 +830,17 @@ export {
799
830
  logsList
800
831
  } from './features/logs';
801
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';
802
844
 
803
845
  export {
804
846
  changePasswordRequestSchema,
@@ -217,6 +217,13 @@ declare module 'deveye-sdk-client' {
217
217
  /** Shown to a caller without write access. */
218
218
  readOnlyHint: string;
219
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 }>;
220
227
  /** The canonical settings row classes (channelRow, field, sectionHint...). */
221
228
  export const settingsStyles: Readonly<Record<string, string>>;
222
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
  }
@@ -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
+ }
package/src/sdk/server.ts CHANGED
@@ -29,6 +29,8 @@ import type {
29
29
  CloudSyncStatePush
30
30
  } from '../protocol/agent';
31
31
 
32
+ export { isPublicIp, isSafePublicUrl } from './net';
33
+
32
34
  /**
33
35
  * Server-side SDK surface: what a feature module's handlers and background
34
36
  * service are given, and nothing else.
@@ -543,6 +545,31 @@ export interface SdkLive {
543
545
  * this data.
544
546
  */
545
547
  changed(workspaceId: number, topics?: readonly string[]): void;
548
+ /**
549
+ * Pushes one frame to every member of `workspaceId` connected right now
550
+ * and holding `read` on YOUR feature (capability `'live.publish'`). The
551
+ * client reads it with `onServerEvent(event, schema, cb)`.
552
+ *
553
+ * The lane for what must be seen AS it happens rather than re-fetched: a
554
+ * cell someone just drew on a shared board. It carries the CHANGE, never
555
+ * the whole state, and it is best-effort by construction, so a client that
556
+ * missed one must be able to recover on its own (a periodic epoch, a
557
+ * re-fetch on reconnection) rather than assume every frame lands.
558
+ *
559
+ * `event` must start with `<manifest.id>.`, like a command; a `requestId`
560
+ * is never attached, so it can never be mistaken for a reply.
561
+ */
562
+ publish(workspaceId: number, event: string, payload: unknown): void;
563
+ }
564
+
565
+ /**
566
+ * The live engine seen from a HANDLER, where the workspace is the caller's.
567
+ * Invalidation stays declarative there (`mutates` on the command), so the only
568
+ * thing left to do by hand is the push lane.
569
+ */
570
+ export interface SdkContextLive {
571
+ /** {@link SdkLive.publish}, in the workspace of the call. */
572
+ publish(event: string, payload: unknown): void;
546
573
  }
547
574
 
548
575
  /** The whole fleet, sessionless (capability `'devices.read'`), for services. */
@@ -599,6 +626,8 @@ export interface SdkFeatureContext<Repo = unknown> {
599
626
  requestId: string;
600
627
  /** The server key derivations, the same `keys` a service gets. */
601
628
  keys: SdkServerKeys;
629
+ /** The push lane, in this workspace (capability `'live.publish'`). */
630
+ live: SdkContextLive;
602
631
  /**
603
632
  * Where DevEye lives, as URLs without a trailing slash: `app` is the
604
633
  * origin members use (`PUBLIC_ORIGIN`), `public` the one reachable
@@ -109,6 +109,8 @@ export interface RecordedCalls {
109
109
  agentRequests: { method: string; deviceId: string }[];
110
110
  /** Instants pinned through `telemetry.pinInstant`. */
111
111
  pinnedInstants: { deviceId: string; ts: number }[];
112
+ /** Frames pushed through `live.publish`, in order. */
113
+ livePublishes: { workspaceId: number; event: string; payload: unknown }[];
112
114
  }
113
115
 
114
116
  function recordingNotify(
@@ -306,7 +308,8 @@ export function createTestContext<Repo = undefined>(
306
308
  liveMessages: [],
307
309
  audits: [],
308
310
  agentRequests: [],
309
- pinnedInstants: []
311
+ pinnedInstants: [],
312
+ livePublishes: []
310
313
  };
311
314
  const isOwner = overrides.isOwner ?? true;
312
315
  const workspaceId = overrides.workspaceId ?? 1;
@@ -354,6 +357,11 @@ export function createTestContext<Repo = undefined>(
354
357
  openBytes: () => null,
355
358
  derive: fakeDerive
356
359
  },
360
+ live: {
361
+ publish(event, payload) {
362
+ recorded.livePublishes.push({ workspaceId, event, payload });
363
+ }
364
+ },
357
365
  items: {
358
366
  restrictions: () => Promise.resolve(restrictions),
359
367
  // The exact rule of the app's dispatcher: the feature first (a
@@ -472,6 +480,7 @@ export function createTestServiceDeps<Repo = undefined>(
472
480
  audits: [],
473
481
  agentRequests: [],
474
482
  pinnedInstants: [],
483
+ livePublishes: [],
475
484
  tickers: [],
476
485
  liveChanges: [],
477
486
  liveTopicChanges: []
@@ -535,6 +544,9 @@ export function createTestServiceDeps<Repo = undefined>(
535
544
  changed(workspaceId, topics) {
536
545
  recorded.liveChanges.push(workspaceId);
537
546
  if (topics) recorded.liveTopicChanges.push({ workspaceId, topics });
547
+ },
548
+ publish(workspaceId, event, payload) {
549
+ recorded.livePublishes.push({ workspaceId, event, payload });
538
550
  }
539
551
  },
540
552
  audit: (entry) => {