@amedia/user 1.3.2 → 1.4.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/CHANGELOG.md +12 -0
- package/README.md +96 -0
- package/index.d.ts +67 -2
- package/package.json +2 -2
- package/user.node.js +8 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# @amedia/user
|
|
2
2
|
|
|
3
|
+
## 1.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#1283](https://github.com/amedia/amedia-user-js/pull/1283) [`f57bc45`](https://github.com/amedia/amedia-user-js/commit/f57bc45e9f8e0286872b01fb17301273eef2f040) Thanks [@hennikul](https://github.com/hennikul)! - Add the aID Identity Verification actions: `requireVerification(requirement)`, `getVerificationUrl(requirement)` and `getVerificationOutcome()`. A site can now ask aID to prove a reader's identity — a verified session, or verified `name` / `birth_date` / `email` / `phone` — instead of being told to "send the reader through verification again" with no way to do it. `requireVerification` answers from data the library already holds when it can, and otherwise sends the reader to `/aid/verify`; it never reports a requirement as satisfied when it could not actually check it. Call it on the action rather than on render: most attributes cannot be re-checked in the browser on the way back, so a second call on a page load that already carries aID's answer throws `verification_already_answered` rather than navigating into a loop. Pass `{ force: true }` to send the reader again deliberately.
|
|
8
|
+
|
|
9
|
+
## 1.3.3
|
|
10
|
+
|
|
11
|
+
### Patch Changes
|
|
12
|
+
|
|
13
|
+
- [#1271](https://github.com/amedia/amedia-user-js/pull/1271) [`5bdf021`](https://github.com/amedia/amedia-user-js/commit/5bdf0219be602373b049d63489bde6aa4279727a) Thanks [@mortenlocka](https://github.com/mortenlocka)! - Dependency upgrades
|
|
14
|
+
|
|
3
15
|
## 1.3.2
|
|
4
16
|
|
|
5
17
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -344,6 +344,102 @@ page etc.
|
|
|
344
344
|
Polling for expected access. Will either return true when required access
|
|
345
345
|
features are attained, or TimeoutError.
|
|
346
346
|
|
|
347
|
+
### `requireVerification(requirement): Promise<{ satisfied: true }>`
|
|
348
|
+
|
|
349
|
+
Make sure the reader has been through aID Identity Verification before you let them do something that requires it.
|
|
350
|
+
|
|
351
|
+
A requirement names what must be proven. `attributes` are values that must be verified on the user (`name`,
|
|
352
|
+
`birth_date`, `email`, `phone`), and `session: true` means this browser session must itself carry a verification stamp.
|
|
353
|
+
At least one of the two is required. The two are different things: an attribute verification persists on the user, while
|
|
354
|
+
a session stamp dies with the session.
|
|
355
|
+
|
|
356
|
+
```ts
|
|
357
|
+
const { satisfied } = await requireVerification({
|
|
358
|
+
attributes: ['birth_date'],
|
|
359
|
+
session: true,
|
|
360
|
+
context: 'ung-activation',
|
|
361
|
+
});
|
|
362
|
+
// satisfied === true → nothing was missing, and nothing happened
|
|
363
|
+
// otherwise the browser has already left for aID Identity Verification
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
The promise resolves `{ satisfied: true }` only when the data @amedia/user already holds proves the requirement is met.
|
|
367
|
+
Otherwise the reader is sent to aID and the promise never resolves, because the page is leaving. That is not a wasted
|
|
368
|
+
trip: aID resolves the requirement itself and bounces straight back when it turns out to already be met, so the usual
|
|
369
|
+
cost of a navigation is one redirect, not a BankID prompt.
|
|
370
|
+
|
|
371
|
+
**Call it on the action, not on render.** Most requirements cannot be re-checked in the browser when the reader comes
|
|
372
|
+
back — a session's scopes reach `name_verified_at` and nothing else, so `birth_date` reads as unknown whether or not it
|
|
373
|
+
was just proven. A page that requires one on every render would therefore navigate, return, and navigate again. To make
|
|
374
|
+
that a bug report rather than an invisible redirect loop, a second call on a page load that already carries aID's answer
|
|
375
|
+
throws `verification_already_answered` instead of leaving:
|
|
376
|
+
|
|
377
|
+
```ts
|
|
378
|
+
const outcome = await getVerificationOutcome(); // read the answer, if there is one
|
|
379
|
+
// ...render from it, and put the call below behind the button that needs it
|
|
380
|
+
const { satisfied } = await requireVerification({ attributes: ['birth_date'] });
|
|
381
|
+
```
|
|
382
|
+
|
|
383
|
+
The guard is per page load, and it sits after the local check — a requirement @amedia/user can see is met still resolves
|
|
384
|
+
`{ satisfied: true }` on the way back. To send the reader again deliberately, a retry behind a button say, pass
|
|
385
|
+
`{ force: true }` as a second argument; a retry the reader asked for is not a loop.
|
|
386
|
+
|
|
387
|
+
Whatever the outcome says, gate anything that matters on the operation itself. The endpoint that needs the verification
|
|
388
|
+
answers authoritatively, and its answer cannot be typed into an address bar.
|
|
389
|
+
|
|
390
|
+
The rest of the requirement is optional:
|
|
391
|
+
|
|
392
|
+
| name | type | description |
|
|
393
|
+
| ------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
394
|
+
| sources | Array<'eid' \| 'otp'> | Which kinds of source are acceptable. Left out, the attribute implies it: contact details route to a one-time code, identity to an eID. Provider names are deliberately not part of this API. |
|
|
395
|
+
| maxAge | string \| number | Force a re-verify when the proof is older than this. Seconds, or a duration such as `'30m'`, `'2h'`, `'1d'`. |
|
|
396
|
+
| requestedUrl | string | Where the reader lands afterwards. Defaults to the current page. |
|
|
397
|
+
| context | string | Tracking, as on `goToLoginPage`. |
|
|
398
|
+
|
|
399
|
+
**Note**: what the browser can answer on its own is deliberately thin. Exactly two things are answered locally: the
|
|
400
|
+
session stamp, and `name` with no `sources` constraint. Everything else navigates rather than guess — a requirement
|
|
401
|
+
naming `birth_date`, `email` or `phone`, because their verification state is outside the scopes an on-site session
|
|
402
|
+
carries, **and any attribute constrained by `sources`**, because aID exposes an attribute's timestamp but not the source
|
|
403
|
+
that produced it. So `{ attributes: ['name'], sources: ['eid'] }` — proving a name came from an eID rather than from the
|
|
404
|
+
reader typing it — always takes the trip. If you need the answer _before_ rendering (to decide whether to offer a button
|
|
405
|
+
at all), ask your own backend, which can read those attributes with a machine token.
|
|
406
|
+
|
|
407
|
+
Throws `ValidationError` — before navigating anywhere — for a requirement aID would reject: one that asks for nothing,
|
|
408
|
+
names an unknown attribute or source, sets a `maxAge` that is not a duration or is longer than a year, or constrains an
|
|
409
|
+
attribute to `sources` that exclude the only source able to prove it (`{ attributes: ['email'], sources: ['eid'] }`). It
|
|
410
|
+
also throws when there is no top-level page to redirect — in a worker, or inside an iframe — because the promise
|
|
411
|
+
otherwise never settles and the caller would wait forever for a navigation that cannot happen.
|
|
412
|
+
|
|
413
|
+
### `getVerificationUrl(requirement): URL`
|
|
414
|
+
|
|
415
|
+
The same requirement as `requireVerification`, returned as a URL instead of navigated to, for a link or a button. It
|
|
416
|
+
performs no local evaluation and throws the same `ValidationError`s — except the top-level-page one, since rendering a
|
|
417
|
+
link inside an iframe is exactly how you work around that.
|
|
418
|
+
|
|
419
|
+
### `getVerificationOutcome(): Promise<{ status, error? } | null>`
|
|
420
|
+
|
|
421
|
+
Call this on page load to find out how a verification you sent the reader on ended. It resolves `null` on an ordinary
|
|
422
|
+
page load, and otherwise a `status` of `'completed'`, `'cancelled'` or `'failed'`. It also refreshes cached user and
|
|
423
|
+
session data so the new verification state is visible before your next render, and then strips its own params from the
|
|
424
|
+
address bar without reloading — in that order, so that a failed refresh cannot leave the reader with no acknowledgement
|
|
425
|
+
of a flow they just completed.
|
|
426
|
+
|
|
427
|
+
A `'failed'` status carries one of a closed set of `error` values:
|
|
428
|
+
|
|
429
|
+
| error | What happened, and what to tell the reader |
|
|
430
|
+
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
431
|
+
| `requirement_not_met` | The provider ran, but the session came back without a stamp. Not a breakage — offer the verification again rather than apologising for a fault |
|
|
432
|
+
| `login_required` | The reader ended up logged out. Send them to login, then back into verification |
|
|
433
|
+
| `invalid_request` | The requirement was rejected by aID. A caller bug — the checks above catch most of these before the reader is involved |
|
|
434
|
+
| `state_mismatch` | The round trip lost its state, usually a stale tab or a lost cookie. Safe to offer again; it costs one re-verify |
|
|
435
|
+
| `provider_error` | Something broke on the aID or provider side, and anything aID does not recognise is reported as this. Apologise and offer a retry |
|
|
436
|
+
| `unknown_outcome` | This module did not recognise the `verification` value at all. Treated as a failure rather than a success, on the grounds that a value we cannot read must not read as one |
|
|
437
|
+
|
|
438
|
+
**Note**: the outcome is a hint for what to tell the reader, never authority. Gate on the session or on your action's own
|
|
439
|
+
response — not on `status === 'completed'`. In particular, `'completed'` does not promise an attribute was proven: aID
|
|
440
|
+
re-checks only the session half on the way back, and a reader can finish the provider and still decline to overwrite the
|
|
441
|
+
value on their account.
|
|
442
|
+
|
|
347
443
|
### `aidUrls: Record<string, URL>`
|
|
348
444
|
|
|
349
445
|
Get various, environment-aware URLs to pages often linked to from other apps. This includes pages like the aID profile
|
package/index.d.ts
CHANGED
|
@@ -108,6 +108,71 @@ declare class TimeoutError extends Error {
|
|
|
108
108
|
*/
|
|
109
109
|
declare const pollForAccess: (requiredAccessFeatures?: string[], timeout_millis?: number) => Promise<true>;
|
|
110
110
|
|
|
111
|
+
declare const VERIFIABLE_ATTRIBUTES: readonly ["name", "birth_date", "email", "phone"];
|
|
112
|
+
type VerifiableAttribute = (typeof VERIFIABLE_ATTRIBUTES)[number];
|
|
113
|
+
declare const VERIFICATION_SOURCES: readonly ["eid", "otp"];
|
|
114
|
+
type VerificationSource = (typeof VERIFICATION_SOURCES)[number];
|
|
115
|
+
type VerificationRequirement = {
|
|
116
|
+
/** Attributes that must be verified on the user. */
|
|
117
|
+
attributes?: VerifiableAttribute[];
|
|
118
|
+
/** Whether the browser session must carry a verification stamp. */
|
|
119
|
+
session?: boolean;
|
|
120
|
+
/** Which kinds of source are acceptable. Omitted, the attribute implies it. */
|
|
121
|
+
sources?: VerificationSource[];
|
|
122
|
+
/** Force a re-verify when the proof is older than this. Seconds, or `30m`. */
|
|
123
|
+
maxAge?: string | number;
|
|
124
|
+
/** Where the reader lands afterwards. Defaults to the current page. */
|
|
125
|
+
requestedUrl?: string;
|
|
126
|
+
/** Tracking, as on `goToLoginPage`. */
|
|
127
|
+
context?: string;
|
|
128
|
+
};
|
|
129
|
+
type VerificationStatus = 'completed' | 'cancelled' | 'failed';
|
|
130
|
+
/**
|
|
131
|
+
* The closed set a failure can name. The first five are eris's
|
|
132
|
+
* `knownVerificationErrors`, which it normalises anything else down to;
|
|
133
|
+
* `unknown_outcome` is added here for a `verification` value this version does
|
|
134
|
+
* not recognise.
|
|
135
|
+
*/
|
|
136
|
+
type VerificationError = 'invalid_request' | 'requirement_not_met' | 'state_mismatch' | 'provider_error' | 'login_required' | 'unknown_outcome';
|
|
137
|
+
type VerificationOutcome = {
|
|
138
|
+
status: VerificationStatus;
|
|
139
|
+
error?: VerificationError;
|
|
140
|
+
};
|
|
141
|
+
/**
|
|
142
|
+
* Builds the aID Identity Verification URL for a requirement, for a link or a
|
|
143
|
+
* button. See `requireVerification` for the requirement itself.
|
|
144
|
+
*
|
|
145
|
+
* @throws ValidationError on a requirement that asks for nothing, or names an
|
|
146
|
+
* attribute, source or maxAge aID would reject.
|
|
147
|
+
*/
|
|
148
|
+
declare const getVerificationUrl: (requirement: VerificationRequirement) => URL;
|
|
149
|
+
/**
|
|
150
|
+
* Makes sure the reader meets a verification requirement.
|
|
151
|
+
*
|
|
152
|
+
* Resolves `{ satisfied: true }` when the data the browser already holds proves
|
|
153
|
+
* the requirement is met. Otherwise it sends the reader to aID Identity
|
|
154
|
+
* Verification and the returned promise never resolves, because the page is
|
|
155
|
+
* leaving. aID resolves the requirement itself and bounces straight back when
|
|
156
|
+
* it turns out to be met, so a navigation is a redirect, not a BankID prompt.
|
|
157
|
+
*
|
|
158
|
+
* @throws ValidationError, as `getVerificationUrl`, before navigating anywhere.
|
|
159
|
+
*/
|
|
160
|
+
declare const requireVerification: (requirement: VerificationRequirement, { force }?: {
|
|
161
|
+
force?: boolean;
|
|
162
|
+
}) => Promise<{
|
|
163
|
+
satisfied: true;
|
|
164
|
+
}>;
|
|
165
|
+
/**
|
|
166
|
+
* Reads the outcome aID appended on the way back, strips it from the address
|
|
167
|
+
* bar without reloading, and refreshes cached user and session data so the new
|
|
168
|
+
* verification state is visible before the next render.
|
|
169
|
+
*
|
|
170
|
+
* Resolves `null` on an ordinary page load. The outcome is a hint for what to
|
|
171
|
+
* tell the reader — never authority. Gate on the session or on the action's own
|
|
172
|
+
* response instead.
|
|
173
|
+
*/
|
|
174
|
+
declare const getVerificationOutcome: () => Promise<VerificationOutcome | null>;
|
|
175
|
+
|
|
111
176
|
type LoginPageParams = {
|
|
112
177
|
requestedUrl?: string;
|
|
113
178
|
context?: string;
|
|
@@ -131,5 +196,5 @@ declare const aidUrls: {
|
|
|
131
196
|
sites: URL;
|
|
132
197
|
};
|
|
133
198
|
|
|
134
|
-
export { EmergencyModeError, PaywallUnlockRequest, SiteAccessRequest, SiteAccessResponse, TimeoutError, UserDataRequest, aidUrls, getLoginUrl, goToLoginPage, logout, pollForAccess, requestDataRefresh };
|
|
135
|
-
export type { PaywallUnlockResponse };
|
|
199
|
+
export { EmergencyModeError, PaywallUnlockRequest, SiteAccessRequest, SiteAccessResponse, TimeoutError, UserDataRequest, aidUrls, getLoginUrl, getVerificationOutcome, getVerificationUrl, goToLoginPage, logout, pollForAccess, requestDataRefresh, requireVerification };
|
|
200
|
+
export type { PaywallUnlockResponse, VerifiableAttribute, VerificationError, VerificationOutcome, VerificationRequirement, VerificationSource, VerificationStatus };
|
package/package.json
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
"url": "git+https://github.com/amedia/amedia-user-js.git"
|
|
7
7
|
},
|
|
8
8
|
"author": "Amedia Produkt og Teknologi AS (https://amedia.no)",
|
|
9
|
-
"version": "1.
|
|
9
|
+
"version": "1.4.0",
|
|
10
10
|
"type": "module",
|
|
11
11
|
"exports": {
|
|
12
12
|
".": {
|
|
@@ -41,7 +41,7 @@
|
|
|
41
41
|
],
|
|
42
42
|
"dependencies": {
|
|
43
43
|
"jose": "5.9.6",
|
|
44
|
-
"valibot": "1.4.
|
|
44
|
+
"valibot": "1.4.2"
|
|
45
45
|
},
|
|
46
46
|
"eik": {
|
|
47
47
|
"server": "https://assets.acdn.no",
|
package/user.node.js
CHANGED
|
@@ -100,12 +100,20 @@ const SiteAccessSchema = v.object({
|
|
|
100
100
|
const ServiceUserSchema = v.partial(v.object({
|
|
101
101
|
uuid: v.string(),
|
|
102
102
|
name: v.string(),
|
|
103
|
+
name_verified_at: v.nullish(v.string()),
|
|
103
104
|
tracking_key: v.string(),
|
|
104
105
|
avatar: v.string(),
|
|
105
106
|
access: v.array(SiteAccessSchema),
|
|
106
107
|
privacy_preferences: PrivacyPreferencesSchema,
|
|
107
108
|
session_tracking_key: v.string(),
|
|
108
109
|
}));
|
|
110
|
+
v.partial(v.object({
|
|
111
|
+
user_uuid: v.string(),
|
|
112
|
+
user_agent: v.string(),
|
|
113
|
+
session_tracking_key: v.string(),
|
|
114
|
+
verified_at: v.nullish(v.string()),
|
|
115
|
+
verification_source: v.nullish(v.string()),
|
|
116
|
+
}));
|
|
109
117
|
v.object({
|
|
110
118
|
type: v.string(),
|
|
111
119
|
title: v.string(),
|