@ignite-ember/extension-bridge 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. package/LICENSE +202 -0
  2. package/NOTICE +5 -0
  3. package/README.md +364 -2
  4. package/dist/bridge.d.ts +37 -0
  5. package/dist/bridge.d.ts.map +1 -0
  6. package/dist/bridge.js +96 -0
  7. package/dist/bridge.js.map +1 -0
  8. package/dist/channel.d.ts +26 -0
  9. package/dist/channel.d.ts.map +1 -0
  10. package/dist/channel.js +36 -0
  11. package/dist/channel.js.map +1 -0
  12. package/dist/contract.d.ts +137 -0
  13. package/dist/contract.d.ts.map +1 -0
  14. package/dist/contract.js +9 -0
  15. package/dist/contract.js.map +1 -0
  16. package/dist/correlator.d.ts +37 -0
  17. package/dist/correlator.d.ts.map +1 -0
  18. package/dist/correlator.js +75 -0
  19. package/dist/correlator.js.map +1 -0
  20. package/dist/guestBridge.d.ts +63 -0
  21. package/dist/guestBridge.d.ts.map +1 -0
  22. package/dist/guestBridge.js +156 -0
  23. package/dist/guestBridge.js.map +1 -0
  24. package/dist/hostModel.d.ts +159 -0
  25. package/dist/hostModel.d.ts.map +1 -0
  26. package/dist/hostModel.generated.d.ts +2373 -0
  27. package/dist/hostModel.generated.d.ts.map +1 -0
  28. package/dist/hostModel.generated.js +1746 -0
  29. package/dist/hostModel.generated.js.map +1 -0
  30. package/dist/hostModel.js +172 -0
  31. package/dist/hostModel.js.map +1 -0
  32. package/dist/index.d.ts +12 -0
  33. package/dist/index.d.ts.map +1 -0
  34. package/dist/index.js +12 -0
  35. package/dist/index.js.map +1 -0
  36. package/dist/protocol.d.ts +348 -0
  37. package/dist/protocol.d.ts.map +1 -0
  38. package/dist/protocol.js +145 -0
  39. package/dist/protocol.js.map +1 -0
  40. package/dist/service.d.ts +168 -0
  41. package/dist/service.d.ts.map +1 -0
  42. package/dist/service.js +196 -0
  43. package/dist/service.js.map +1 -0
  44. package/dist/signals.d.ts +21 -0
  45. package/dist/signals.d.ts.map +1 -0
  46. package/dist/signals.js +52 -0
  47. package/dist/signals.js.map +1 -0
  48. package/dist/tokens.d.ts +101 -0
  49. package/dist/tokens.d.ts.map +1 -0
  50. package/dist/tokens.js +164 -0
  51. package/dist/tokens.js.map +1 -0
  52. package/dist/watchers.d.ts +12 -0
  53. package/dist/watchers.d.ts.map +1 -0
  54. package/dist/watchers.js +18 -0
  55. package/dist/watchers.js.map +1 -0
  56. package/package.json +53 -4
  57. package/src/bridge.ts +116 -0
  58. package/src/channel.ts +48 -0
  59. package/src/contract.ts +157 -0
  60. package/src/correlator.ts +88 -0
  61. package/src/guestBridge.ts +261 -0
  62. package/src/hostModel.generated.ts +3155 -0
  63. package/src/hostModel.ts +213 -0
  64. package/src/index.ts +11 -0
  65. package/src/protocol.ts +485 -0
  66. package/src/service.ts +278 -0
  67. package/src/signals.ts +65 -0
  68. package/src/tokens.ts +171 -0
  69. package/src/watchers.ts +18 -0
@@ -0,0 +1,485 @@
1
+ /**
2
+ * What crosses the gap between the host app and an extension's frame.
3
+ *
4
+ * One envelope type, versioned, with the host and the guest reading
5
+ * the same definition. The guest half of this file is the part that
6
+ * becomes a published package when somebody outside this repository
7
+ * writes an extension; until then both sides import it from here, so
8
+ * there is one description of the wire rather than two that agree
9
+ * until they don't.
10
+ *
11
+ * The frame is the untrusted party. Everything the host accepts from
12
+ * it is checked — the origin it came from, the window it came from,
13
+ * the nonce it was issued, and whether the method is one this
14
+ * extension was granted. None of those checks live in the guest.
15
+ */
16
+
17
+ /** Bumped only for a change the other side cannot ignore. */
18
+ export const BRIDGE_VERSION = 1;
19
+
20
+ /**
21
+ * Where inside an extension the user is: a deep link, replayed from
22
+ * `location`. Its keys are the extension's own, which is why the bridge
23
+ * cannot name them; an extension names them through `connect<P>()`.
24
+ */
25
+ export type LaunchParams = { readonly [key: string]: unknown };
26
+
27
+ /**
28
+ * How an extension is set up: `contributes.settings`, as an
29
+ * administrator left it. Keyed by the setting names the extension's
30
+ * manifest declares; an extension names them through `connect<P, S>()`.
31
+ */
32
+ export type ExtensionSettings = { readonly [setting: string]: unknown };
33
+
34
+ /** A backend RPC's arguments, by name, as its schema defines them. */
35
+ export type RpcArgs = { readonly [name: string]: unknown };
36
+
37
+ /** Where the user is, in strings, for the host to fold into its URL. */
38
+ export type LocationState = { readonly [key: string]: string };
39
+
40
+ /** Host → guest, once, before anything else is accepted. */
41
+ export interface HelloMessage {
42
+ /** The wire's version: the same constant on both sides. */
43
+ igni: typeof BRIDGE_VERSION;
44
+ /** Which message this is. */
45
+ kind: "hello";
46
+ /** Issued per frame, per session. Every guest message must carry it. */
47
+ nonce: string;
48
+ /** The extension this frame is, so a guest can label its own logs. */
49
+ extensionId: string;
50
+ /** Opaque per-extension launch parameters, from the host. */
51
+ params: LaunchParams;
52
+ /**
53
+ * What `contributes.settings` is configured to, as an
54
+ * administrator left it.
55
+ *
56
+ * Separate from `params` on purpose. `params` is where you are —
57
+ * a deep link, replayed from `location`. This is how you are set
58
+ * up. Merging them would mean a setting called `doc` and a link
59
+ * carrying `?doc=` were the same key, and whichever the host
60
+ * wrote last would win silently.
61
+ *
62
+ * Sent in `hello` and nowhere else: a change applies at the next
63
+ * mount. Reconfiguring a frame mid-render is a harder promise
64
+ * than it is worth until somebody asks for it, and the host's
65
+ * `set_extension_settings` says the same thing. Empty when
66
+ * nothing is configured.
67
+ *
68
+ * Optional on the wire: it was added after the envelope shipped,
69
+ * and a guest built against this version may be framed by a host
70
+ * that predates it. Missing reads as empty.
71
+ */
72
+ settings?: ExtensionSettings;
73
+ /**
74
+ * The extension's own service, as its page reaches it
75
+ * (`bridge.service.url`) — the one origin beyond declared egress its
76
+ * frame's `connect-src` admits. Null: it has none. Optional on the
77
+ * wire for the same reason `settings` is; missing reads as null.
78
+ */
79
+ serviceUrl?: string | null;
80
+ /** `"light"` or `"dark"`, following the host. */
81
+ theme: string;
82
+ /**
83
+ * The published design tokens, as the host currently computes them.
84
+ *
85
+ * Sent rather than fetched: the guest is a different origin and its
86
+ * own CSP refuses a cross-origin stylesheet. Sent rather than
87
+ * baked into the guest's package, because a copy of a theme defined
88
+ * across forty-five blocks drifts within a release.
89
+ */
90
+ tokens: Record<string, string>;
91
+ }
92
+
93
+ /** Host → guest, whenever the host's theme changes. */
94
+ export interface ThemeMessage {
95
+ /** The wire's version: the same constant on both sides. */
96
+ igni: typeof BRIDGE_VERSION;
97
+ /** Which message this is. */
98
+ kind: "theme";
99
+ /** `"light"` or `"dark"`, following the host. */
100
+ theme: string;
101
+ /** The published design tokens, as the host currently computes them. */
102
+ tokens: Record<string, string>;
103
+ }
104
+
105
+ /**
106
+ * Host → guest: the launch parameters changed under a mounted frame.
107
+ *
108
+ * `params` used to arrive exactly once, inside `hello`, and there
109
+ * was no way to send new ones. That is the difference between a
110
+ * widget and a page: a page can be linked to, and a link that
111
+ * resolves while the frame is already mounted had nowhere to land.
112
+ * The host would have had to tear the frame down and rebuild it,
113
+ * losing whatever state it held, to deliver a changed query string.
114
+ */
115
+ export interface ParamsMessage {
116
+ /** The wire's version: the same constant on both sides. */
117
+ igni: typeof BRIDGE_VERSION;
118
+ /** Which message this is. */
119
+ kind: "params";
120
+ /** Where inside the extension the user is now, changed under a mounted frame. */
121
+ params: LaunchParams;
122
+ }
123
+
124
+ /**
125
+ * Guest → host: where I am now.
126
+ *
127
+ * **Not a navigation.** `navigate` asks the host to go somewhere
128
+ * else; this says "I am still here, and here is now this". The host
129
+ * folds it into its own URL and replays it in the next `hello`, so a
130
+ * reload or a shared link comes back to the same place inside the
131
+ * extension.
132
+ *
133
+ * It exists because an extension has no other way to be addressable.
134
+ * It cannot write the address bar — `allow-top-navigation` is
135
+ * deliberately absent from the frame's sandbox — and it cannot
136
+ * persist anything, because each extension is served from an
137
+ * ephemeral port, a port is part of an origin, and so `localStorage`
138
+ * is wiped whenever the backend restarts.
139
+ *
140
+ * Strings only, and the host is free to cap or drop them: this ends
141
+ * up in a URL, and an extension that puts its whole state here would
142
+ * be writing an unbounded value into the host's address bar.
143
+ */
144
+ export interface LocationMessage {
145
+ /** The wire's version: the same constant on both sides. */
146
+ igni: typeof BRIDGE_VERSION;
147
+ /** Which message this is. */
148
+ kind: "location";
149
+ /** Issued per frame, per session. Every guest message must carry it. */
150
+ nonce: string;
151
+ /** Where the user is, in strings, for the host to fold into its URL. */
152
+ state: LocationState;
153
+ }
154
+
155
+ /** Guest → host: call a backend RPC. */
156
+ export interface CallMessage {
157
+ /** The wire's version: the same constant on both sides. */
158
+ igni: typeof BRIDGE_VERSION;
159
+ /** Which message this is. */
160
+ kind: "call";
161
+ /** Issued per frame, per session. Every guest message must carry it. */
162
+ nonce: string;
163
+ /** Correlates the reply. Generated by the guest; echoed, never trusted. */
164
+ id: string;
165
+ /** The backend method to call, as its schema names it. */
166
+ method: string;
167
+ /** The method's arguments, by name. */
168
+ args: RpcArgs;
169
+ }
170
+
171
+ /** Guest → host: ask the host app to go somewhere. */
172
+ export interface NavigateMessage {
173
+ /** The wire's version: the same constant on both sides. */
174
+ igni: typeof BRIDGE_VERSION;
175
+ /** Which message this is. */
176
+ kind: "navigate";
177
+ /** Issued per frame, per session. Every guest message must carry it. */
178
+ nonce: string;
179
+ /** A page the host knows. The host decides whether it exists. */
180
+ to: string;
181
+ }
182
+
183
+ /** Guest → host: this surface is finished. */
184
+ export interface CloseMessage {
185
+ /** The wire's version: the same constant on both sides. */
186
+ igni: typeof BRIDGE_VERSION;
187
+ /** Which message this is. */
188
+ kind: "close";
189
+ /** Issued per frame, per session. Every guest message must carry it. */
190
+ nonce: string;
191
+ }
192
+
193
+ /** Host → guest: the answer to one `call`. */
194
+ export interface ResultMessage {
195
+ /** The wire's version: the same constant on both sides. */
196
+ igni: typeof BRIDGE_VERSION;
197
+ /** Which message this is. */
198
+ kind: "result";
199
+ /** Correlates the reply. Generated by the guest; echoed, never trusted. */
200
+ id: string;
201
+ /** Whether the call succeeded. */
202
+ ok: boolean;
203
+ /** What the call answered with, when it succeeded. */
204
+ value?: unknown;
205
+ /** Present when `ok` is false. Always a sentence, never an object. */
206
+ error?: string;
207
+ }
208
+
209
+ /**
210
+ * Guest → host: one request to the host object model (`bridge.host…`).
211
+ *
212
+ * The host side of the bridge forwards it to the backend with this
213
+ * extension as the caller and its own window as the page's home, and the
214
+ * backend checks it against the manifest's `permissions.host`. Nothing
215
+ * here is trusted.
216
+ */
217
+ export interface HostRequestMessage {
218
+ /** The wire's version: the same constant on both sides. */
219
+ igni: typeof BRIDGE_VERSION;
220
+ /** Which message this is. */
221
+ kind: "host";
222
+ /** Issued per frame, per session. Every guest message must carry it. */
223
+ nonce: string;
224
+ /** Correlates the reply. Generated by the guest; echoed, never trusted. */
225
+ id: string;
226
+ /** What to do: read a property, write one, call a method, subscribe, unsubscribe. */
227
+ op: "get" | "set" | "call" | "subscribe" | "unsubscribe";
228
+ /** `chat.processing`, `chat.post`; empty for subscribe. */
229
+ path: string;
230
+ /** A window other than this page's own, for `host.windows.ui(id)`. */
231
+ window?: string | null;
232
+ /** A session other than the one on screen, for `host.sessions.chat(id)`. */
233
+ session?: string | null;
234
+ /** The arguments of a call, by name. */
235
+ params?: Record<string, unknown>;
236
+ /** The value of a write. */
237
+ value?: unknown;
238
+ /** Signal wire names, for subscribe and unsubscribe. */
239
+ signals?: string[];
240
+ }
241
+
242
+ /**
243
+ * Guest → host: a token for this extension's own service
244
+ * (`bridge.service`).
245
+ *
246
+ * Carries no audience, on purpose: the host asks the backend as this
247
+ * frame's extension, and the backend answers for the service recorded
248
+ * on that extension's own origin. A page cannot ask for anybody
249
+ * else's.
250
+ */
251
+ export interface ServiceTokenMessage {
252
+ /** The wire's version: the same constant on both sides. */
253
+ igni: typeof BRIDGE_VERSION;
254
+ /** Which message this is. */
255
+ kind: "service-token";
256
+ /** Issued per frame, per session. Every guest message must carry it. */
257
+ nonce: string;
258
+ /** Correlates the reply. Generated by the guest; echoed, never trusted. */
259
+ id: string;
260
+ }
261
+
262
+ /** Host → guest: the answer to one `service-token`. */
263
+ export interface ServiceTokenReplyMessage {
264
+ /** The wire's version: the same constant on both sides. */
265
+ igni: typeof BRIDGE_VERSION;
266
+ /** Which message this is. */
267
+ kind: "service-token-reply";
268
+ /** Correlates the reply. Generated by the guest; echoed, never trusted. */
269
+ id: string;
270
+ /** Whether a token was issued. */
271
+ ok: boolean;
272
+ /** The bearer token, when `ok`. */
273
+ token?: string;
274
+ /** Seconds it has left, when `ok`. */
275
+ expiresIn?: number;
276
+ /** Why not — nobody signed in, no service. A sentence. */
277
+ error?: string;
278
+ }
279
+
280
+ /** Host → guest: the answer to one host-model request. */
281
+ export interface HostReplyMessage {
282
+ /** The wire's version: the same constant on both sides. */
283
+ igni: typeof BRIDGE_VERSION;
284
+ /** Which message this is. */
285
+ kind: "host-reply";
286
+ /** Correlates the reply. Generated by the guest; echoed, never trusted. */
287
+ id: string;
288
+ /** Whether the request succeeded. */
289
+ ok: boolean;
290
+ /** What the request answered with, when it succeeded. */
291
+ result?: unknown;
292
+ /** Why not, when it did not: the host's code and a sentence for a person. */
293
+ error?: { code: string; message: string };
294
+ }
295
+
296
+ /** Host → guest: a host-model signal this extension subscribed to. */
297
+ export interface HostSignalMessage {
298
+ /** The wire's version: the same constant on both sides. */
299
+ igni: typeof BRIDGE_VERSION;
300
+ /** Which message this is. */
301
+ kind: "signal";
302
+ /** The signal's wire name. */
303
+ signal: string;
304
+ /** What the signal carries. */
305
+ value: unknown;
306
+ }
307
+
308
+ const HOST_OPS = new Set(["get", "set", "call", "subscribe", "unsubscribe"]);
309
+
310
+ /**
311
+ * Anything the host says to a page.
312
+ *
313
+ * The whole vocabulary of the host's side of the wire, in one union:
314
+ * the greeting, the theme, the launch parameters, the answers to the
315
+ * page's calls, the signals it subscribed to, and the tokens for the
316
+ * extension's own service.
317
+ */
318
+ export type HostMessage =
319
+ | HelloMessage
320
+ | ThemeMessage
321
+ | ParamsMessage
322
+ | ResultMessage
323
+ | HostReplyMessage
324
+ | HostSignalMessage
325
+ | ServiceTokenReplyMessage;
326
+
327
+ /**
328
+ * Anything a page says to the host.
329
+ *
330
+ * The whole vocabulary of the guest's side of the wire: the calls it
331
+ * makes, where it wants to go, where it is, that it is finished, the
332
+ * host-model requests it makes, and the service token it hands back.
333
+ */
334
+ export type GuestMessage =
335
+ | CallMessage
336
+ | NavigateMessage
337
+ | LocationMessage
338
+ | CloseMessage
339
+ | HostRequestMessage
340
+ | ServiceTokenMessage;
341
+
342
+ /**
343
+ * Is this a message from a guest, shaped the way we require?
344
+ *
345
+ * Written as a narrowing guard rather than a schema check because the
346
+ * host has to answer this about `unknown` arriving from a frame, and
347
+ * the answer has to be "no" for everything that is not exactly right.
348
+ * A message that fails here is dropped without a reply: a guest that
349
+ * can tell malformed from unauthorised has learned something.
350
+ *
351
+ * @param data — the message as it arrived, in whatever shape it is.
352
+ */
353
+ export function isGuestMessage(data: unknown): data is GuestMessage {
354
+ if (typeof data !== "object" || data === null) return false;
355
+ const m = data as Record<string, unknown>;
356
+ if (m.igni !== BRIDGE_VERSION) return false;
357
+ if (typeof m.nonce !== "string" || m.nonce.length === 0) return false;
358
+ switch (m.kind) {
359
+ case "call":
360
+ return (
361
+ typeof m.id === "string" &&
362
+ m.id.length > 0 &&
363
+ typeof m.method === "string" &&
364
+ m.method.length > 0 &&
365
+ typeof m.args === "object" &&
366
+ m.args !== null &&
367
+ !Array.isArray(m.args)
368
+ );
369
+ case "navigate":
370
+ return typeof m.to === "string" && m.to.length > 0;
371
+ case "location":
372
+ // Every value a string, checked rather than assumed: this goes
373
+ // into the host's own URL, and a guest is the untrusted party.
374
+ return (
375
+ typeof m.state === "object" &&
376
+ m.state !== null &&
377
+ !Array.isArray(m.state) &&
378
+ Object.values(m.state as Record<string, unknown>).every(
379
+ (value) => typeof value === "string",
380
+ )
381
+ );
382
+ case "close":
383
+ return true;
384
+ case "service-token":
385
+ return typeof m.id === "string" && m.id.length > 0;
386
+ case "host":
387
+ return (
388
+ typeof m.id === "string" &&
389
+ m.id.length > 0 &&
390
+ typeof m.op === "string" &&
391
+ HOST_OPS.has(m.op) &&
392
+ typeof m.path === "string" &&
393
+ (m.window === undefined ||
394
+ m.window === null ||
395
+ typeof m.window === "string") &&
396
+ (m.session === undefined ||
397
+ m.session === null ||
398
+ typeof m.session === "string") &&
399
+ (m.params === undefined ||
400
+ (typeof m.params === "object" &&
401
+ m.params !== null &&
402
+ !Array.isArray(m.params))) &&
403
+ (m.signals === undefined ||
404
+ (Array.isArray(m.signals) &&
405
+ m.signals.every((one) => typeof one === "string")))
406
+ );
407
+ default:
408
+ return false;
409
+ }
410
+ }
411
+
412
+ /**
413
+ * Is this a message from the host, shaped the way the guest requires?
414
+ *
415
+ * @param data — the message as it arrived, in whatever shape it is.
416
+ */
417
+ export function isHostMessage(data: unknown): data is HostMessage {
418
+ if (typeof data !== "object" || data === null) return false;
419
+ const m = data as Record<string, unknown>;
420
+ if (m.igni !== BRIDGE_VERSION) return false;
421
+ switch (m.kind) {
422
+ case "hello":
423
+ return (
424
+ typeof m.nonce === "string" &&
425
+ typeof m.extensionId === "string" &&
426
+ typeof m.theme === "string" &&
427
+ typeof m.params === "object" &&
428
+ m.params !== null &&
429
+ (m.settings === undefined || (typeof m.settings === "object" && m.settings !== null)) &&
430
+ (m.serviceUrl === undefined || m.serviceUrl === null || typeof m.serviceUrl === "string") &&
431
+ typeof m.tokens === "object" &&
432
+ m.tokens !== null
433
+ );
434
+ case "theme":
435
+ return (
436
+ typeof m.theme === "string" &&
437
+ typeof m.tokens === "object" &&
438
+ m.tokens !== null
439
+ );
440
+ case "params":
441
+ return (
442
+ typeof m.params === "object" &&
443
+ m.params !== null &&
444
+ !Array.isArray(m.params)
445
+ );
446
+ case "result":
447
+ return typeof m.id === "string" && typeof m.ok === "boolean";
448
+ case "host-reply":
449
+ return typeof m.id === "string" && typeof m.ok === "boolean";
450
+ case "service-token-reply":
451
+ return (
452
+ typeof m.id === "string" &&
453
+ typeof m.ok === "boolean" &&
454
+ (m.token === undefined || typeof m.token === "string") &&
455
+ (m.expiresIn === undefined || typeof m.expiresIn === "number")
456
+ );
457
+ case "signal":
458
+ return typeof m.signal === "string" && m.signal.length > 0;
459
+ default:
460
+ return false;
461
+ }
462
+ }
463
+
464
+ /**
465
+ * May this extension call this method?
466
+ *
467
+ * Exact names, or a `*`-suffixed prefix. No regular expressions and no
468
+ * `*` anywhere but the end: a permission list is read by whoever
469
+ * approves an install, and a pattern language it cannot be read in is
470
+ * a permission nobody actually granted.
471
+ *
472
+ * @param method — the method the extension wants to call.
473
+ * @param allow — the methods it was granted, as exact names or as
474
+ * `*`-suffixed prefixes.
475
+ */
476
+ export function methodAllowed(
477
+ method: string,
478
+ allow: readonly string[],
479
+ ): boolean {
480
+ return allow.some((pattern) =>
481
+ pattern.endsWith("*")
482
+ ? method.startsWith(pattern.slice(0, -1))
483
+ : method === pattern,
484
+ );
485
+ }