@daybook/feedback 1.4.3 → 1.6.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/README.md CHANGED
@@ -3,7 +3,65 @@
3
3
  In-app feedback for the web. The reporter points at what is wrong and says what happened; everything
4
4
  a triager needs is captured without asking them.
5
5
 
6
- 9 KB gzipped, no dependencies.
6
+ About 26 KB gzipped as a script tag. Its one dependency is `@daybook/core`, which has none.
7
+
8
+ It is a module of Daybook's SDK family for the web: the site starts `@daybook/core` once, with one key,
9
+ and the widget is `daybook.feedback`. Started by itself with `init({ ingestKey })`, the way before the
10
+ family, it works as it always has.
11
+
12
+ ## Start with Daybook
13
+
14
+ ```
15
+ npm install @daybook/core @daybook/feedback
16
+ ```
17
+
18
+ ```js
19
+ import { Daybook } from '@daybook/core'
20
+ import '@daybook/feedback' // registers itself on import
21
+
22
+ const daybook = await Daybook.initialize('dbk_…', {
23
+ feedback: { app: { version: '1.4.0' } },
24
+ })
25
+
26
+ daybook.identify(user.id, { email: user.email, name: user.name }) // at sign-in
27
+ daybook.reset() // at sign-out
28
+
29
+ daybook.feedback.open() // from your own "Report a problem"
30
+ ```
31
+
32
+ The widget is on the page once Daybook has started; `feedback: { autoStart: false }` keeps it off until
33
+ `daybook.feedback.start()`. `daybook.feedback` is the same object `init` answers, so everything below
34
+ is called on it, and every option below but `ingestKey` goes under `feedback`.
35
+
36
+ **The key** is the site's own, `dbk_…`: in Daybook, open the project's settings, find the site under
37
+ **App key** and issue one per environment. It is not a secret: it is in the page's source, and it grants
38
+ only what the widget does. It goes in the code where Daybook is started, never in server configuration.
39
+ The same key starts every Daybook module on the site.
40
+
41
+ **What turns feedback on for the site** is a web install for the same environment, in Feedback › Setup:
42
+ it holds the domains the widget may run on, who may report and how the widget looks. Without one the
43
+ widget does not appear and the console says `feedback_not_set_up`. Its own ingest key (`pmi_…`) is not
44
+ in the code any more.
45
+
46
+ **Who is reporting** is `daybook.identify`: the user's id is the report's `externalId`. Under verified
47
+ identity, pass the signature with `daybook.feedback.authenticate(signature)`; under sign-in with
48
+ Daybook, call `daybook.feedback.signIn()` from a click. Tracking consent does not turn feedback off: it
49
+ is a function of the site, not a measurement.
50
+
51
+ **By script tag**, one tag for every module:
52
+
53
+ ```html
54
+ <script src="https://daybook.team/sdk/v1/daybook.js" data-key="dbk_…" data-modules="feedback"></script>
55
+ <script>
56
+ daybook.identify(user.id, { email: user.email })
57
+ </script>
58
+ ```
59
+
60
+ `data-modules="analytics,feedback"` adds analytics with the same key. The attributes are in
61
+ [`@daybook/core`'s README](https://www.npmjs.com/package/@daybook/core).
62
+
63
+ The rest of this page first describes the widget started by itself, with its ingest key, which keeps
64
+ working.
7
65
 
8
66
  ## Install
9
67
 
@@ -243,8 +301,10 @@ three days later when the reporter has moved on.
243
301
  the whole answer.
244
302
 
245
303
  It obeys `redact` exactly as everything else does: field values are described rather than
246
- reproduced, and `data-daybook-private` subtrees are replaced by a marker. Script bodies are
247
- dropped, attributes and text are capped, and the whole thing truncates rather than growing.
304
+ reproduced, `data-daybook-private` subtrees are replaced by a marker, and credentials found in text
305
+ and attributes read `[masked: GitHub token]`. Whatever the reporter blurred is withheld as
306
+ `data-daybook-blurred`. Script bodies are dropped, attributes and text are capped, and the whole
307
+ thing truncates rather than growing.
248
308
 
249
309
  **What it does carry is the page's visible text**, because that is what the page is. On screens
250
310
  showing personal data, decide whether that belongs in a report — `dom: false` turns it off, and
@@ -261,6 +321,9 @@ three days later when the reporter has moved on.
261
321
  page is left exactly as it was — no dimming — because the screenshot is also the record of what
262
322
  the page looked like, and a report about a colour should not arrive with the colours changed.
263
323
 
324
+ Except where it must not show: private elements, credentials, and anything the reporter blurred
325
+ are covered before the frame is taken — see [Redaction](#redaction).
326
+
264
327
  `screenshots` decides what the composer offers, and takes three values:
265
328
 
266
329
  | Value | The composer |
@@ -328,12 +391,67 @@ already crossed the wire.
328
391
  - Query strings are stripped from every captured URL.
329
392
  - Emails, JWTs, bearer tokens and long digit runs are masked in console text.
330
393
  - Password fields and anything you mark `data-daybook-private` are blurred before a screenshot is taken.
394
+ - Credentials on the page are found and masked without anybody marking them (1.5) — below.
331
395
 
332
396
  ```html
333
397
  <div data-daybook-private>Card ending 4242</div>
334
398
  ```
335
399
 
336
- Turn it off with `redact: false` only if you are certain about what is on screen.
400
+ Turn it off with `redact: false` only if you are certain about what is on screen. It does not turn
401
+ off what the reporter blurs: that was their decision, made while looking at the page.
402
+
403
+ ### Credentials nobody marked
404
+
405
+ `data-daybook-private` covers what you foresaw. What nobody foresees is the settings screen that shows
406
+ a new API key once, a link whose query string still carries a token, a debug panel printing a JWT —
407
+ and the reporter, looking straight at it, rarely thinks of the key as part of the page they are
408
+ reporting. So the page's text, its attributes (links, `data-*`, `title`, a labelled `<meta>`), the
409
+ console lines, a pin's text and the page address are all read for credentials before anything is
410
+ sent. What is found becomes `[masked: GitHub token]` in the snapshot and a solid grey bar over
411
+ exactly those characters in the screenshot, and the report's `context.redaction` says how many.
412
+
413
+ Recognised on their own, because their prefix is not something prose contains for any other reason:
414
+
415
+ | | |
416
+ |---|---|
417
+ | Daybook API keys | `pmk_` and 64 hex characters |
418
+ | OpenAI, Anthropic | `sk-…`, `sk-proj-…`, `sk-ant-…` with a generated body |
419
+ | Stripe | `sk_live_…`, `sk_test_…`, `rk_live_…` — not the publishable `pk_` |
420
+ | GitHub | `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, `github_pat_` |
421
+ | Slack | `xoxb-`, `xoxa-`, `xoxp-`, `xoxr-`, `xoxs-` |
422
+ | AWS | access key ids, `AKIA…` and `ASIA…` |
423
+ | JWTs | `eyJ….eyJ….…` |
424
+ | Private keys | a `-----BEGIN … PRIVATE KEY-----` block |
425
+
426
+ Everything else needs two things together: a label right in front of it — `key`, `token`, `secret`,
427
+ `password`, `api`, `auth`, as part of a longer name too (`api_key=`, `"client_secret":`,
428
+ `X-Api-Key:`, a `<dt>API key</dt>` before the `<dd>`) — and a value that looks generated: `Bearer`
429
+ or `Basic` followed by one, or a long hex or base64 run.
430
+
431
+ **What is left alone matters as much.** A forty-character commit hash is not a secret, and neither is
432
+ a UUID — even after the word "key", because an idempotency key is a UUID. Neither is `key:
433
+ MyComponentHeaderTitle`, `const apiKey = process.env.API_KEY`, `sk-fading-circle` (SpinKit's CSS),
434
+ `Bearer YOUR_TOKEN_HERE`, or ordinary sentences about keys and tokens. A generated value is told
435
+ from a written one by measure, not by guess: random characters mix both cases and digits and seldom
436
+ run three lowercase letters together, and names do the opposite. Run over 300,000 lines of Daybook's
437
+ own front end, docs and backend, the rules found one thing — and it was a key.
438
+
439
+ Text painted into a canvas, an image of text, and the inside of another component's shadow root are
440
+ not read. A blur covers those.
441
+
442
+ ### What the reporter blurs
443
+
444
+ The composer offers **Blur something** beside *Add another pin*, and it is the same gesture: click an
445
+ element, or drag across an area — a corner of a chart, half a table. What a click would blur is shown
446
+ blurred under the pointer first, every blur stays on the page while the report is written, each is
447
+ listed in the panel with its own remove, and Esc backs out.
448
+
449
+ A blur applies to the screenshot exactly as the reporter saw it, and the element is blurred for the
450
+ frame the way a private one is. In the page snapshot the subtree is withheld as
451
+ `<section data-daybook-blurred>[withheld]</section>`; for an area, every element drawn wholly inside
452
+ it and every piece of text drawn under it. A pin on something blurred is sent without its text.
453
+
454
+ Nothing about a blur goes on the wire but a count: no selector, no text. It holds with `redact: false`.
337
455
 
338
456
  ## Offline
339
457
 
package/dist/blur.d.ts ADDED
@@ -0,0 +1,36 @@
1
+ /**
2
+ * What the reporter blurred, in the terms the captures need it. PM-T-0682.
3
+ *
4
+ * data-daybook-private is the developer's decision, made in advance and for every report. A blur is
5
+ * the reporter's, made at the moment of reporting and for this one: the colleague's name in the
6
+ * corner, the balance they would rather not send, the part of a dashboard that belongs to a client.
7
+ * Without it the only choice was between a screenshot of everything and no screenshot at all, and
8
+ * the second one is what people chose.
9
+ *
10
+ * It is the reporter's own decision, so it holds whether or not the host turned redaction off.
11
+ * `redact: false` says the developer trusts what is on their screens; it does not overrule somebody
12
+ * who has just pointed at a thing and said "not this".
13
+ */
14
+ /** A rectangle in viewport pixels. */
15
+ export interface Box {
16
+ left: number;
17
+ top: number;
18
+ width: number;
19
+ height: number;
20
+ }
21
+ /** Where the reporter's blurs are now. */
22
+ export interface Blurred {
23
+ /** Elements they clicked: covered in the screenshot and withheld whole from the snapshot. */
24
+ elements: Element[];
25
+ /**
26
+ * Areas they dragged across, and elements that could no longer be found by the time of capture.
27
+ * Covered in the screenshot; in the snapshot, whatever is drawn inside them is withheld.
28
+ */
29
+ regions: Box[];
30
+ }
31
+ /** The snapshot's marker for a subtree the reporter blurred, beside data-daybook-private. */
32
+ export declare const BLURRED_ATTRIBUTE = "data-daybook-blurred";
33
+ /** Whether two boxes share any area at all. Touching edges do not count. */
34
+ export declare function overlaps(a: Box, b: Box): boolean;
35
+ /** Whether `inner` lies inside `outer`, give or take the pixel a fractional layout rounds to. */
36
+ export declare function inside(inner: Box, outer: Box): boolean;
package/dist/blur.js ADDED
@@ -0,0 +1,26 @@
1
+ /**
2
+ * What the reporter blurred, in the terms the captures need it. PM-T-0682.
3
+ *
4
+ * data-daybook-private is the developer's decision, made in advance and for every report. A blur is
5
+ * the reporter's, made at the moment of reporting and for this one: the colleague's name in the
6
+ * corner, the balance they would rather not send, the part of a dashboard that belongs to a client.
7
+ * Without it the only choice was between a screenshot of everything and no screenshot at all, and
8
+ * the second one is what people chose.
9
+ *
10
+ * It is the reporter's own decision, so it holds whether or not the host turned redaction off.
11
+ * `redact: false` says the developer trusts what is on their screens; it does not overrule somebody
12
+ * who has just pointed at a thing and said "not this".
13
+ */
14
+ /** The snapshot's marker for a subtree the reporter blurred, beside data-daybook-private. */
15
+ export const BLURRED_ATTRIBUTE = 'data-daybook-blurred';
16
+ /** Whether two boxes share any area at all. Touching edges do not count. */
17
+ export function overlaps(a, b) {
18
+ return a.left < b.left + b.width && b.left < a.left + a.width
19
+ && a.top < b.top + b.height && b.top < a.top + a.height;
20
+ }
21
+ /** Whether `inner` lies inside `outer`, give or take the pixel a fractional layout rounds to. */
22
+ export function inside(inner, outer) {
23
+ return inner.left >= outer.left - 1 && inner.top >= outer.top - 1
24
+ && inner.left + inner.width <= outer.left + outer.width + 1
25
+ && inner.top + inner.height <= outer.top + outer.height + 1;
26
+ }
package/dist/client.d.ts CHANGED
@@ -48,6 +48,11 @@ export declare class IngestClient {
48
48
  signIn(): Promise<string>;
49
49
  /** Held in memory only, and only long enough to reach the next handshake. */
50
50
  private identityToken;
51
+ /**
52
+ * The header the key travels in. A site's own key (`dbk_…`, PM-R-0110) goes in the header every
53
+ * Daybook door reads it from; an ingest key (`pmi_…`) goes where it always has.
54
+ */
55
+ private keyHeader;
51
56
  private base;
52
57
  /**
53
58
  * Where the bytes actually go, given where the server said they go.
package/dist/client.js CHANGED
@@ -168,6 +168,13 @@ export class IngestClient {
168
168
  this.identityToken = identityToken;
169
169
  return identityToken;
170
170
  }
171
+ /**
172
+ * The header the key travels in. A site's own key (`dbk_…`, PM-R-0110) goes in the header every
173
+ * Daybook door reads it from; an ingest key (`pmi_…`) goes where it always has.
174
+ */
175
+ keyHeader() {
176
+ return this.ingestKey.startsWith('dbk_') ? 'X-Daybook-Key' : 'X-Ingest-Key';
177
+ }
171
178
  base() {
172
179
  return this.apiUrl.replace(/\/$/, '');
173
180
  }
@@ -215,7 +222,7 @@ export class IngestClient {
215
222
  post(path, body) {
216
223
  const headers = {
217
224
  'Content-Type': 'application/json',
218
- 'X-Ingest-Key': this.ingestKey,
225
+ [this.keyHeader()]: this.ingestKey,
219
226
  };
220
227
  // Only when there is one. A report without a session is still legal — anonymous reporting is
221
228
  // the whole point on a public site — and it simply arrives unattributed.
@@ -237,7 +244,7 @@ export class IngestClient {
237
244
  'Content-Type': ticket.contentType,
238
245
  // The upload goes to our API now rather than to storage, so it needs the key like every
239
246
  // other call. A presigned URL carried its own authorisation in the signature.
240
- 'X-Ingest-Key': this.ingestKey,
247
+ [this.keyHeader()]: this.ingestKey,
241
248
  },
242
249
  body: upload.blob,
243
250
  credentials: 'omit',
package/dist/context.d.ts CHANGED
@@ -1,4 +1,21 @@
1
1
  import type { Anchor, Breadcrumb } from './types.js';
2
+ /**
3
+ * What was taken out of a report before it was sent, as counts and never as content. PM-T-0682.
4
+ *
5
+ * Sent as `context.redaction`, in the one part of the wire contract that is open by design, so it
6
+ * needs no server change and a reader that does not know it ignores it. A triager who meets a grey
7
+ * bar in the screenshot or `[masked: GitHub token]` in the snapshot should know it was put there on
8
+ * purpose — and an assistant reading the report should not go looking for the missing key.
9
+ */
10
+ export interface Withheld {
11
+ /** How many things the reporter blurred. */
12
+ blurredByReporter: number;
13
+ /** How many credentials each capture found and masked. Only the captures that were taken. */
14
+ secretsMasked: {
15
+ screenshot?: number;
16
+ snapshot?: number;
17
+ };
18
+ }
2
19
  /**
3
20
  * The metadata a triager needs and a reporter should never be asked for.
4
21
  *
@@ -15,4 +32,11 @@ export declare function captureContext(options: {
15
32
  build?: string;
16
33
  environment?: string;
17
34
  };
35
+ /**
36
+ * Whether credentials are masked in the page text this carries — the title, the route, and each
37
+ * pin's text and page. A pin's text is eighty characters of whatever the reporter pointed at, and
38
+ * the thing they point at is sometimes the key they are complaining about.
39
+ */
40
+ redact?: boolean;
41
+ withheld?: Withheld;
18
42
  }): Record<string, unknown>;
package/dist/context.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { redactUrl } from './redact.js';
2
+ import { maskSecrets } from './secrets.js';
2
3
  import { SDK_NAME, SDK_VERSION } from './version.js';
3
4
  /**
4
5
  * The metadata a triager needs and a reporter should never be asked for.
@@ -9,12 +10,13 @@ import { SDK_NAME, SDK_VERSION } from './version.js';
9
10
  * on. All of it is available for free at the moment of capture.
10
11
  */
11
12
  export function captureContext(options) {
13
+ const mask = (text) => (options.redact ? maskSecrets(text).text : text);
12
14
  const context = {
13
15
  platform: 'web',
14
16
  // Pathname only. The predecessor stored it this way so a report survives moving between staging
15
17
  // and production, and that reasoning still holds.
16
- route: location.pathname,
17
- title: document.title.slice(0, 200),
18
+ route: mask(location.pathname),
19
+ title: mask(document.title.slice(0, 200)),
18
20
  locale: navigator.language,
19
21
  timezone: timezone(),
20
22
  viewport: {
@@ -37,7 +39,13 @@ export function captureContext(options) {
37
39
  * reading one pin keeps reading one pin (PM-R-0004 #11: the wire only ever grows). `anchors` is
38
40
  * all of them, in the order they were numbered, and is only sent when there is a list to send.
39
41
  */
40
- const anchors = options.anchors ?? [];
42
+ const anchors = (options.anchors ?? []).map(anchor => (options.redact
43
+ ? {
44
+ ...anchor,
45
+ elementText: anchor.elementText === null ? null : mask(anchor.elementText),
46
+ ...(anchor.page === undefined ? {} : { page: mask(anchor.page) }),
47
+ }
48
+ : anchor));
41
49
  if (anchors[0])
42
50
  context.anchor = anchors[0];
43
51
  if (anchors.length > 1)
@@ -45,6 +53,12 @@ export function captureContext(options) {
45
53
  if (options.breadcrumbs && options.breadcrumbs.length > 0) {
46
54
  context.breadcrumbs = options.breadcrumbs;
47
55
  }
56
+ // Only when something was withheld: a report with nothing taken out says so by not saying anything.
57
+ const withheld = options.withheld;
58
+ if (withheld && (withheld.blurredByReporter > 0
59
+ || Object.values(withheld.secretsMasked).some(count => (count ?? 0) > 0))) {
60
+ context.redaction = withheld;
61
+ }
48
62
  return context;
49
63
  }
50
64
  /**