@amedia/user 1.5.1 → 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/CHANGELOG.md CHANGED
@@ -1,5 +1,103 @@
1
1
  # @amedia/user
2
2
 
3
+ ## 1.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#1299](https://github.com/amedia/amedia-user-js/pull/1299) [`3d5a21a`](https://github.com/amedia/amedia-user-js/commit/3d5a21a72cecf1143581249c1eb326a403e73c9e) Thanks [@hennikul](https://github.com/hennikul)! - aID on-site verification and the On-Site API from a server, not just a browser
8
+
9
+ Everything verification-related moves into `@amedia/user-core`, and
10
+ `@amedia/user/node` gains the server half. The browser API is unchanged except
11
+ where noted under **Changed behaviour** — the same functions now call into core
12
+ rather than carrying their own copy.
13
+
14
+ **New: the On-Site API from a server**
15
+
16
+ `createOnSiteClient({ siteDomain, apiOrigin, token, headers, timeoutMs, signal })`
17
+ reads `getSelf`, `getSession` and `getAccessFeatures` for a reader whose
18
+ `aid.session` you hold, using two credentials: their session id in `X-Aid-Session`
19
+ and an m2m token for the `public-onsite-api` audience. Together these reach data
20
+ a browser session is not granted — the `*_verified_at` timestamps above all.
21
+ - The site travels in `X-Aid-Site`, because `Host` is a forbidden header name
22
+ that `fetch` drops without a word.
23
+ - `apiOrigin` is where the API answers when that is not the site's own domain:
24
+ the in-cluster router (`AID_ONSITE_API_URL`), or another environment's host.
25
+ Left out, a snap session sent to a canonical domain would reach production.
26
+ - `timeoutMs` defaults to 3000 and composes with your own `signal`. There is no
27
+ timeout below it, so a server rendering against an aID that never answers
28
+ would otherwise spend its whole request concurrency waiting.
29
+ - The client holds nothing and costs about a microsecond, so build one per
30
+ request from the site you are answering for. Keep the token provider outside
31
+ it — pass a function, and it is called per request.
32
+
33
+ **New: verification from a server**
34
+ - `buildVerificationUrl({ siteDomain, requestedUrl, ...requirement })` — the
35
+ `/aid/verify` link, so it is in the first render rather than after a script
36
+ loads. Throws for anything aID would refuse anyway.
37
+ - `readVerificationOutcome(url)` — the outcome off the URL the reader came back
38
+ to. Takes a whole URL or a bare path, which is what `req.url` is in
39
+ `node:http` and Express.
40
+ - The requirement vocabulary, shared with the browser:
41
+ `normalizeVerificationRequirement`, `verificationUrlFor`,
42
+ `verificationSourceOf`, `VERIFIABLE_ATTRIBUTES`, `VERIFICATION_SOURCES`,
43
+ `MAX_AGE_CEILING_SECONDS`.
44
+
45
+ **New: which provider the reader will meet**
46
+
47
+ `getVerificationProviders(requirement?)` in the browser and
48
+ `fetchVerificationProviders(requirement?, opts?)` on the server read aID's
49
+ registry, so a page can draw the logo it is about to send someone to rather than
50
+ assume BankID. A provider added on our side then appears without a release on
51
+ yours. Needs no credential, and narrows by the same requirement the verify
52
+ hand-off takes; omit it for the whole catalogue.
53
+
54
+ `icon_svg` is markup from the network — draw it as
55
+ `<img src="data:image/svg+xml;base64,…">` rather than through `innerHTML`.
56
+
57
+ **New: aID's problems, by name**
58
+
59
+ `namesNoReader(error)`, `isLoggedOut(error)` and `isAidProblem(error, ...types)`
60
+ take the error straight from a `catch` and duck-type what it carries, so an
61
+ error from another package's client works too. With `AidProblem` and
62
+ `LOGGED_OUT_PROBLEMS`, a caller matches a problem by name instead of by
63
+ substring.
64
+
65
+ All three are deliberately narrower than "any 4xx": an unapproved audience or a
66
+ missing scope is a configuration fault, and reading it as a signed-out reader
67
+ hides it behind a page that looks like it is working.
68
+
69
+ **Fixed: every reader read as unverified**
70
+
71
+ `ServiceUserSchema` declared neither `birth_date`, `email` and `phone` nor any of
72
+ their `*_verified_at` timestamps, and valibot strips what it does not declare. A
73
+ caller naming `birth_date_verified_at` in a `getSelf` filter got it back silently
74
+ removed — so a verified reader was indistinguishable from an unverified one.
75
+
76
+ **Changed behaviour**
77
+ - `getVerificationOutcome()` (and the new `readVerificationOutcome`) keep `error`
78
+ only when the status is `failed`.
79
+ `?verification=cancelled&verification_error=login_required` used to answer
80
+ `{ status: 'cancelled', error: 'login_required' }` and now answers
81
+ `{ status: 'cancelled' }`. eris never sends that pair — it answers an empty
82
+ error for both `completed` and `cancelled` — so nothing aID produces is lost.
83
+ What it stops is a stale `verification_error` surviving a back-button and
84
+ making `if (outcome.error)` report a failure for a verification that
85
+ completed.
86
+ - `requestedUrl` must be a path on your own site. `getVerificationUrl`,
87
+ `requireVerification` and `buildVerificationUrl` now throw for an absolute URL
88
+ or for `//`/`/\`, which a browser reads as the start of a host. eris keeps
89
+ only the path of `requested_url`, so these were never a redirect off-site —
90
+ they were a reader who finished verifying on the front page instead of where
91
+ they started, with nothing said.
92
+ - `AidRequestOptions` gains `signal`, passed through to `fetch` on every read.
93
+
94
+ **Docs**
95
+
96
+ README rewritten around both halves — browser and node — with setup for the
97
+ in-cluster, direct and non-production cases. The same for third parties in the
98
+ Confluence page. `AGENTS.md` becomes `CLAUDE.md`, and says that a feature here
99
+ is expected to work server-side as well as in the browser.
100
+
3
101
  ## 1.5.1
4
102
 
5
103
  ### Patch Changes
package/index.d.ts CHANGED
@@ -51,6 +51,32 @@ declare class PaywallError extends Error {
51
51
  constructor(message: string, code: string);
52
52
  }
53
53
 
54
+ /**
55
+ * One provider as a chooser needs it: what to call it, what it proves, what it
56
+ * looks like. `icon_svg` is the registry's own artwork, and is serialised even
57
+ * when empty — an absent logo is a provider without one, not an older response.
58
+ *
59
+ * `acr_values` is deliberately absent from the public projection: naming the
60
+ * assurance level invites a caller to ask for a weaker one.
61
+ */
62
+ declare const VerificationProviderSchema: v.ObjectSchema<{
63
+ readonly id: v.StringSchema<undefined>;
64
+ readonly label: v.StringSchema<undefined>;
65
+ readonly source: v.StringSchema<undefined>;
66
+ readonly attributes: v.ArraySchema<v.StringSchema<undefined>, undefined>;
67
+ /**
68
+ * The provider's logo, as SVG markup.
69
+ *
70
+ * Markup from the network, so it goes in as an image rather than as nodes:
71
+ * `<img src="data:image/svg+xml;base64,…">` draws it with scripts inert,
72
+ * while `innerHTML = icon_svg` would run anything it carried. aID writes this
73
+ * and the trust is internal, which is why this is a rendering instruction and
74
+ * not a warning — but the safe rendering costs nothing.
75
+ */
76
+ readonly icon_svg: v.StringSchema<undefined>;
77
+ }, undefined>;
78
+ type VerificationProvider = v.InferOutput<typeof VerificationProviderSchema>;
79
+
54
80
  declare enum AffiliationType {
55
81
  ACCESS = "access",
56
82
  FAMILY = "family",
@@ -64,8 +90,50 @@ declare const PrimarySiteSchema: v.ObjectSchema<{
64
90
  }, undefined>;
65
91
  type PrimarySite = v.InferOutput<typeof PrimarySiteSchema>;
66
92
 
93
+ declare const VERIFIABLE_ATTRIBUTES: readonly ["name", "birth_date", "email", "phone"];
94
+ type VerifiableAttribute = (typeof VERIFIABLE_ATTRIBUTES)[number];
95
+ declare const VERIFICATION_SOURCES: readonly ["eid", "otp"];
96
+ type VerificationSource = (typeof VERIFICATION_SOURCES)[number];
97
+ type VerificationRequirement = {
98
+ /** Attributes that must carry a verification timestamp on the user. */
99
+ attributes?: VerifiableAttribute[];
100
+ /** Whether the session must carry a verification stamp. */
101
+ verifiedSession?: boolean;
102
+ /** Which kinds of source are acceptable. Omitted, the attribute implies it. */
103
+ sources?: VerificationSource[];
104
+ /** Force a re-verify when the proof is older than this. Seconds, or `30m`. `0` means prove it now. */
105
+ maxAge?: string | number;
106
+ /** Where the reader lands afterwards. A path on your own site. */
107
+ requestedUrl?: string;
108
+ /** Tracking, as on `goToLoginPage`. */
109
+ context?: string;
110
+ };
111
+ type VerificationStatus = 'completed' | 'cancelled' | 'failed';
112
+ /**
113
+ * The closed set a failure can name. The first five are eris's
114
+ * `knownVerificationErrors`, which it normalises anything else down to;
115
+ * `unknown_outcome` is added here for a `verification` value this version does
116
+ * not recognise.
117
+ */
118
+ type VerificationError = 'invalid_request' | 'requirement_not_met' | 'state_mismatch' | 'provider_error' | 'login_required' | 'unknown_outcome';
119
+ type VerificationOutcome = {
120
+ status: VerificationStatus;
121
+ error?: VerificationError;
122
+ };
123
+
67
124
  type ClientId = string;
68
125
 
126
+ /**
127
+ * The providers aID may offer this reader, in aID's own order — what to call
128
+ * each one and what it looks like, so a page can draw the logo it is about to
129
+ * send the reader to rather than guess which one that is.
130
+ *
131
+ * Narrowed by a requirement when given, the same one `requireVerification`
132
+ * takes. Answers aID's own origin rather than the site's: the registry knows no
133
+ * reader and needs no credential.
134
+ */
135
+ declare const getVerificationProviders: (requirement?: VerificationRequirement) => Promise<VerificationProvider[]>;
136
+
69
137
  type NamespaceList = Array<string>;
70
138
 
71
139
  type Millis = number;
@@ -173,36 +241,6 @@ declare class TimeoutError extends Error {
173
241
  */
174
242
  declare const pollForAccess: (requiredAccessFeatures?: string[], timeout_millis?: number) => Promise<true>;
175
243
 
176
- declare const VERIFIABLE_ATTRIBUTES: readonly ["name", "birth_date", "email", "phone"];
177
- type VerifiableAttribute = (typeof VERIFIABLE_ATTRIBUTES)[number];
178
- declare const VERIFICATION_SOURCES: readonly ["eid", "otp"];
179
- type VerificationSource = (typeof VERIFICATION_SOURCES)[number];
180
- type VerificationRequirement = {
181
- /** Attributes that must be verified on the user. */
182
- attributes?: VerifiableAttribute[];
183
- /** Whether the browser session must carry a verification stamp. */
184
- verifiedSession?: boolean;
185
- /** Which kinds of source are acceptable. Omitted, the attribute implies it. */
186
- sources?: VerificationSource[];
187
- /** Force a re-verify when the proof is older than this. Seconds, or `30m`. `0` means prove it now. */
188
- maxAge?: string | number;
189
- /** Where the reader lands afterwards. Defaults to the current page. */
190
- requestedUrl?: string;
191
- /** Tracking, as on `goToLoginPage`. */
192
- context?: string;
193
- };
194
- type VerificationStatus = 'completed' | 'cancelled' | 'failed';
195
- /**
196
- * The closed set a failure can name. The first five are eris's
197
- * `knownVerificationErrors`, which it normalises anything else down to;
198
- * `unknown_outcome` is added here for a `verification` value this version does
199
- * not recognise.
200
- */
201
- type VerificationError = 'invalid_request' | 'requirement_not_met' | 'state_mismatch' | 'provider_error' | 'login_required' | 'unknown_outcome';
202
- type VerificationOutcome = {
203
- status: VerificationStatus;
204
- error?: VerificationError;
205
- };
206
244
  /**
207
245
  * Builds the aID Identity Verification URL for a requirement, for a link or a
208
246
  * button. See `requireVerification` for the requirement itself.
@@ -261,5 +299,5 @@ declare const aidUrls: {
261
299
  sites: URL;
262
300
  };
263
301
 
264
- export { EmergencyModeError, FetchTimeoutError, PaywallError, PaywallUnlockRequest, PrivacyPreferences, SiteAccessRequest, SiteAccessResponse, TimeoutError, UserDataRequest, ValidationError, aidUrls, getLoginUrl, getVerificationOutcome, getVerificationUrl, goToLoginPage, logout, pollForAccess, requestDataRefresh, requireVerification };
302
+ export { EmergencyModeError, FetchTimeoutError, PaywallError, PaywallUnlockRequest, PrivacyPreferences, SiteAccessRequest, SiteAccessResponse, TimeoutError, UserDataRequest, ValidationError, aidUrls, getLoginUrl, getVerificationOutcome, getVerificationProviders, getVerificationUrl, goToLoginPage, logout, pollForAccess, requestDataRefresh, requireVerification };
265
303
  export type { PaywallUnlockResponse, State, UserAttributes, 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.5.1",
9
+ "version": "1.6.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.2"
44
+ "valibot": "1.5.0"
45
45
  },
46
46
  "eik": {
47
47
  "server": "https://assets.acdn.no",