ark-oauth-client-node 0.0.0-stage → 2.2.1

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.
@@ -0,0 +1,672 @@
1
+ /**
2
+ * Type declarations for ark-oauth-client-node.
3
+ *
4
+ * Hand-written rather than generated, so the documentation an editor shows is the documentation
5
+ * the source carries. Everything below mirrors src/ exactly; when one changes, so does the other.
6
+ */
7
+
8
+ // =====================================================================
9
+ // errors
10
+ // =====================================================================
11
+
12
+ export class ArkError extends Error {}
13
+ export class ArkConfigError extends ArkError {}
14
+ export class ArkNetworkError extends ArkError {}
15
+ export class ArkCallbackError extends ArkError {}
16
+
17
+ export class ArkTokenError extends ArkError {
18
+ /** The claim that failed validation, when one claim is to blame. */
19
+ claim: string | null;
20
+ token: string | null;
21
+ }
22
+
23
+ export class ArkOAuthError extends ArkError {
24
+ /** The RFC 6749 §5.2 code: `invalid_grant`, `invalid_client`, `slow_down`, … */
25
+ error: string;
26
+ errorDescription: string | null;
27
+ errorUri: string | null;
28
+ /** The HTTP status the error arrived with. */
29
+ status: number;
30
+ /** The URL that produced it. */
31
+ endpoint: string | null;
32
+ body: unknown;
33
+ static fromResponse(status: number, body: unknown, endpoint: string): ArkOAuthError;
34
+ }
35
+
36
+ // =====================================================================
37
+ // configuration
38
+ // =====================================================================
39
+
40
+ export type TokenEndpointAuthMethod = 'client_secret_basic' | 'client_secret_post' | 'private_key_jwt' | 'none';
41
+ export type ResponseMode = 'query' | 'fragment' | 'form_post';
42
+
43
+ export interface PrivateKeyJwtOptions {
44
+ /** A PEM string, a JWK object, or a node:crypto KeyObject. */
45
+ privateKey: unknown;
46
+ /** Published in the assertion header so the server can pick the right key from your JWKS. */
47
+ kid?: string;
48
+ alg?: string;
49
+ lifetimeSeconds?: number;
50
+ }
51
+
52
+ export interface ArkClientOptions {
53
+ /** The issuer URL of the tenant: `{BaseUrl}/{TenantId}`. The only value that is really required. */
54
+ authority?: string;
55
+ /** Alternative to `authority`, matching the .NET client's configuration shape. */
56
+ authServerUrl?: string;
57
+ tenantId?: string;
58
+
59
+ clientId: string;
60
+ /** Omit for public clients (SPA, native, CLI). */
61
+ clientSecret?: string | null;
62
+ /** Derived from what you configure: `none`, `client_secret_basic` or `private_key_jwt`. */
63
+ tokenEndpointAuthMethod?: TokenEndpointAuthMethod;
64
+ privateKeyJwt?: PrivateKeyJwtOptions | null;
65
+
66
+ /** Absolute, no fragment, https unless loopback — the server matches it exactly. */
67
+ redirectUri?: string;
68
+ postLogoutRedirectUri?: string;
69
+ /** Defaults to openid, profile, email, offline_access. */
70
+ scopes?: string[];
71
+ /** Expected `aud` when verifying access tokens in an API. */
72
+ audience?: string | null;
73
+
74
+ responseMode?: ResponseMode;
75
+ /** Send authorization parameters over the back channel (RFC 9126). */
76
+ usePar?: boolean;
77
+ prompt?: string | null;
78
+ acrValues?: string | null;
79
+ extraAuthorizationParams?: Record<string, string> | null;
80
+
81
+ clockToleranceSeconds?: number;
82
+ /** Only ever false for local development against a plain-http provider. */
83
+ requireHttps?: boolean;
84
+ /** Require at_hash/c_hash on ID tokens. On by default; Ark always sends them. */
85
+ requireTokenHashes?: boolean;
86
+ idTokenSigningAlgorithms?: string[] | null;
87
+
88
+ timeoutMs?: number;
89
+ metadataTtlMs?: number;
90
+ jwksTtlMs?: number;
91
+ /** How long before an unknown `kid` may trigger another JWKS fetch. Default 10s. */
92
+ jwksMinRefreshIntervalMs?: number;
93
+ fetch?: typeof fetch;
94
+ roleClaim?: string;
95
+ }
96
+
97
+ export type ArkResolvedConfig = Readonly<Required<Pick<ArkClientOptions, 'clientId'>> & Record<string, unknown>> & {
98
+ authority: string;
99
+ clientId: string;
100
+ clientSecret: string | null;
101
+ tokenEndpointAuthMethod: TokenEndpointAuthMethod;
102
+ redirectUri: string | null;
103
+ postLogoutRedirectUri: string | null;
104
+ scopes: readonly string[];
105
+ };
106
+
107
+ export function normalizeConfig(options: ArkClientOptions): ArkResolvedConfig;
108
+ export const DEFAULT_SCOPES: readonly string[];
109
+
110
+ // =====================================================================
111
+ // tokens
112
+ // =====================================================================
113
+
114
+ export interface TokenResponse {
115
+ access_token?: string;
116
+ token_type?: string;
117
+ expires_in?: number;
118
+ expires_at?: number;
119
+ refresh_token?: string;
120
+ id_token?: string;
121
+ scope?: string;
122
+ [key: string]: unknown;
123
+ }
124
+
125
+ export class TokenSet {
126
+ constructor(response?: TokenResponse, options?: { issuedAt?: number; claims?: Record<string, any> | null });
127
+ accessToken: string | null;
128
+ tokenType: string;
129
+ refreshToken: string | null;
130
+ idToken: string | null;
131
+ scope: string | null;
132
+ issuedAt: number;
133
+ /** Absolute expiry in epoch seconds — computed on arrival, so it survives a session store. */
134
+ expiresAt: number | null;
135
+ /** Validated ID token claims. Null for a client credentials token. */
136
+ claims: Record<string, any> | null;
137
+ raw: TokenResponse;
138
+
139
+ expiresIn(now?: number): number | null;
140
+ /** True once the token is spent. `leewaySeconds` renews it before it dies rather than after. */
141
+ expired(leewaySeconds?: number, now?: number): boolean;
142
+ scopes(): string[];
143
+ hasScope(...wanted: Array<string | string[]>): boolean;
144
+ /** The tenant's authorization claims from the access token — what to authorise on. */
145
+ arkClaims(): string[];
146
+ accessTokenClaims(): Record<string, any> | null;
147
+ readonly subject: string | null;
148
+ authorizationHeader(): string;
149
+ toJSON(): Record<string, any>;
150
+ static fromJSON(data: any): TokenSet | null;
151
+ }
152
+
153
+ // =====================================================================
154
+ // discovery, keys, JWT
155
+ // =====================================================================
156
+
157
+ export interface ProviderMetadata {
158
+ issuer: string;
159
+ authorization_endpoint: string;
160
+ token_endpoint: string;
161
+ userinfo_endpoint?: string;
162
+ jwks_uri: string;
163
+ introspection_endpoint?: string;
164
+ revocation_endpoint?: string;
165
+ end_session_endpoint?: string;
166
+ device_authorization_endpoint?: string;
167
+ pushed_authorization_request_endpoint?: string;
168
+ registration_endpoint?: string;
169
+ scopes_supported?: string[];
170
+ grant_types_supported?: string[];
171
+ response_modes_supported?: string[];
172
+ code_challenge_methods_supported?: string[];
173
+ token_endpoint_auth_methods_supported?: string[];
174
+ authorization_response_iss_parameter_supported?: boolean;
175
+ require_pushed_authorization_requests?: boolean;
176
+ [key: string]: unknown;
177
+ }
178
+
179
+ export function discoveryUrls(authority: string): [string, string];
180
+
181
+ export class MetadataResolver {
182
+ constructor(options?: { ttlMs?: number; timeoutMs?: number; fetch?: typeof fetch });
183
+ get(authority: string, options?: { force?: boolean }): Promise<ProviderMetadata>;
184
+ clear(): void;
185
+ }
186
+
187
+ export interface Jwk {
188
+ kty: string;
189
+ kid?: string;
190
+ use?: string;
191
+ alg?: string;
192
+ [key: string]: unknown;
193
+ }
194
+
195
+ export class JwksCache {
196
+ constructor(jwksUri: string, options?: { ttlMs?: number; minRefreshIntervalMs?: number; timeoutMs?: number; fetch?: typeof fetch });
197
+ readonly uri: string;
198
+ keys(options?: { force?: boolean }): Promise<Jwk[]>;
199
+ getSigningKey(kid: string | undefined, alg: string): Promise<Jwk>;
200
+ clear(): void;
201
+ }
202
+
203
+ export interface DecodedJwt {
204
+ header: Record<string, any>;
205
+ payload: Record<string, any>;
206
+ signature: Buffer;
207
+ signingInput: string;
208
+ }
209
+
210
+ /** Decodes without verifying. Never authorise on the result. */
211
+ export function decodeJwt(token: string): DecodedJwt;
212
+ export function verifySignature(decoded: DecodedJwt, jwk: Jwk, options?: { algorithms?: string[] }): true;
213
+
214
+ export interface ClaimValidationOptions {
215
+ issuer?: string;
216
+ audience?: string;
217
+ subject?: string;
218
+ nonce?: string | null;
219
+ maxAgeSeconds?: number | null;
220
+ clockToleranceSeconds?: number;
221
+ requireExp?: boolean;
222
+ requireIat?: boolean;
223
+ now?: number;
224
+ }
225
+
226
+ export function validateClaims(payload: Record<string, any>, options?: ClaimValidationOptions): Record<string, any>;
227
+ export function validateTokenHashes(
228
+ payload: Record<string, any>,
229
+ options?: { accessToken?: string | null; code?: string | null; require?: boolean }
230
+ ): Record<string, any>;
231
+
232
+ export function verifyJwt(
233
+ token: string,
234
+ jwks: { getSigningKey(kid: string | undefined, alg: string): Promise<Jwk> },
235
+ options?: ClaimValidationOptions & {
236
+ typ?: string;
237
+ algorithms?: string[];
238
+ accessToken?: string | null;
239
+ code?: string | null;
240
+ requireTokenHashes?: boolean;
241
+ }
242
+ ): Promise<Record<string, any>>;
243
+
244
+ export function signJwt(
245
+ payload: Record<string, any>,
246
+ options: { key: unknown; alg?: string; kid?: string; typ?: string; header?: Record<string, any> }
247
+ ): string;
248
+
249
+ // =====================================================================
250
+ // PKCE and encoding
251
+ // =====================================================================
252
+
253
+ export function createCodeVerifier(): string;
254
+ export function codeChallengeFor(verifier: string): string;
255
+ export function createPkcePair(): { codeVerifier: string; codeChallenge: string; codeChallengeMethod: 'S256' };
256
+ export function createState(): string;
257
+ export function createNonce(): string;
258
+ export function base64UrlEncode(input: Buffer | string): string;
259
+ export function base64UrlDecode(value: string): Buffer;
260
+ export function leftHalfHash(value: string): string;
261
+ export function randomToken(bytes?: number): string;
262
+
263
+ // =====================================================================
264
+ // the client
265
+ // =====================================================================
266
+
267
+ /** What createAuthorizationUrl returns and handleCallback needs back. Store it server-side. */
268
+ export interface ArkLoginTransaction {
269
+ url: string;
270
+ state: string;
271
+ nonce: string | null;
272
+ codeVerifier: string;
273
+ redirectUri: string;
274
+ scope: string;
275
+ maxAge: number | null;
276
+ createdAt: number;
277
+ returnTo?: string;
278
+ }
279
+
280
+ export interface AuthorizationUrlOptions {
281
+ scopes?: string[];
282
+ state?: string;
283
+ nonce?: string;
284
+ redirectUri?: string;
285
+ responseMode?: ResponseMode;
286
+ prompt?: string;
287
+ loginHint?: string;
288
+ maxAge?: number;
289
+ acrValues?: string;
290
+ usePar?: boolean;
291
+ returnTo?: string;
292
+ extra?: Record<string, string>;
293
+ }
294
+
295
+ export interface DeviceAuthorizationResponse {
296
+ device_code: string;
297
+ user_code: string;
298
+ verification_uri: string;
299
+ verification_uri_complete: string;
300
+ expires_in: number;
301
+ interval: number;
302
+ }
303
+
304
+ export interface IntrospectionResponse {
305
+ active: boolean;
306
+ sub?: string;
307
+ scope?: string;
308
+ client_id?: string;
309
+ token_type?: string;
310
+ exp?: number;
311
+ iat?: number;
312
+ [key: string]: unknown;
313
+ }
314
+
315
+ export interface ArkSetupReport {
316
+ authority: string;
317
+ clientId: string;
318
+ isConfidential: boolean;
319
+ tokenEndpointAuthMethod: TokenEndpointAuthMethod;
320
+ scopes: string[];
321
+ redirectUri: string | null;
322
+ postLogoutRedirectUri: string | null;
323
+ origin: string | null;
324
+ tenantId: string;
325
+ /** The tenant's admin console, where the client is registered. */
326
+ adminConsoleUrl: string;
327
+ /** The provider's own page of what it expects from this client. */
328
+ integrationPageUrl: string;
329
+ discoveryUrl: string;
330
+ discoveryOk: boolean;
331
+ discoveryError: string | null;
332
+ supportsClientCredentials: boolean;
333
+ supportsDynamicRegistration: boolean;
334
+ provider: Record<string, any> | null;
335
+ signingKeys?: Array<{ kid?: string; kty: string; alg: string | null; use: string | null }>;
336
+ /** Empty when local configuration and the provider's metadata agree. */
337
+ problems: string[];
338
+ }
339
+
340
+ export class ArkOAuthClient {
341
+ constructor(options: ArkClientOptions);
342
+ readonly config: ArkResolvedConfig;
343
+ readonly authority: string;
344
+
345
+ metadata(options?: { force?: boolean }): Promise<ProviderMetadata>;
346
+ jwks(): Promise<JwksCache>;
347
+
348
+ createAuthorizationUrl(options?: AuthorizationUrlOptions): Promise<ArkLoginTransaction>;
349
+ static readCallbackParams(input: string | URLSearchParams | Record<string, any>): Record<string, string>;
350
+ handleCallback(
351
+ responseParams: string | URLSearchParams | Record<string, any>,
352
+ transaction: ArkLoginTransaction | (Partial<ArkLoginTransaction> & { state: string; codeVerifier: string }),
353
+ options?: { redirectUri?: string }
354
+ ): Promise<TokenSet>;
355
+ exchangeCode(options: {
356
+ code: string;
357
+ codeVerifier: string;
358
+ redirectUri: string;
359
+ nonce?: string | null;
360
+ maxAge?: number | null;
361
+ }): Promise<TokenSet>;
362
+
363
+ refresh(refreshToken: string, options?: { scopes?: string[] }): Promise<TokenSet>;
364
+ clientCredentials(options?: {
365
+ scopes?: string[];
366
+ clientId?: string;
367
+ clientSecret?: string;
368
+ force?: boolean;
369
+ renewBeforeSeconds?: number;
370
+ }): Promise<TokenSet>;
371
+
372
+ deviceAuthorization(options?: { scopes?: string[] }): Promise<DeviceAuthorizationResponse>;
373
+ pollDeviceToken(
374
+ deviceAuthorization: DeviceAuthorizationResponse | string,
375
+ options?: { signal?: AbortSignal; onPending?: (error: ArkOAuthError) => void; intervalSeconds?: number; timeoutSeconds?: number }
376
+ ): Promise<TokenSet>;
377
+
378
+ pushAuthorizationRequest(params: Record<string, string>): Promise<{ request_uri: string; expires_in: number }>;
379
+
380
+ userInfo(accessToken: string): Promise<Record<string, any>>;
381
+ introspect(token: string, options?: { tokenTypeHint?: 'access_token' | 'refresh_token' }): Promise<IntrospectionResponse>;
382
+ revoke(token: string, options?: { tokenTypeHint?: 'access_token' | 'refresh_token' }): Promise<true>;
383
+ endSessionUrl(options?: { idTokenHint?: string; postLogoutRedirectUri?: string; state?: string; clientId?: string }): Promise<string>;
384
+
385
+ verifyIdToken(
386
+ idToken: string,
387
+ options?: { nonce?: string | null; accessToken?: string | null; code?: string | null; maxAge?: number | null }
388
+ ): Promise<Record<string, any>>;
389
+ verifyAccessToken(
390
+ token: string,
391
+ options?: { audience?: string; scopes?: string[]; arkClaims?: string[]; requireTypeHeader?: boolean }
392
+ ): Promise<Record<string, any>>;
393
+
394
+ registerClient(clientMetadata: Record<string, any>, initialAccessToken?: string): Promise<Record<string, any>>;
395
+ readRegistration(clientId: string, registrationAccessToken: string): Promise<Record<string, any>>;
396
+ deleteRegistration(clientId: string, registrationAccessToken: string): Promise<true>;
397
+
398
+ /** Pairs local configuration with the provider's live metadata and reports what does not line up. */
399
+ checkSetup(options?: { origin?: string; callbackPath?: string }): Promise<ArkSetupReport>;
400
+ }
401
+
402
+ export function createArkClient(options: ArkClientOptions): ArkOAuthClient;
403
+
404
+ // =====================================================================
405
+ // sessions
406
+ // =====================================================================
407
+
408
+ export interface SessionStore {
409
+ get(id: string): Promise<any | null>;
410
+ set(id: string, data: any, ttlSeconds: number): Promise<void>;
411
+ destroy(id: string): Promise<void>;
412
+ touch?(id: string, ttlSeconds: number): Promise<void>;
413
+ }
414
+
415
+ export class MemorySessionStore implements SessionStore {
416
+ constructor(options?: { sweepIntervalMs?: number });
417
+ get(id: string): Promise<any | null>;
418
+ set(id: string, data: any, ttlSeconds: number): Promise<void>;
419
+ destroy(id: string): Promise<void>;
420
+ touch(id: string, ttlSeconds: number): Promise<void>;
421
+ sweep(now?: number): void;
422
+ readonly size: number;
423
+ close(): void;
424
+ }
425
+
426
+ export function createSessionId(): string;
427
+ export function signSessionId(id: string, secret: string): string;
428
+ export function unsignSessionId(value: string, secret: string): string | null;
429
+ export function parseCookies(header?: string): Record<string, string>;
430
+ export function serializeCookie(
431
+ name: string,
432
+ value: string,
433
+ options?: { maxAge?: number; domain?: string; path?: string; expires?: Date | number; httpOnly?: boolean; secure?: boolean; sameSite?: string }
434
+ ): string;
435
+
436
+ // =====================================================================
437
+ // account switching on a shared browser
438
+ // =====================================================================
439
+
440
+ export const ArkAccessDeniedReasons: Readonly<{ NO_APP_ACCESS: 'no_app_access'; FORBIDDEN: 'forbidden' }>;
441
+ export type ArkAccessDeniedReason = 'no_app_access' | 'forbidden';
442
+
443
+ /** `accountSwitch` — the same settings as AccountSwitch (.NET) and account_switch (Python). Everything is off or unchanged by default. */
444
+ export interface ArkAccountSwitchOptions {
445
+ /** Serve the three endpoints, and send an HTML 403 to the page. Default true. */
446
+ enabled?: boolean;
447
+ /** Refuse, at the callback, an account the provider issued no ark_claims for. Default false. */
448
+ requireArkClaims?: boolean;
449
+ /** Narrow that check to at least one of these values (case-insensitive). */
450
+ requiredClaims?: string[];
451
+ /** Default /ark/no-access. */
452
+ accessDeniedPath?: string;
453
+ /** Default /ark/switch-user. */
454
+ switchUserPath?: string;
455
+ /** Default /ark/sign-out. */
456
+ signOutPath?: string;
457
+ /** Draw the built-in page. Turn off when accessDeniedPath is a route of your own. Default true. */
458
+ serveDefaultPage?: boolean;
459
+ /** Defaults to the client id. */
460
+ appDisplayName?: string | null;
461
+ showSignedInAccount?: boolean;
462
+ allowFullSignOut?: boolean;
463
+ /** Switching also ends the provider session — for a kiosk. Default false. */
464
+ endProviderSessionOnSwitch?: boolean;
465
+ /** Default 'login'. */
466
+ prompt?: string;
467
+ homePath?: string;
468
+ /** http(s) only. */
469
+ supportUrl?: string | null;
470
+ supportEmail?: string | null;
471
+ }
472
+
473
+ export const ACCOUNT_SWITCH_DEFAULTS: Readonly<Required<ArkAccountSwitchOptions>>;
474
+ export function normalizeAccountSwitch(options?: ArkAccountSwitchOptions): Readonly<Required<ArkAccountSwitchOptions>>;
475
+
476
+ export interface ArkAccessEvaluationContext {
477
+ /** ID token claims. */
478
+ claims: Record<string, any>;
479
+ arkClaims: string[];
480
+ /** What the configured rule concluded before your handler ran. */
481
+ allowedByConfiguration: boolean;
482
+ tokens: TokenSet | null;
483
+ }
484
+
485
+ export interface ArkAccessDeniedContext {
486
+ reason: ArkAccessDeniedReason;
487
+ subject: string | null;
488
+ email: string | null;
489
+ name: string | null;
490
+ arkClaims: string[];
491
+ returnUrl: string | null;
492
+ /** Set true when you have written the response yourself. */
493
+ handled: boolean;
494
+ }
495
+
496
+ export interface ArkDeniedAccount {
497
+ subject: string | null;
498
+ email: string | null;
499
+ name: string | null;
500
+ reason: ArkAccessDeniedReason | null;
501
+ returnUrl: string | null;
502
+ }
503
+
504
+ export interface ArkClientEvents {
505
+ /** Your entitlement rule. Replaces the configured one; read allowedByConfiguration to combine them. */
506
+ onEvaluateAccess?: (context: ArkAccessEvaluationContext) => boolean | Promise<boolean>;
507
+ /** Log a denial, or write a response of your own (then set `handled` or just respond). */
508
+ onAccessDenied?: (context: ArkAccessDeniedContext, req: any, res: any) => void | Promise<void>;
509
+ }
510
+
511
+ export interface ArkChallengeOptions {
512
+ returnTo?: string;
513
+ prompt?: string;
514
+ loginHint?: string;
515
+ scopes?: string[];
516
+ maxAge?: number;
517
+ }
518
+
519
+ export const ArkChallengeProperties: Readonly<{
520
+ /** prompt=login: the provider draws its sign-in form instead of answering from its session. */
521
+ switchUser(returnUrl?: string | null, loginHint?: string | null, prompt?: string): ArkChallengeOptions;
522
+ selectAccount(returnUrl?: string | null): ArkChallengeOptions;
523
+ }>;
524
+
525
+ /** A same-origin path, or `fallback`. Guards every return URL against open redirects. */
526
+ export function localOrDefault(url: string | null | undefined, fallback?: string | null): string | null;
527
+
528
+ export function renderAccessDeniedPage(
529
+ options: Readonly<Required<ArkAccountSwitchOptions>>,
530
+ model: { app?: string | null; account?: string | null; returnUrl: string }
531
+ ): string;
532
+
533
+ /** Binds an appsettings.json `ark_oauth_client` section (C#, camel or snake keys) into arkExpress()/ArkOAuthClient options. */
534
+ export const ArkAuthConfig: Readonly<{
535
+ fromMapping(data: Record<string, any>): Partial<ArkExpressOptions>;
536
+ }>;
537
+
538
+ /** This package's version, read from its package.json. */
539
+ export const VERSION: string;
540
+
541
+ // =====================================================================
542
+ // middleware
543
+ // =====================================================================
544
+
545
+ /** What the middleware attaches to every request. */
546
+ export interface ArkRequestContext {
547
+ client: ArkOAuthClient;
548
+ store: SessionStore;
549
+ sessionId: string | null;
550
+ isAuthenticated: boolean;
551
+ /** ID token claims, plus UserInfo when fetchUserInfo is on. */
552
+ user: Record<string, any> | null;
553
+ sub: string | null;
554
+ /** Ark authorization claims — the thing to authorise on. */
555
+ claims: string[];
556
+ scopes: string[];
557
+ tokens: TokenSet | null;
558
+ idToken: string | null;
559
+ /** The current access token, refreshed first if it is about to expire. */
560
+ accessToken(): Promise<string | null>;
561
+ /** Adds `Authorization: Bearer …` to a headers object for a downstream call. */
562
+ authorize(headers?: Record<string, string>): Promise<Record<string, string>>;
563
+ hasClaim(...wanted: Array<string | string[]>): boolean;
564
+ hasScope(...wanted: Array<string | string[]>): boolean;
565
+ login(options?: ArkChallengeOptions): Promise<void>;
566
+ /** Revokes the refresh token, ends the local session, then RP-initiated logout at the provider. */
567
+ logout(options?: { returnTo?: string }): Promise<void>;
568
+ /** Drops this session and challenges with prompt=login, so somebody else can sign in. */
569
+ switchUser(options?: { returnUrl?: string; loginHint?: string }): Promise<void>;
570
+ /** This application's session and the provider's. */
571
+ signOutEverywhere(options?: { returnUrl?: string }): Promise<void>;
572
+ /** This application's session only. */
573
+ signOutLocally(options?: { returnUrl?: string }): Promise<void>;
574
+ /** The account the last denial was about, for a page of your own; null otherwise. */
575
+ deniedAccount(): ArkDeniedAccount | null;
576
+ }
577
+
578
+ /** What arkBearer attaches when a token is presented. */
579
+ export interface ArkBearerContext {
580
+ isAuthenticated: boolean;
581
+ token: string | null;
582
+ payload?: Record<string, any>;
583
+ sub?: string;
584
+ clientId?: string | null;
585
+ sessionId?: string | null;
586
+ scopes: string[];
587
+ claims: string[];
588
+ hasClaim?(...wanted: Array<string | string[]>): boolean;
589
+ hasScope?(...wanted: Array<string | string[]>): boolean;
590
+ client?: ArkOAuthClient;
591
+ }
592
+
593
+ type Middleware = (req: any, res: any, next: (error?: any) => void) => void | Promise<void>;
594
+
595
+ export interface ArkExpressOptions extends Partial<ArkClientOptions> {
596
+ /** Reuse an existing client instead of configuring one here. */
597
+ client?: ArkOAuthClient;
598
+ /** Signs the session cookie. At least 16 characters, and the same value across every instance. */
599
+ secret: string;
600
+ loginPath?: string;
601
+ /** Defaults to the path of `redirectUri`, or /signin-oidc. */
602
+ callbackPath?: string;
603
+ logoutPath?: string;
604
+ /** Defaults to an in-process Map. Supply a shared store for more than one instance. */
605
+ store?: SessionStore;
606
+ cookieName?: string;
607
+ cookie?: { httpOnly?: boolean; secure?: boolean; sameSite?: string; domain?: string; path?: string };
608
+ sessionTtlSeconds?: number;
609
+ /** Renew the access token this many seconds before it expires. Default 120, as in the .NET and Python clients. */
610
+ refreshLeewaySeconds?: number;
611
+ /** Also call /userinfo at sign-in and merge the result into `req.ark.user`. */
612
+ fetchUserInfo?: boolean;
613
+ returnToParam?: string;
614
+ defaultReturnTo?: string;
615
+ /** Where a failed sign-in lands, with ?auth_error=… */
616
+ errorPath?: string | null;
617
+ onError?: (error: Error, req: any, res: any, next: (error?: any) => void) => void;
618
+ /** Read X-Forwarded-Proto + X-Forwarded-Host (both, or neither). Turn off when no proxy sets them. Default true. */
619
+ trustProxy?: boolean;
620
+ /** The shared-browser case: entitlement at the callback, the access-denied page, prompt=login switching. */
621
+ accountSwitch?: ArkAccountSwitchOptions;
622
+ events?: ArkClientEvents;
623
+ }
624
+
625
+ export interface ArkExpressMiddleware extends Middleware {
626
+ /** Redirects a browser to sign in; answers 401 with a bearer challenge for anything else. */
627
+ requireAuth(options?: { claims?: string[]; scopes?: string[] }): Middleware;
628
+ requireClaims(...claims: Array<string | string[]>): Middleware;
629
+ requireScopes(...scopes: Array<string | string[]>): Middleware;
630
+ /** checkSetup() for this request: the redirect URI it would really send, and who is signed in. */
631
+ checkSetup(req: any): Promise<ArkSetupReport & { isAuthenticated: boolean; signedInAs: string | null; authError: string | null }>;
632
+ switchUser(req: any, res: any, options?: { returnUrl?: string; loginHint?: string }): Promise<void>;
633
+ signOutEverywhere(req: any, res: any, options?: { returnUrl?: string }): Promise<void>;
634
+ signOutLocally(req: any, res: any, options?: { returnUrl?: string }): Promise<void>;
635
+ deniedAccount(req: any): ArkDeniedAccount | null;
636
+ readonly client: ArkOAuthClient;
637
+ readonly store: SessionStore;
638
+ readonly accountSwitch: Readonly<Required<ArkAccountSwitchOptions>>;
639
+ readonly loginPath: string;
640
+ readonly callbackPath: string;
641
+ readonly logoutPath: string;
642
+ }
643
+
644
+ export function arkExpress(options: ArkExpressOptions): ArkExpressMiddleware;
645
+
646
+ export interface ArkBearerOptions extends Partial<ArkClientOptions> {
647
+ client?: ArkOAuthClient;
648
+ /** Required on every request this middleware guards. */
649
+ scopes?: string[];
650
+ /** Required Ark authorization claims. */
651
+ claims?: string[];
652
+ audience?: string;
653
+ /** Let unauthenticated requests through with `req.ark.isAuthenticated === false`. */
654
+ optional?: boolean;
655
+ /** Require the RFC 9068 `at+jwt` type header. On by default. */
656
+ requireTypeHeader?: boolean;
657
+ }
658
+
659
+ export interface ArkBearerMiddleware extends Middleware {
660
+ require(options?: { scopes?: string[]; claims?: string[] }): Middleware;
661
+ readonly client: ArkOAuthClient;
662
+ }
663
+
664
+ export function arkBearer(options?: ArkBearerOptions): ArkBearerMiddleware;
665
+
666
+ declare global {
667
+ namespace Express {
668
+ interface Request {
669
+ ark?: ArkRequestContext | ArkBearerContext;
670
+ }
671
+ }
672
+ }