@nauth-toolkit/client 0.3.2 → 0.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/dist/index.d.mts CHANGED
@@ -469,6 +469,9 @@ declare enum NAuthErrorCode {
469
469
  PASSWORD_RESET_MAX_ATTEMPTS = "PASSWORD_RESET_MAX_ATTEMPTS",
470
470
  RATE_LIMIT_PASSWORD_RESET = "RATE_LIMIT_PASSWORD_RESET",
471
471
  SIGNIN_BLOCKED_HIGH_RISK = "SIGNIN_BLOCKED_HIGH_RISK",
472
+ OIDC_INTERACTION_NOT_FOUND = "OIDC_INTERACTION_NOT_FOUND",
473
+ OIDC_LOGIN_REQUIRED = "OIDC_LOGIN_REQUIRED",
474
+ OIDC_ACCESS_DENIED = "OIDC_ACCESS_DENIED",
472
475
  RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
473
476
  FORBIDDEN = "FORBIDDEN",
474
477
  INTERNAL_ERROR = "INTERNAL_ERROR",
@@ -1079,6 +1082,49 @@ interface NAuthClientConfig {
1079
1082
  */
1080
1083
  headers?: Record<string, string>;
1081
1084
  };
1085
+ /**
1086
+ * OpenID Connect interaction configuration.
1087
+ *
1088
+ * Only relevant to an application that *is* an OpenID Connect provider — one running
1089
+ * `@nauth-toolkit/oidc-provider` and hosting its own consent screen. A relying party
1090
+ * signing in with someone else's provider needs none of this.
1091
+ *
1092
+ * @example
1093
+ * ```typescript
1094
+ * const client = new NAuthClient({
1095
+ * baseUrl: 'https://api.example.com',
1096
+ * authPathPrefix: '/auth',
1097
+ * tokenDelivery: 'cookies',
1098
+ * oidc: {
1099
+ * // Only needed when the backend mounts the interaction routes somewhere
1100
+ * // other than `{baseUrl}/oidc/interaction`.
1101
+ * basePath: 'https://api.example.com/identity/interaction',
1102
+ * },
1103
+ * });
1104
+ * ```
1105
+ */
1106
+ oidc?: {
1107
+ /**
1108
+ * Base path (or absolute URL) of the backend's interaction routes.
1109
+ *
1110
+ * Must match where the provider module mounted them — `interaction.path` in
1111
+ * `OIDCProviderModule.forRoot()`, plus any global prefix.
1112
+ *
1113
+ * @default `{baseUrl}/oidc/interaction`
1114
+ */
1115
+ basePath?: string;
1116
+ /**
1117
+ * Frontend route that renders the consent screen.
1118
+ *
1119
+ * The interaction id is appended to it, so `/interaction` produces
1120
+ * `/interaction/<uid>`. This must match the route the backend's
1121
+ * `interactionUrl` sends the browser to, and is what the return guard and
1122
+ * navigation handler send a user back to after a login detour.
1123
+ *
1124
+ * @default '/interaction'
1125
+ */
1126
+ interactionPath?: string;
1127
+ };
1082
1128
  }
1083
1129
 
1084
1130
  /**
@@ -1844,6 +1890,63 @@ interface CreateApiKeyResult {
1844
1890
  apiKey: ApiKeyInfo;
1845
1891
  }
1846
1892
 
1893
+ /**
1894
+ * Types for driving an OpenID Connect interaction from the browser.
1895
+ *
1896
+ * These mirror what `@nauth-toolkit/oidc-provider`'s interaction bridge returns. They
1897
+ * are only needed by an application that hosts the consent screen for its own OpenID
1898
+ * Connect provider — a relying party signing in *with* such a provider uses an OIDC
1899
+ * client library instead.
1900
+ */
1901
+ /**
1902
+ * nauth's verdict on the session behind an interaction request.
1903
+ *
1904
+ * - `authenticated` — a completed login stands behind the request
1905
+ * - `login_required` — recoverable: send the user through login and come back
1906
+ * - `denied` — the account may not be issued credentials at all
1907
+ */
1908
+ type OIDCGateStatus = 'authenticated' | 'login_required' | 'denied';
1909
+ /** The client application an authorization request is being made on behalf of. */
1910
+ interface OIDCInteractionClient {
1911
+ /** Public client identifier. */
1912
+ clientId: string;
1913
+ /** Human-readable name, when the client registered one. */
1914
+ clientName?: string;
1915
+ /** Logo to show on the consent screen. */
1916
+ logoUri?: string;
1917
+ /** The client's home page. */
1918
+ clientUri?: string;
1919
+ }
1920
+ /** What the consent screen needs in order to ask the user. */
1921
+ interface OIDCInteractionState {
1922
+ /** The pending interaction id. */
1923
+ uid: string;
1924
+ /** What the provider is asking for: a login, or consent for scopes. */
1925
+ prompt: 'login' | 'consent' | string;
1926
+ /** The client making the request, as the user should see it. */
1927
+ client: OIDCInteractionClient;
1928
+ /** Scopes the client asked for. */
1929
+ scopes: string[];
1930
+ /** Scopes still needing consent — the rest are already granted. */
1931
+ missingScopes: string[];
1932
+ /** nauth's verdict on the current session. */
1933
+ gate: OIDCGateStatus;
1934
+ /** Why, when the gate is not `authenticated`. */
1935
+ gateReason?: string;
1936
+ /** External identifier of the signed-in user, when there is one. */
1937
+ sub?: string;
1938
+ }
1939
+ /** Where to send the browser after a decision. */
1940
+ interface OIDCInteractionRedirect {
1941
+ /** Absolute URL to navigate to. Leave the SPA — the provider takes over from here. */
1942
+ redirectTo: string;
1943
+ }
1944
+ /** The user's answer to a consent screen. */
1945
+ interface OIDCConsentDecision {
1946
+ /** A narrowed set of scopes to grant. Omit to grant everything that was asked for. */
1947
+ scopes?: string[];
1948
+ }
1949
+
1847
1950
  /**
1848
1951
  * Client-side error wrapper for SDK operations.
1849
1952
  *
@@ -2836,6 +2939,144 @@ declare class ApiKeyOperations {
2836
2939
  private handleError;
2837
2940
  }
2838
2941
 
2942
+ /** Storage key holding the interaction to return to after a login detour. */
2943
+ declare const PENDING_INTERACTION_KEY = "nauth_pending_interaction";
2944
+ /** Frontend route that renders the consent screen, when none is configured. */
2945
+ declare const DEFAULT_INTERACTION_ROUTE = "/interaction";
2946
+ /**
2947
+ * OpenID Connect interaction operations. Accessed via `client.oidc.*`.
2948
+ *
2949
+ * These drive the consent screen of an application that *is* an OpenID Connect
2950
+ * provider — one running `@nauth-toolkit/oidc-provider`. A relying party signing in
2951
+ * with someone else's provider needs none of this; use an OIDC client library.
2952
+ *
2953
+ * Calls the interaction routes your backend mounts. With NestJS those are shipped by
2954
+ * `OIDCProviderModule.forRoot()` and default to `/oidc/interaction`, which is what
2955
+ * `basePath` assumes; point `oidc.basePath` elsewhere if you moved them.
2956
+ *
2957
+ * Every method answers with a `redirectTo` rather than following a redirect itself,
2958
+ * because the browser has to leave the single-page app entirely at that point:
2959
+ * `window.location.assign(redirectTo)`, not `router.navigate`.
2960
+ *
2961
+ * @example
2962
+ * ```typescript
2963
+ * const state = await client.oidc.getInteraction(uid);
2964
+ *
2965
+ * if (state.gate === 'login_required') {
2966
+ * await client.oidc.setPendingInteraction(uid);
2967
+ * router.navigate(['/login']);
2968
+ * } else if (state.prompt === 'login') {
2969
+ * const { redirectTo } = await client.oidc.completeLogin(uid);
2970
+ * window.location.assign(redirectTo);
2971
+ * }
2972
+ * ```
2973
+ */
2974
+ declare class OIDCOperations {
2975
+ private readonly config;
2976
+ private readonly storage;
2977
+ private readonly basePath;
2978
+ /** Frontend route rendering the consent screen, with the id appended. */
2979
+ readonly interactionPath: string;
2980
+ /**
2981
+ * @param config - Resolved client configuration
2982
+ * @param storage - Ephemeral (session-scoped) storage for the pending interaction
2983
+ * @param basePath - Base path for the interaction routes (default: `{baseUrl}/oidc/interaction`)
2984
+ */
2985
+ constructor(config: ResolvedNAuthClientConfig, storage: NAuthStorageAdapter, basePath?: string);
2986
+ /**
2987
+ * The in-app route that renders the consent screen for a given interaction.
2988
+ *
2989
+ * One place for the convention, so a route guard, a navigation handler and a
2990
+ * component all agree on where the consent screen lives.
2991
+ *
2992
+ * @param uid - The pending interaction id
2993
+ * @returns A route path such as `/interaction/abc123`
2994
+ */
2995
+ interactionRoute(uid: string): string;
2996
+ /**
2997
+ * Read a pending interaction, so the page can decide what to render.
2998
+ *
2999
+ * Answers for a signed-out caller too — a `login_required` gate is precisely the
3000
+ * signal to send the user through login.
3001
+ *
3002
+ * @param uid - The pending interaction id, from the route the provider redirected to
3003
+ * @returns What the request needs, and nauth's verdict on the current session
3004
+ */
3005
+ getInteraction(uid: string): Promise<OIDCInteractionState>;
3006
+ /**
3007
+ * Complete the login step for the currently authenticated user.
3008
+ *
3009
+ * Used when `getInteraction` reports `prompt === 'login'` and the gate is
3010
+ * `authenticated`: nothing needs showing, the interaction just needs resolving.
3011
+ *
3012
+ * @param uid - The pending interaction id
3013
+ * @returns Where to send the browser to resume the authorization request
3014
+ */
3015
+ completeLogin(uid: string): Promise<OIDCInteractionRedirect>;
3016
+ /**
3017
+ * Grant the client what it asked for.
3018
+ *
3019
+ * @param uid - The pending interaction id
3020
+ * @param scopes - A narrowed set of scopes to grant; omit to grant everything asked for
3021
+ * @returns Where to send the browser next
3022
+ */
3023
+ approve(uid: string, scopes?: string[]): Promise<OIDCInteractionRedirect>;
3024
+ /**
3025
+ * Refuse the request. The client is told `access_denied`.
3026
+ *
3027
+ * @param uid - The pending interaction id
3028
+ * @returns Where to send the browser next
3029
+ */
3030
+ deny(uid: string): Promise<OIDCInteractionRedirect>;
3031
+ /**
3032
+ * Abandon a pending interaction, so the client gets a clean protocol error rather
3033
+ * than waiting on a browser tab that is never coming back.
3034
+ *
3035
+ * @param uid - The pending interaction id
3036
+ * @returns Where to send the browser
3037
+ */
3038
+ abort(uid: string): Promise<OIDCInteractionRedirect>;
3039
+ /**
3040
+ * Remember an interaction to return to once the user has finished logging in.
3041
+ *
3042
+ * Stored in session-scoped storage rather than a query parameter, because the login
3043
+ * that follows may run several challenge steps — forced password change, email or
3044
+ * phone verification, MFA setup — each with its own URL. A query parameter does not
3045
+ * survive that; this does.
3046
+ *
3047
+ * @param uid - The pending interaction id
3048
+ */
3049
+ setPendingInteraction(uid: string): Promise<void>;
3050
+ /**
3051
+ * The interaction waiting to be resumed, if any.
3052
+ *
3053
+ * @returns The pending interaction id, or null
3054
+ */
3055
+ getPendingInteraction(): Promise<string | null>;
3056
+ /**
3057
+ * Forget the pending interaction.
3058
+ *
3059
+ * Call this once you have acted on it, so a later visit to the same page is not
3060
+ * diverted a second time.
3061
+ */
3062
+ clearPendingInteraction(): Promise<void>;
3063
+ /**
3064
+ * Take the pending interaction and forget it in one step.
3065
+ *
3066
+ * The read-then-clear a navigation handler or route guard wants: whoever gets the id
3067
+ * owns the resumption, and no one else is sent there afterwards.
3068
+ *
3069
+ * @returns The pending interaction id, or null
3070
+ */
3071
+ takePendingInteraction(): Promise<string | null>;
3072
+ private url;
3073
+ private buildHeaders;
3074
+ private getCsrfToken;
3075
+ private get;
3076
+ private post;
3077
+ private handleError;
3078
+ }
3079
+
2839
3080
  /**
2840
3081
  * Primary client for interacting with nauth-toolkit backend.
2841
3082
  */
@@ -2892,6 +3133,27 @@ declare class NAuthClient {
2892
3133
  * ```
2893
3134
  */
2894
3135
  readonly apiKeys: ApiKeyOperations;
3136
+ /**
3137
+ * OpenID Connect interaction operations (consent screen, login step, abort).
3138
+ *
3139
+ * Only meaningful when this application *is* an OpenID Connect provider — one
3140
+ * running `@nauth-toolkit/oidc-provider`. Calls the interaction routes the backend
3141
+ * mounts (default base path `{baseUrl}/oidc/interaction`; override with
3142
+ * `oidc.basePath`).
3143
+ *
3144
+ * @example
3145
+ * ```typescript
3146
+ * const state = await client.oidc.getInteraction(uid);
3147
+ * if (state.gate === 'login_required') {
3148
+ * await client.oidc.setPendingInteraction(uid);
3149
+ * router.navigate(['/login']);
3150
+ * } else {
3151
+ * const { redirectTo } = await client.oidc.approve(uid);
3152
+ * window.location.assign(redirectTo);
3153
+ * }
3154
+ * ```
3155
+ */
3156
+ readonly oidc: OIDCOperations;
2895
3157
  /**
2896
3158
  * Create a new client instance.
2897
3159
  *
@@ -3708,4 +3970,4 @@ declare class FetchAdapter implements HttpAdapter {
3708
3970
  request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
3709
3971
  }
3710
3972
 
3711
- export { type AdminAuditHistoryRequest, AdminOperations, type AdminResetPasswordRequest, type AdminResetPasswordResponse, type AdminSignupRequest, type AdminSignupResponse, type AdminSignupSocialRequest, type AdminSignupSocialResponse, type ApiKeyInfo, ApiKeyOperations, type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSessionExpiredEvent, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, type CreateApiKeyRequest, type CreateApiKeyResult, type DateFilter, type DeleteUserResponse, type DisableUserResponse, type EnableUserResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetMFADevicesResponse, type GetSetupDataRequest, type GetSetupDataResponse, type GetUserSessionsResponse, type GetUsersRequest, type GetUsersResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, type NAuthAdminEndpoints, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type RecaptchaConfig, type RecaptchaVersion, type RemoveMFADeviceResponse, type ResendCodeRequest, type ResetPasswordWithCodeRequest, type ResetPasswordWithCodeResponse, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateApiKeyRequest, type UpdateProfileRequest, type UserSessionInfo, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, apiKeyHeader, defaultAdminEndpoints, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };
3973
+ export { type AdminAuditHistoryRequest, AdminOperations, type AdminResetPasswordRequest, type AdminResetPasswordResponse, type AdminSignupRequest, type AdminSignupResponse, type AdminSignupSocialRequest, type AdminSignupSocialResponse, type ApiKeyInfo, ApiKeyOperations, type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSessionExpiredEvent, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, type CreateApiKeyRequest, type CreateApiKeyResult, DEFAULT_INTERACTION_ROUTE, type DateFilter, type DeleteUserResponse, type DisableUserResponse, type EnableUserResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetMFADevicesResponse, type GetSetupDataRequest, type GetSetupDataResponse, type GetUserSessionsResponse, type GetUsersRequest, type GetUsersResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, type NAuthAdminEndpoints, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type OIDCConsentDecision, type OIDCGateStatus, type OIDCInteractionClient, type OIDCInteractionRedirect, type OIDCInteractionState, OIDCOperations, PENDING_INTERACTION_KEY, type RecaptchaConfig, type RecaptchaVersion, type RemoveMFADeviceResponse, type ResendCodeRequest, type ResetPasswordWithCodeRequest, type ResetPasswordWithCodeResponse, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateApiKeyRequest, type UpdateProfileRequest, type UserSessionInfo, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, apiKeyHeader, defaultAdminEndpoints, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };
package/dist/index.d.ts CHANGED
@@ -469,6 +469,9 @@ declare enum NAuthErrorCode {
469
469
  PASSWORD_RESET_MAX_ATTEMPTS = "PASSWORD_RESET_MAX_ATTEMPTS",
470
470
  RATE_LIMIT_PASSWORD_RESET = "RATE_LIMIT_PASSWORD_RESET",
471
471
  SIGNIN_BLOCKED_HIGH_RISK = "SIGNIN_BLOCKED_HIGH_RISK",
472
+ OIDC_INTERACTION_NOT_FOUND = "OIDC_INTERACTION_NOT_FOUND",
473
+ OIDC_LOGIN_REQUIRED = "OIDC_LOGIN_REQUIRED",
474
+ OIDC_ACCESS_DENIED = "OIDC_ACCESS_DENIED",
472
475
  RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND",
473
476
  FORBIDDEN = "FORBIDDEN",
474
477
  INTERNAL_ERROR = "INTERNAL_ERROR",
@@ -1079,6 +1082,49 @@ interface NAuthClientConfig {
1079
1082
  */
1080
1083
  headers?: Record<string, string>;
1081
1084
  };
1085
+ /**
1086
+ * OpenID Connect interaction configuration.
1087
+ *
1088
+ * Only relevant to an application that *is* an OpenID Connect provider — one running
1089
+ * `@nauth-toolkit/oidc-provider` and hosting its own consent screen. A relying party
1090
+ * signing in with someone else's provider needs none of this.
1091
+ *
1092
+ * @example
1093
+ * ```typescript
1094
+ * const client = new NAuthClient({
1095
+ * baseUrl: 'https://api.example.com',
1096
+ * authPathPrefix: '/auth',
1097
+ * tokenDelivery: 'cookies',
1098
+ * oidc: {
1099
+ * // Only needed when the backend mounts the interaction routes somewhere
1100
+ * // other than `{baseUrl}/oidc/interaction`.
1101
+ * basePath: 'https://api.example.com/identity/interaction',
1102
+ * },
1103
+ * });
1104
+ * ```
1105
+ */
1106
+ oidc?: {
1107
+ /**
1108
+ * Base path (or absolute URL) of the backend's interaction routes.
1109
+ *
1110
+ * Must match where the provider module mounted them — `interaction.path` in
1111
+ * `OIDCProviderModule.forRoot()`, plus any global prefix.
1112
+ *
1113
+ * @default `{baseUrl}/oidc/interaction`
1114
+ */
1115
+ basePath?: string;
1116
+ /**
1117
+ * Frontend route that renders the consent screen.
1118
+ *
1119
+ * The interaction id is appended to it, so `/interaction` produces
1120
+ * `/interaction/<uid>`. This must match the route the backend's
1121
+ * `interactionUrl` sends the browser to, and is what the return guard and
1122
+ * navigation handler send a user back to after a login detour.
1123
+ *
1124
+ * @default '/interaction'
1125
+ */
1126
+ interactionPath?: string;
1127
+ };
1082
1128
  }
1083
1129
 
1084
1130
  /**
@@ -1844,6 +1890,63 @@ interface CreateApiKeyResult {
1844
1890
  apiKey: ApiKeyInfo;
1845
1891
  }
1846
1892
 
1893
+ /**
1894
+ * Types for driving an OpenID Connect interaction from the browser.
1895
+ *
1896
+ * These mirror what `@nauth-toolkit/oidc-provider`'s interaction bridge returns. They
1897
+ * are only needed by an application that hosts the consent screen for its own OpenID
1898
+ * Connect provider — a relying party signing in *with* such a provider uses an OIDC
1899
+ * client library instead.
1900
+ */
1901
+ /**
1902
+ * nauth's verdict on the session behind an interaction request.
1903
+ *
1904
+ * - `authenticated` — a completed login stands behind the request
1905
+ * - `login_required` — recoverable: send the user through login and come back
1906
+ * - `denied` — the account may not be issued credentials at all
1907
+ */
1908
+ type OIDCGateStatus = 'authenticated' | 'login_required' | 'denied';
1909
+ /** The client application an authorization request is being made on behalf of. */
1910
+ interface OIDCInteractionClient {
1911
+ /** Public client identifier. */
1912
+ clientId: string;
1913
+ /** Human-readable name, when the client registered one. */
1914
+ clientName?: string;
1915
+ /** Logo to show on the consent screen. */
1916
+ logoUri?: string;
1917
+ /** The client's home page. */
1918
+ clientUri?: string;
1919
+ }
1920
+ /** What the consent screen needs in order to ask the user. */
1921
+ interface OIDCInteractionState {
1922
+ /** The pending interaction id. */
1923
+ uid: string;
1924
+ /** What the provider is asking for: a login, or consent for scopes. */
1925
+ prompt: 'login' | 'consent' | string;
1926
+ /** The client making the request, as the user should see it. */
1927
+ client: OIDCInteractionClient;
1928
+ /** Scopes the client asked for. */
1929
+ scopes: string[];
1930
+ /** Scopes still needing consent — the rest are already granted. */
1931
+ missingScopes: string[];
1932
+ /** nauth's verdict on the current session. */
1933
+ gate: OIDCGateStatus;
1934
+ /** Why, when the gate is not `authenticated`. */
1935
+ gateReason?: string;
1936
+ /** External identifier of the signed-in user, when there is one. */
1937
+ sub?: string;
1938
+ }
1939
+ /** Where to send the browser after a decision. */
1940
+ interface OIDCInteractionRedirect {
1941
+ /** Absolute URL to navigate to. Leave the SPA — the provider takes over from here. */
1942
+ redirectTo: string;
1943
+ }
1944
+ /** The user's answer to a consent screen. */
1945
+ interface OIDCConsentDecision {
1946
+ /** A narrowed set of scopes to grant. Omit to grant everything that was asked for. */
1947
+ scopes?: string[];
1948
+ }
1949
+
1847
1950
  /**
1848
1951
  * Client-side error wrapper for SDK operations.
1849
1952
  *
@@ -2836,6 +2939,144 @@ declare class ApiKeyOperations {
2836
2939
  private handleError;
2837
2940
  }
2838
2941
 
2942
+ /** Storage key holding the interaction to return to after a login detour. */
2943
+ declare const PENDING_INTERACTION_KEY = "nauth_pending_interaction";
2944
+ /** Frontend route that renders the consent screen, when none is configured. */
2945
+ declare const DEFAULT_INTERACTION_ROUTE = "/interaction";
2946
+ /**
2947
+ * OpenID Connect interaction operations. Accessed via `client.oidc.*`.
2948
+ *
2949
+ * These drive the consent screen of an application that *is* an OpenID Connect
2950
+ * provider — one running `@nauth-toolkit/oidc-provider`. A relying party signing in
2951
+ * with someone else's provider needs none of this; use an OIDC client library.
2952
+ *
2953
+ * Calls the interaction routes your backend mounts. With NestJS those are shipped by
2954
+ * `OIDCProviderModule.forRoot()` and default to `/oidc/interaction`, which is what
2955
+ * `basePath` assumes; point `oidc.basePath` elsewhere if you moved them.
2956
+ *
2957
+ * Every method answers with a `redirectTo` rather than following a redirect itself,
2958
+ * because the browser has to leave the single-page app entirely at that point:
2959
+ * `window.location.assign(redirectTo)`, not `router.navigate`.
2960
+ *
2961
+ * @example
2962
+ * ```typescript
2963
+ * const state = await client.oidc.getInteraction(uid);
2964
+ *
2965
+ * if (state.gate === 'login_required') {
2966
+ * await client.oidc.setPendingInteraction(uid);
2967
+ * router.navigate(['/login']);
2968
+ * } else if (state.prompt === 'login') {
2969
+ * const { redirectTo } = await client.oidc.completeLogin(uid);
2970
+ * window.location.assign(redirectTo);
2971
+ * }
2972
+ * ```
2973
+ */
2974
+ declare class OIDCOperations {
2975
+ private readonly config;
2976
+ private readonly storage;
2977
+ private readonly basePath;
2978
+ /** Frontend route rendering the consent screen, with the id appended. */
2979
+ readonly interactionPath: string;
2980
+ /**
2981
+ * @param config - Resolved client configuration
2982
+ * @param storage - Ephemeral (session-scoped) storage for the pending interaction
2983
+ * @param basePath - Base path for the interaction routes (default: `{baseUrl}/oidc/interaction`)
2984
+ */
2985
+ constructor(config: ResolvedNAuthClientConfig, storage: NAuthStorageAdapter, basePath?: string);
2986
+ /**
2987
+ * The in-app route that renders the consent screen for a given interaction.
2988
+ *
2989
+ * One place for the convention, so a route guard, a navigation handler and a
2990
+ * component all agree on where the consent screen lives.
2991
+ *
2992
+ * @param uid - The pending interaction id
2993
+ * @returns A route path such as `/interaction/abc123`
2994
+ */
2995
+ interactionRoute(uid: string): string;
2996
+ /**
2997
+ * Read a pending interaction, so the page can decide what to render.
2998
+ *
2999
+ * Answers for a signed-out caller too — a `login_required` gate is precisely the
3000
+ * signal to send the user through login.
3001
+ *
3002
+ * @param uid - The pending interaction id, from the route the provider redirected to
3003
+ * @returns What the request needs, and nauth's verdict on the current session
3004
+ */
3005
+ getInteraction(uid: string): Promise<OIDCInteractionState>;
3006
+ /**
3007
+ * Complete the login step for the currently authenticated user.
3008
+ *
3009
+ * Used when `getInteraction` reports `prompt === 'login'` and the gate is
3010
+ * `authenticated`: nothing needs showing, the interaction just needs resolving.
3011
+ *
3012
+ * @param uid - The pending interaction id
3013
+ * @returns Where to send the browser to resume the authorization request
3014
+ */
3015
+ completeLogin(uid: string): Promise<OIDCInteractionRedirect>;
3016
+ /**
3017
+ * Grant the client what it asked for.
3018
+ *
3019
+ * @param uid - The pending interaction id
3020
+ * @param scopes - A narrowed set of scopes to grant; omit to grant everything asked for
3021
+ * @returns Where to send the browser next
3022
+ */
3023
+ approve(uid: string, scopes?: string[]): Promise<OIDCInteractionRedirect>;
3024
+ /**
3025
+ * Refuse the request. The client is told `access_denied`.
3026
+ *
3027
+ * @param uid - The pending interaction id
3028
+ * @returns Where to send the browser next
3029
+ */
3030
+ deny(uid: string): Promise<OIDCInteractionRedirect>;
3031
+ /**
3032
+ * Abandon a pending interaction, so the client gets a clean protocol error rather
3033
+ * than waiting on a browser tab that is never coming back.
3034
+ *
3035
+ * @param uid - The pending interaction id
3036
+ * @returns Where to send the browser
3037
+ */
3038
+ abort(uid: string): Promise<OIDCInteractionRedirect>;
3039
+ /**
3040
+ * Remember an interaction to return to once the user has finished logging in.
3041
+ *
3042
+ * Stored in session-scoped storage rather than a query parameter, because the login
3043
+ * that follows may run several challenge steps — forced password change, email or
3044
+ * phone verification, MFA setup — each with its own URL. A query parameter does not
3045
+ * survive that; this does.
3046
+ *
3047
+ * @param uid - The pending interaction id
3048
+ */
3049
+ setPendingInteraction(uid: string): Promise<void>;
3050
+ /**
3051
+ * The interaction waiting to be resumed, if any.
3052
+ *
3053
+ * @returns The pending interaction id, or null
3054
+ */
3055
+ getPendingInteraction(): Promise<string | null>;
3056
+ /**
3057
+ * Forget the pending interaction.
3058
+ *
3059
+ * Call this once you have acted on it, so a later visit to the same page is not
3060
+ * diverted a second time.
3061
+ */
3062
+ clearPendingInteraction(): Promise<void>;
3063
+ /**
3064
+ * Take the pending interaction and forget it in one step.
3065
+ *
3066
+ * The read-then-clear a navigation handler or route guard wants: whoever gets the id
3067
+ * owns the resumption, and no one else is sent there afterwards.
3068
+ *
3069
+ * @returns The pending interaction id, or null
3070
+ */
3071
+ takePendingInteraction(): Promise<string | null>;
3072
+ private url;
3073
+ private buildHeaders;
3074
+ private getCsrfToken;
3075
+ private get;
3076
+ private post;
3077
+ private handleError;
3078
+ }
3079
+
2839
3080
  /**
2840
3081
  * Primary client for interacting with nauth-toolkit backend.
2841
3082
  */
@@ -2892,6 +3133,27 @@ declare class NAuthClient {
2892
3133
  * ```
2893
3134
  */
2894
3135
  readonly apiKeys: ApiKeyOperations;
3136
+ /**
3137
+ * OpenID Connect interaction operations (consent screen, login step, abort).
3138
+ *
3139
+ * Only meaningful when this application *is* an OpenID Connect provider — one
3140
+ * running `@nauth-toolkit/oidc-provider`. Calls the interaction routes the backend
3141
+ * mounts (default base path `{baseUrl}/oidc/interaction`; override with
3142
+ * `oidc.basePath`).
3143
+ *
3144
+ * @example
3145
+ * ```typescript
3146
+ * const state = await client.oidc.getInteraction(uid);
3147
+ * if (state.gate === 'login_required') {
3148
+ * await client.oidc.setPendingInteraction(uid);
3149
+ * router.navigate(['/login']);
3150
+ * } else {
3151
+ * const { redirectTo } = await client.oidc.approve(uid);
3152
+ * window.location.assign(redirectTo);
3153
+ * }
3154
+ * ```
3155
+ */
3156
+ readonly oidc: OIDCOperations;
2895
3157
  /**
2896
3158
  * Create a new client instance.
2897
3159
  *
@@ -3708,4 +3970,4 @@ declare class FetchAdapter implements HttpAdapter {
3708
3970
  request<T>(config: HttpRequest): Promise<HttpResponse<T>>;
3709
3971
  }
3710
3972
 
3711
- export { type AdminAuditHistoryRequest, AdminOperations, type AdminResetPasswordRequest, type AdminResetPasswordResponse, type AdminSignupRequest, type AdminSignupResponse, type AdminSignupSocialRequest, type AdminSignupSocialResponse, type ApiKeyInfo, ApiKeyOperations, type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSessionExpiredEvent, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, type CreateApiKeyRequest, type CreateApiKeyResult, type DateFilter, type DeleteUserResponse, type DisableUserResponse, type EnableUserResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetMFADevicesResponse, type GetSetupDataRequest, type GetSetupDataResponse, type GetUserSessionsResponse, type GetUsersRequest, type GetUsersResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, type NAuthAdminEndpoints, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type RecaptchaConfig, type RecaptchaVersion, type RemoveMFADeviceResponse, type ResendCodeRequest, type ResetPasswordWithCodeRequest, type ResetPasswordWithCodeResponse, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateApiKeyRequest, type UpdateProfileRequest, type UserSessionInfo, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, apiKeyHeader, defaultAdminEndpoints, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };
3973
+ export { type AdminAuditHistoryRequest, AdminOperations, type AdminResetPasswordRequest, type AdminResetPasswordResponse, type AdminSignupRequest, type AdminSignupResponse, type AdminSignupSocialRequest, type AdminSignupSocialResponse, type ApiKeyInfo, ApiKeyOperations, type AuditHistoryResponse, type AuthAuditEvent, type AuthAuditEventStatus, AuthAuditEventType, AuthChallenge, type AuthChallengeEvent, type AuthErrorEvent, type AuthEvent, type AuthEventListener, type AuthEventType, type AuthLoginEvent, type AuthLogoutEvent, type AuthRefreshEvent, type AuthResponse, type AuthResponseContext, type AuthSessionExpiredEvent, type AuthSignupEvent, type AuthSuccessEvent, type AuthUser, type AuthUserSummary, type BackupCodesResponse, type BaseChallengeResponse, BrowserStorage, type ChallengeResponse, ChallengeRouter, type ChangePasswordRequest, type ConfirmForgotPasswordRequest, type ConfirmForgotPasswordResponse, type CreateApiKeyRequest, type CreateApiKeyResult, DEFAULT_INTERACTION_ROUTE, type DateFilter, type DeleteUserResponse, type DisableUserResponse, type EnableUserResponse, EventEmitter, FetchAdapter, type ForceChangePasswordResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GetChallengeDataRequest, type GetChallengeDataResponse, type GetMFADevicesResponse, type GetSetupDataRequest, type GetSetupDataResponse, type GetUserSessionsResponse, type GetUsersRequest, type GetUsersResponse, type HttpAdapter, type HttpRequest, type HttpResponse, InMemoryStorage, type LinkedAccountsResponse, type LoginRequest, type LogoutAllRequest, type LogoutRequest, type MFAChallengeMethod, type MFACodeResponse, type MFADevice, type MFADeviceMethod, type MFAMethod, type MFAPasskeyResponse, type MFASetupData, type MFASetupResponse, type MFAStatus, type MfaRoutesConfig, type NAuthAdminEndpoints, NAuthClient, type NAuthClientConfig, NAuthClientError, type NAuthEndpoints, type NAuthError, NAuthErrorCode, type NAuthRedirectsConfig, type NAuthStorageAdapter, type OAuthCallbackEvent, type OAuthCompletedEvent, type OAuthErrorEvent, type OAuthStartedEvent, type OIDCConsentDecision, type OIDCGateStatus, type OIDCInteractionClient, type OIDCInteractionRedirect, type OIDCInteractionState, OIDCOperations, PENDING_INTERACTION_KEY, type RecaptchaConfig, type RecaptchaVersion, type RemoveMFADeviceResponse, type ResendCodeRequest, type ResetPasswordWithCodeRequest, type ResetPasswordWithCodeResponse, type ResolvedNAuthClientConfig, type SignupRequest, type SocialLoginOptions, type SocialProvider, type SocialVerifyRequest, type TokenDeliveryMode, type TokenResponse, type UpdateApiKeyRequest, type UpdateProfileRequest, type UserSessionInfo, type VerifyEmailResponse, type VerifyPhoneCodeResponse, type VerifyPhoneCollectResponse, apiKeyHeader, defaultAdminEndpoints, defaultEndpoints, getChallengeInstructions, getMFAMethod, getMaskedDestination, isOTPChallenge, requiresPhoneCollection, resolveConfig };