@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/user.node.d.ts CHANGED
@@ -1,4 +1,5 @@
1
1
  import * as v from 'valibot';
2
+ import { BaseIssue } from 'valibot';
2
3
  import { JWTPayload } from 'jose';
3
4
 
4
5
  type AccessFeatures = string[];
@@ -77,10 +78,30 @@ declare class IgnoredNetworkError extends Error {
77
78
  constructor(originalError?: unknown | undefined);
78
79
  }
79
80
 
81
+ /**
82
+ * Every attribute is optional: what comes back is decided by the filter asked
83
+ * for and the scopes behind the credential, and aID omits what it may not read
84
+ * exactly as it omits what the reader does not have.
85
+ *
86
+ * An attribute missing from this schema is dropped in silence — valibot strips
87
+ * what it does not declare — so a field absent here reads as an attribute the
88
+ * reader has not got. For a `*_verified_at` that means every reader looks
89
+ * unverified, which is why all four are listed rather than only the one a
90
+ * browser session can reach.
91
+ */
80
92
  declare const ServiceUserSchema: Omit<v.ObjectSchema<{
81
93
  readonly uuid: v.StringSchema<undefined>;
82
94
  readonly name: v.StringSchema<undefined>;
83
95
  readonly name_verified_at: v.NullishSchema<v.StringSchema<undefined>, undefined>;
96
+ readonly birth_date: v.NullishSchema<v.StringSchema<undefined>, undefined>;
97
+ readonly birth_date_verified_at: v.NullishSchema<v.StringSchema<undefined>, undefined>;
98
+ readonly email: v.NullishSchema<v.StringSchema<undefined>, undefined>;
99
+ readonly email_verified_at: v.NullishSchema<v.StringSchema<undefined>, undefined>;
100
+ readonly phone: v.NullishSchema<v.ObjectSchema<{
101
+ readonly country_code: v.StringSchema<undefined>;
102
+ readonly national_number: v.StringSchema<undefined>;
103
+ }, undefined>, undefined>;
104
+ readonly phone_verified_at: v.NullishSchema<v.StringSchema<undefined>, undefined>;
84
105
  readonly tracking_key: v.StringSchema<undefined>;
85
106
  readonly avatar: v.StringSchema<undefined>;
86
107
  readonly access: v.ArraySchema<v.ObjectSchema<{
@@ -97,6 +118,15 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
97
118
  readonly uuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
98
119
  readonly name: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
99
120
  readonly name_verified_at: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
121
+ readonly birth_date: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
122
+ readonly birth_date_verified_at: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
123
+ readonly email: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
124
+ readonly email_verified_at: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
125
+ readonly phone: v.OptionalSchema<v.NullishSchema<v.ObjectSchema<{
126
+ readonly country_code: v.StringSchema<undefined>;
127
+ readonly national_number: v.StringSchema<undefined>;
128
+ }, undefined>, undefined>, undefined>;
129
+ readonly phone_verified_at: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
100
130
  readonly tracking_key: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
101
131
  readonly avatar: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
102
132
  readonly access: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -113,6 +143,15 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
113
143
  uuid?: string | undefined;
114
144
  name?: string | undefined;
115
145
  name_verified_at?: string | null | undefined;
146
+ birth_date?: string | null | undefined;
147
+ birth_date_verified_at?: string | null | undefined;
148
+ email?: string | null | undefined;
149
+ email_verified_at?: string | null | undefined;
150
+ phone?: {
151
+ country_code: string;
152
+ national_number: string;
153
+ } | null | undefined;
154
+ phone_verified_at?: string | null | undefined;
116
155
  tracking_key?: string | undefined;
117
156
  avatar?: string | undefined;
118
157
  access?: {
@@ -128,6 +167,15 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
128
167
  uuid?: string | undefined;
129
168
  name?: string | undefined;
130
169
  name_verified_at?: string | null | undefined;
170
+ birth_date?: string | null | undefined;
171
+ birth_date_verified_at?: string | null | undefined;
172
+ email?: string | null | undefined;
173
+ email_verified_at?: string | null | undefined;
174
+ phone?: {
175
+ country_code: string;
176
+ national_number: string;
177
+ } | null | undefined;
178
+ phone_verified_at?: string | null | undefined;
131
179
  tracking_key?: string | undefined;
132
180
  avatar?: string | undefined;
133
181
  access?: {
@@ -144,6 +192,15 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
144
192
  uuid?: string | undefined;
145
193
  name?: string | undefined;
146
194
  name_verified_at?: string | null | undefined;
195
+ birth_date?: string | null | undefined;
196
+ birth_date_verified_at?: string | null | undefined;
197
+ email?: string | null | undefined;
198
+ email_verified_at?: string | null | undefined;
199
+ phone?: {
200
+ country_code: string;
201
+ national_number: string;
202
+ } | null | undefined;
203
+ phone_verified_at?: string | null | undefined;
147
204
  tracking_key?: string | undefined;
148
205
  avatar?: string | undefined;
149
206
  access?: {
@@ -161,6 +218,15 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
161
218
  uuid?: string | undefined;
162
219
  name?: string | undefined;
163
220
  name_verified_at?: string | null | undefined;
221
+ birth_date?: string | null | undefined;
222
+ birth_date_verified_at?: string | null | undefined;
223
+ email?: string | null | undefined;
224
+ email_verified_at?: string | null | undefined;
225
+ phone?: {
226
+ country_code: string;
227
+ national_number: string;
228
+ } | null | undefined;
229
+ phone_verified_at?: string | null | undefined;
164
230
  tracking_key?: string | undefined;
165
231
  avatar?: string | undefined;
166
232
  access?: {
@@ -177,6 +243,15 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
177
243
  uuid?: string | undefined;
178
244
  name?: string | undefined;
179
245
  name_verified_at?: string | null | undefined;
246
+ birth_date?: string | null | undefined;
247
+ birth_date_verified_at?: string | null | undefined;
248
+ email?: string | null | undefined;
249
+ email_verified_at?: string | null | undefined;
250
+ phone?: {
251
+ country_code: string;
252
+ national_number: string;
253
+ } | null | undefined;
254
+ phone_verified_at?: string | null | undefined;
180
255
  tracking_key?: string | undefined;
181
256
  avatar?: string | undefined;
182
257
  access?: {
@@ -193,11 +268,89 @@ declare const ServiceUserSchema: Omit<v.ObjectSchema<{
193
268
  } | undefined;
194
269
  };
195
270
  type ServiceUser = v.InferOutput<typeof ServiceUserSchema>;
271
+ declare const SessionSchema: Omit<v.ObjectSchema<{
272
+ readonly user_uuid: v.StringSchema<undefined>;
273
+ readonly user_agent: v.StringSchema<undefined>;
274
+ readonly session_tracking_key: v.StringSchema<undefined>;
275
+ readonly verified_at: v.NullishSchema<v.StringSchema<undefined>, undefined>;
276
+ readonly verification_source: v.NullishSchema<v.StringSchema<undefined>, undefined>;
277
+ }, undefined>, "~types" | "~run" | "~standard" | "entries"> & {
278
+ readonly entries: {
279
+ readonly user_uuid: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
280
+ readonly user_agent: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
281
+ readonly session_tracking_key: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
282
+ readonly verified_at: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
283
+ readonly verification_source: v.OptionalSchema<v.NullishSchema<v.StringSchema<undefined>, undefined>, undefined>;
284
+ };
285
+ readonly "~standard": v.StandardProps<{
286
+ user_uuid?: string | undefined;
287
+ user_agent?: string | undefined;
288
+ session_tracking_key?: string | undefined;
289
+ verified_at?: string | null | undefined;
290
+ verification_source?: string | null | undefined;
291
+ }, {
292
+ user_uuid?: string | undefined;
293
+ user_agent?: string | undefined;
294
+ session_tracking_key?: string | undefined;
295
+ verified_at?: string | null | undefined;
296
+ verification_source?: string | null | undefined;
297
+ }>;
298
+ readonly "~run": (dataset: v.UnknownDataset, config: v.Config<v.BaseIssue<unknown>>) => v.OutputDataset<{
299
+ user_uuid?: string | undefined;
300
+ user_agent?: string | undefined;
301
+ session_tracking_key?: string | undefined;
302
+ verified_at?: string | null | undefined;
303
+ verification_source?: string | null | undefined;
304
+ }, v.StringIssue | v.ObjectIssue>;
305
+ readonly "~types"?: {
306
+ readonly input: {
307
+ user_uuid?: string | undefined;
308
+ user_agent?: string | undefined;
309
+ session_tracking_key?: string | undefined;
310
+ verified_at?: string | null | undefined;
311
+ verification_source?: string | null | undefined;
312
+ };
313
+ readonly output: {
314
+ user_uuid?: string | undefined;
315
+ user_agent?: string | undefined;
316
+ session_tracking_key?: string | undefined;
317
+ verified_at?: string | null | undefined;
318
+ verification_source?: string | null | undefined;
319
+ };
320
+ readonly issue: v.StringIssue | v.ObjectIssue;
321
+ } | undefined;
322
+ };
323
+ type Session = v.InferOutput<typeof SessionSchema>;
196
324
  declare enum LoginStatus {
197
325
  INITIATED = "INITIATED",
198
326
  COMPLETED = "COMPLETED",
199
327
  ERROR = "ERROR"
200
328
  }
329
+ /**
330
+ * One provider as a chooser needs it: what to call it, what it proves, what it
331
+ * looks like. `icon_svg` is the registry's own artwork, and is serialised even
332
+ * when empty — an absent logo is a provider without one, not an older response.
333
+ *
334
+ * `acr_values` is deliberately absent from the public projection: naming the
335
+ * assurance level invites a caller to ask for a weaker one.
336
+ */
337
+ declare const VerificationProviderSchema: v.ObjectSchema<{
338
+ readonly id: v.StringSchema<undefined>;
339
+ readonly label: v.StringSchema<undefined>;
340
+ readonly source: v.StringSchema<undefined>;
341
+ readonly attributes: v.ArraySchema<v.StringSchema<undefined>, undefined>;
342
+ /**
343
+ * The provider's logo, as SVG markup.
344
+ *
345
+ * Markup from the network, so it goes in as an image rather than as nodes:
346
+ * `<img src="data:image/svg+xml;base64,…">` draws it with scripts inert,
347
+ * while `innerHTML = icon_svg` would run anything it carried. aID writes this
348
+ * and the trust is internal, which is why this is a rendering instruction and
349
+ * not a warning — but the safe rendering costs nothing.
350
+ */
351
+ readonly icon_svg: v.StringSchema<undefined>;
352
+ }, undefined>;
353
+ type VerificationProvider = v.InferOutput<typeof VerificationProviderSchema>;
201
354
 
202
355
  declare enum AffiliationType {
203
356
  ACCESS = "access",
@@ -212,7 +365,157 @@ declare const PrimarySiteSchema: v.ObjectSchema<{
212
365
  }, undefined>;
213
366
  type PrimarySite = v.InferOutput<typeof PrimarySiteSchema>;
214
367
 
368
+ declare const VERIFIABLE_ATTRIBUTES: readonly ["name", "birth_date", "email", "phone"];
369
+ type VerifiableAttribute = (typeof VERIFIABLE_ATTRIBUTES)[number];
370
+ declare const VERIFICATION_SOURCES: readonly ["eid", "otp"];
371
+ type VerificationSource = (typeof VERIFICATION_SOURCES)[number];
372
+ type VerificationRequirement = {
373
+ /** Attributes that must carry a verification timestamp on the user. */
374
+ attributes?: VerifiableAttribute[];
375
+ /** Whether the session must carry a verification stamp. */
376
+ verifiedSession?: boolean;
377
+ /** Which kinds of source are acceptable. Omitted, the attribute implies it. */
378
+ sources?: VerificationSource[];
379
+ /** Force a re-verify when the proof is older than this. Seconds, or `30m`. `0` means prove it now. */
380
+ maxAge?: string | number;
381
+ /** Where the reader lands afterwards. A path on your own site. */
382
+ requestedUrl?: string;
383
+ /** Tracking, as on `goToLoginPage`. */
384
+ context?: string;
385
+ };
386
+ type VerificationStatus = 'completed' | 'cancelled' | 'failed';
387
+ /**
388
+ * The closed set a failure can name. The first five are eris's
389
+ * `knownVerificationErrors`, which it normalises anything else down to;
390
+ * `unknown_outcome` is added here for a `verification` value this version does
391
+ * not recognise.
392
+ */
393
+ type VerificationError = 'invalid_request' | 'requirement_not_met' | 'state_mismatch' | 'provider_error' | 'login_required' | 'unknown_outcome';
394
+ type VerificationOutcome = {
395
+ status: VerificationStatus;
396
+ error?: VerificationError;
397
+ };
398
+ declare const MAX_AGE_CEILING_SECONDS: number;
399
+ /**
400
+ * What kind of source a provider name is, as quirinus classifies it.
401
+ *
402
+ * Vesta writes only names quirinus knows — `bankid`, `otp`, and `eid` for the
403
+ * dummy provider, chosen so a role-holding test account classifies rather than
404
+ * falling through (`VerificationProvider::STAMP_SOURCES`). Its own table matches
405
+ * `eid` by substring where quirinus requires equality; this follows quirinus,
406
+ * because classifying a name quirinus leaves unclassified is what would report a
407
+ * requirement met that aID considers unmet.
408
+ */
409
+ declare const verificationSourceOf: (provider: string | null | undefined) => VerificationSource | null;
410
+ type NormalizedRequirement = {
411
+ attributes: VerifiableAttribute[];
412
+ verifiedSession: boolean;
413
+ sources: VerificationSource[];
414
+ maxAgeSeconds?: number;
415
+ requestedUrl: string;
416
+ context: string;
417
+ };
418
+ /**
419
+ * Checks the requirement and fills in what was left out. Throws rather than
420
+ * navigating for anything aID would refuse anyway, so a caller bug costs no
421
+ * round trip.
422
+ *
423
+ * `fallbackRequestedUrl` is where the reader returns when the requirement does
424
+ * not say — the current page in a browser, and a caller's own choice on a
425
+ * server, which has no current page.
426
+ */
427
+ declare const normalizeVerificationRequirement: (requirement: VerificationRequirement, fallbackRequestedUrl: string) => NormalizedRequirement;
428
+ /** `/aid/verify` on the site's own domain, carrying the requirement. */
429
+ declare const verificationUrlFor: (siteDomain: string, requirement: NormalizedRequirement) => URL;
430
+ declare const readVerificationOutcome: (url: URL | string) => VerificationOutcome | null;
431
+
215
432
  declare const DEFAULT_CLIENT_ID = "default";
433
+ type CoreFetcher = (url: string | URL | Request, options?: RequestInit) => Promise<Record<string, unknown> | null>;
434
+ type CoreSchemaVerifiedFetch = <Schema extends v.BaseSchema<unknown, unknown, BaseIssue<unknown>>>(schema: Schema, url: string | URL | Request, options?: RequestInit) => Promise<v.InferOutput<Schema>>;
435
+ interface AidRequestOptions {
436
+ /** If set, is prefixed to all request URLs. Empty by default (relative URLs — browser behavior). */
437
+ baseUrl?: string;
438
+ /** Additional headers to merge into every request (e.g. Authorization for Node). */
439
+ headers?: Record<string, string>;
440
+ /** Override the fetcher used for JSON calls. Defaults to `coreFetcher`. Browser passes its own wrapper so emergency-mode / retry / circuit-breaker concerns apply. */
441
+ fetcher?: CoreFetcher;
442
+ /** Override the schema-verified fetcher. Defaults to `coreSchemaVerifiedFetch`. */
443
+ schemaVerifiedFetch?: CoreSchemaVerifiedFetch;
444
+ /**
445
+ * Aborts the call. A browser has the page's own lifetime to bound a request;
446
+ * a server has none, so the node client sets one from its own timeout.
447
+ */
448
+ signal?: AbortSignal;
449
+ }
450
+
451
+ /**
452
+ * The problem types aID answers with, named rather than matched by substring.
453
+ *
454
+ * A caller testing `type.includes('session/not-found')` stops matching the day
455
+ * a type is renamed, and does so silently — the branch simply never runs again.
456
+ */
457
+ declare const AidProblem: {
458
+ readonly SESSION_NOT_FOUND: "/api/problem/aid/session/not-found";
459
+ readonly SESSION_NOT_SPECIFIED: "/api/problem/aid/session/not-specified";
460
+ readonly SESSION_IDENTIFIER_INVALID: "/api/problem/aid/session/identifier-invalid";
461
+ readonly SESSION_NOT_VERIFIED: "/api/problem/aid/session/not-verified";
462
+ readonly SESSION_ALREADY_ACTIVATED: "/api/problem/aid/session/already-activated";
463
+ readonly SESSION_TOO_MANY_ACTIVATED: "/api/problem/aid/session/too-many-activated";
464
+ readonly USER_DEACTIVATED: "/api/problem/aid/user/deactivated";
465
+ readonly BIRTH_DATE_NOT_VERIFIED: "/api/problem/aid/user/birthdate-not-verified";
466
+ readonly BIRTH_DATE_VERIFIED_TOO_LONG_AGO: "/api/problem/aid/user/birthdate-verified-too-long-ago";
467
+ readonly AGREEMENT_NOT_FOUND: "/api/problem/aid/agreement/not-found";
468
+ readonly AGREEMENT_DUPLICATE: "/api/problem/aid/agreement/duplicate";
469
+ readonly ACTIVATION_NOT_FOUND: "/api/problem/aid/activation/not-found";
470
+ /** The request named no reader: with an m2m credential, a session with no user. */
471
+ readonly MISSING_PARAMETER: "/api/problem/request/param/missing";
472
+ readonly INVALID_PARAMETER: "/api/problem/request/param/invalid";
473
+ readonly INVALID_CLIENT_CREDENTIAL: "/api/problem/request/auth/invalid-client-credential";
474
+ readonly ACCESS_DENIED: "/api/problem/request/auth/access-denied";
475
+ readonly INSUFFICIENT_SCOPE: "/api/problem/request/auth/oauth-insufficient-scope";
476
+ readonly UNKNOWN_SITE: "/api/problem/onsite/unknown-site";
477
+ readonly SITE_NOT_AID_ENABLED: "/api/problem/onsite/site-not-aid-enabled";
478
+ readonly UNKNOWN_SERVICE_PROVIDER: "/api/problem/onsite/unknown-service-provider";
479
+ readonly NO_BACKEND_FOR_SERVICE_PROVIDER: "/api/problem/onsite/no-backend-for-service-provider";
480
+ readonly BACKEND_UNREACHABLE: "/api/problem/onsite/backend-unreachable";
481
+ readonly SITE_CONFIG_UNAVAILABLE: "/api/problem/onsite/site-config-unavailable";
482
+ };
483
+ type AidProblemType = (typeof AidProblem)[keyof typeof AidProblem];
484
+ declare const isAidProblem: (value: unknown, ...types: AidProblemType[]) => boolean;
485
+ /**
486
+ * Nobody is signed in. Render a login link rather than an error — this is a
487
+ * state, not a failure.
488
+ */
489
+ declare const LOGGED_OUT_PROBLEMS: readonly ["/api/problem/aid/session/not-found", "/api/problem/aid/session/not-specified", "/api/problem/aid/session/identifier-invalid", "/api/problem/aid/user/deactivated"];
490
+ declare const isLoggedOut: (value: unknown) => boolean;
491
+ /**
492
+ * No reader to answer about: signed out, or an anonymous session, which names
493
+ * no user for an m2m credential to act for.
494
+ *
495
+ * Takes the error straight from a catch block:
496
+ *
497
+ * ```ts
498
+ * try {
499
+ * return await aid.getSelf(sessionId);
500
+ * } catch (error) {
501
+ * if (namesNoReader(error)) return null;
502
+ * throw error;
503
+ * }
504
+ * ```
505
+ *
506
+ * Deliberately distinct from every 4xx. An unapproved audience or a missing
507
+ * scope is a configuration fault, and reading it as a signed-out reader hides
508
+ * it behind a page that looks like it is working.
509
+ *
510
+ * `MISSING_PARAMETER` is in the list on eris' behaviour rather than on its name:
511
+ * both places that answer this problem type mean "the request named no reader"
512
+ * — an m2m credential with no session, and a session identifying no user. An
513
+ * ordinary missing parameter answers in eris' older JSON:API shape, which
514
+ * carries no `type` at all and so cannot reach here. That is a convention, not
515
+ * a guarantee the type name makes, so a third place answering it for a real
516
+ * missing parameter would widen this helper silently (amedia-user-js#1299).
517
+ */
518
+ declare const namesNoReader: (value: unknown) => boolean;
216
519
 
217
520
  interface AidClientOptions {
218
521
  /** Absolute base URL for aID (e.g. "https://aid.example.no"). Required. */
@@ -255,6 +558,101 @@ interface AidClient {
255
558
  */
256
559
  declare const createAidClient: (options: AidClientOptions) => AidClient;
257
560
 
561
+ /** The router reads this; `Host` cannot be set from `fetch`. */
562
+ declare const SITE_HEADER = "X-Aid-Site";
563
+ declare const SESSION_HEADER = "X-Aid-Session";
564
+ interface OnSiteClientOptions {
565
+ /** The site to act for, as aID knows it — its main domain, not an alias. */
566
+ siteDomain: string;
567
+ /**
568
+ * Where the On-Site API answers, when that is not the site's own domain.
569
+ * Defaults to `https://{siteDomain}`, which is right whenever the site is
570
+ * served where aID knows it.
571
+ *
572
+ * Two reasons it is not:
573
+ *
574
+ * - **Inside Amedia's clusters**, the router next door skips the trip out
575
+ * through the edge and back. Every pod we deploy is given its address as
576
+ * `AID_ONSITE_API_URL`; it resolves in our clusters and nowhere else.
577
+ * - **Outside production**, the site answers somewhere other than its
578
+ * canonical domain — `www.avisnavn.no.snap5.api.no` while aID still knows
579
+ * it as `www.avisnavn.no`. `siteDomain` stays canonical, because that is
580
+ * what names the site to aID; this is where the environment goes.
581
+ *
582
+ * Left to its default, a snap session sent to a canonical domain reaches
583
+ * production and answers that it does not know the session — which reads
584
+ * like a login problem rather than a wrong environment.
585
+ */
586
+ apiOrigin?: string;
587
+ /**
588
+ * An m2m access token minted for the `public-onsite-api` audience. Needed for
589
+ * anything a reader's own session is not granted, the verification timestamps
590
+ * above all.
591
+ *
592
+ * **Pass a function**, not a resolved token. It is called on each request, so
593
+ * whatever caches and refreshes tokens stays outside this client and keeps
594
+ * working however many clients are made. A string is a token you have already
595
+ * minted, which is fine for a long-lived client and wrong for one built per
596
+ * request — that mints one per request.
597
+ */
598
+ token?: string | (() => string | Promise<string>);
599
+ /** Additional headers to merge into every request. */
600
+ headers?: Record<string, string>;
601
+ /**
602
+ * How long to wait before giving up, in milliseconds. Defaults to 3000.
603
+ *
604
+ * There is no timeout below this one: an aID that accepts the connection and
605
+ * then never answers holds the request open until the platform's own socket
606
+ * timeout, and a server rendering pages against it spends its whole request
607
+ * concurrency waiting. A page without the reader's name beats a page that
608
+ * never arrives, so `getSelf` failing fast is the useful failure.
609
+ *
610
+ * Pass `signal` instead to drive it from your own request's lifetime; the two
611
+ * compose, and whichever fires first wins.
612
+ */
613
+ timeoutMs?: number;
614
+ /** Aborts the outgoing call — your own request's signal, typically. */
615
+ signal?: AbortSignal;
616
+ }
617
+ interface OnSiteClient {
618
+ /**
619
+ * The reader the session belongs to.
620
+ *
621
+ * Name `uuid` in the filter even when you do not want it: a filter naming
622
+ * only attributes your token may not read answers `403`, while one that also
623
+ * names a readable attribute answers with the unreadable ones simply absent.
624
+ * Absent is also what an attribute the reader does not have looks like, so
625
+ * treat a missing `*_verified_at` as unproven — never as proven.
626
+ */
627
+ getSelf: (sessionId: string, filter?: string[]) => Promise<ServiceUser>;
628
+ /** The session itself: whether it is verified, and when. */
629
+ getSession: (sessionId: string) => Promise<Session>;
630
+ /** Access features on this client's site, or on a sibling if named. */
631
+ getAccessFeatures: (sessionId: string, siteDomain?: string) => Promise<string[]>;
632
+ }
633
+ /**
634
+ * A server-side client for the aID On-Site API.
635
+ *
636
+ * Two credentials, two jobs: `X-Aid-Session` says which reader the call is
637
+ * about, and the m2m token says what may be read about them. Together they
638
+ * reach data the reader's own browser session is not granted, about a reader
639
+ * the session proves is still signed in.
640
+ *
641
+ * The site travels in `X-Aid-Site` rather than `Host`, which is a forbidden
642
+ * header name — `fetch` drops it without a word, and the router would resolve
643
+ * its own address instead. It is sent on both roads: going direct, the URL
644
+ * already names the site and eris reads it off `Host`, so the header is spare
645
+ * rather than wrong, and one request shape serves both.
646
+ *
647
+ * Holds nothing: three closures over these options, no cache and no pool, about
648
+ * a microsecond to build. So a server juggling many sites makes one per request
649
+ * from the site it is answering for, rather than keeping a map of them — the
650
+ * token provider is the thing worth keeping, and it lives outside.
651
+ *
652
+ * @see https://www.aid.no/aid/docs/developer/aid-on-site-api
653
+ */
654
+ declare const createOnSiteClient: (options: OnSiteClientOptions) => OnSiteClient;
655
+
258
656
  interface ShamoClientOptions {
259
657
  baseUrl: string;
260
658
  token: string;
@@ -265,6 +663,46 @@ interface ShamoClient {
265
663
  }
266
664
  declare const createShamoClient: (options: ShamoClientOptions) => ShamoClient;
267
665
 
666
+ interface ServerVerificationRequirement extends VerificationRequirement {
667
+ /** The site to send the reader to, as aID knows it. */
668
+ siteDomain: string;
669
+ /**
670
+ * Where the reader lands afterwards, as a path on your own site. Required
671
+ * here, unlike in the browser: a server has no current page to fall back to.
672
+ */
673
+ requestedUrl: string;
674
+ }
675
+ /**
676
+ * The `/aid/verify` link for a requirement, ready to put in an `href`.
677
+ *
678
+ * Built on the server so the link is in the first render rather than after a
679
+ * script has loaded. Throws for a requirement aID would refuse anyway — an
680
+ * unknown attribute, a `sources` that excludes one, nothing required at all —
681
+ * so a caller bug costs no round trip.
682
+ *
683
+ * @see https://www.aid.no/aid/docs/developer/aid-on-site-verification
684
+ */
685
+ declare const buildVerificationUrl: ({ siteDomain, ...requirement }: ServerVerificationRequirement) => URL;
686
+ /**
687
+ * The providers aID may offer a reader, in aID's own order — what to call each
688
+ * one and what it looks like, so a server-rendered page can draw the logo it is
689
+ * about to send the reader to.
690
+ *
691
+ * Narrowed by a requirement when given; omit it for the whole catalogue.
692
+ *
693
+ * Unlike everything else here this one lives on aID's own origin rather than
694
+ * the site's, and needs no credential: the registry knows no reader. That
695
+ * origin is filled in, because in a browser a relative URL would have resolved
696
+ * against the page and here there is no page — `fetch('/api/aid/...')` simply
697
+ * throws. Name another `baseUrl` to reach another environment.
698
+ *
699
+ * `icon_svg` is markup from the network. Rendering it through `innerHTML` runs
700
+ * whatever it contains; `<img src="data:image/svg+xml;base64,…">` does not.
701
+ *
702
+ * @see https://www.aid.no/aid/docs/developer/aid-on-site-verification
703
+ */
704
+ declare const fetchVerificationProviders: (requirement?: VerificationRequirement, opts?: AidRequestOptions) => Promise<VerificationProvider[]>;
705
+
268
706
  interface JwksOptions {
269
707
  /** Maximum age of the JWKS cache in milliseconds. Default 10 minutes. */
270
708
  cacheMaxAge?: number;
@@ -322,5 +760,5 @@ interface ValidatedToken {
322
760
  */
323
761
  declare const validateToken: (jwt: string, options: ValidateTokenOptions) => Promise<ValidatedToken>;
324
762
 
325
- export { AffiliationType, DEFAULT_CLIENT_ID, FetchTimeoutError, IgnoredNetworkError, LoginStatus, ProblemJsonError, ResponseError, ServerError, ValidationError, clearJwksCache, createAidClient, createShamoClient, validateToken };
326
- export type { AccessFeatures, AidClient, AidClientOptions, JwksOptions, PrimarySite, ServiceUser, ShamoClient, ShamoClientOptions, State, UserAttributes, ValidateTokenOptions, ValidatedToken };
763
+ export { AffiliationType, AidProblem, DEFAULT_CLIENT_ID, FetchTimeoutError, IgnoredNetworkError, LOGGED_OUT_PROBLEMS, LoginStatus, MAX_AGE_CEILING_SECONDS, ProblemJsonError, ResponseError, SESSION_HEADER, SITE_HEADER, ServerError, VERIFIABLE_ATTRIBUTES, VERIFICATION_SOURCES, ValidationError, buildVerificationUrl, clearJwksCache, createAidClient, createOnSiteClient, createShamoClient, fetchVerificationProviders, isAidProblem, isLoggedOut, namesNoReader, normalizeVerificationRequirement, readVerificationOutcome, validateToken, verificationSourceOf, verificationUrlFor };
764
+ export type { AccessFeatures, AidClient, AidClientOptions, AidProblemType, JwksOptions, OnSiteClient, OnSiteClientOptions, PrimarySite, ServerVerificationRequirement, ServiceUser, ShamoClient, ShamoClientOptions, State, UserAttributes, ValidateTokenOptions, ValidatedToken, VerifiableAttribute, VerificationError, VerificationOutcome, VerificationProvider, VerificationRequirement, VerificationSource, VerificationStatus };