@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 +122 -4
- package/dist/blur.d.ts +36 -0
- package/dist/blur.js +26 -0
- package/dist/client.d.ts +5 -0
- package/dist/client.js +9 -2
- package/dist/context.d.ts +24 -0
- package/dist/context.js +17 -3
- package/dist/feedback.js +55 -12
- package/dist/index.d.ts +12 -0
- package/dist/index.js +32 -3
- package/dist/module.d.ts +23 -0
- package/dist/module.js +53 -0
- package/dist/redact.d.ts +4 -0
- package/dist/redact.js +8 -3
- package/dist/screenshot.d.ts +37 -7
- package/dist/screenshot.js +137 -11
- package/dist/secrets.d.ts +86 -0
- package/dist/secrets.js +237 -0
- package/dist/snapshot.d.ts +14 -2
- package/dist/snapshot.js +193 -38
- package/dist/types.d.ts +18 -5
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/dist/widget.d.ts +52 -2
- package/dist/widget.js +341 -22
- package/package.json +12 -5
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
|
-
|
|
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,
|
|
247
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
/**
|