@microsoft/rayfin-auth package
Classes
| Auth |
The main Auth module class. This provides the high-level API for authentication operations and manages the user session. |
| AuthApi |
Manages all authentication-related API interactions. |
Interfaces
| AuthOptions | |
| AuthSettingsConfig |
Auth settings configuration returned by getAuthSettings(). Derived from project runtime settings endpoint. Use this to dynamically configure UI based on enabled auth methods. |
| AuthStorage |
Storage interface used by Auth to persist the session (and PKCE state)
across page loads. Defaults to |
| CompletePasswordResetRequest |
Request payload for completing password reset. |
| EmailVerificationResponse |
Response from email verification. |
| JsonWebKey |
JSON Web Key (JWK) object per RFC 7517. Represents a cryptographic key in JSON format. |
| JwksResponse |
JWKS (JSON Web Key Set) response per RFC 7517. Contains public keys for JWT signature verification. |
| MagicLinkCallbackResult |
Result from handling a magic link callback. |
| MagicLinkOptions |
Options for initiating a magic link authentication flow. |
| MagicLinkRequest |
Request payload for sending a magic link (matches backend MagicLinkRequest). |
| MagicLinkResponse |
Response from magic link send endpoint. |
| MagicLinkResult |
Result from initiating a magic link request. Contains the state parameter needed to correlate the callback. |
| OpaqueSession |
Public opaque session surface returned to app code. Raw tokens are concealed internally by the Auth SDK. |
| PasswordGrantCredentials |
Credentials for password grant token issuance (ROPC authentication). |
| PasswordResetRequest |
Request payload for password reset. |
| PasswordResetResponse |
Response from password reset request. |
| PkceState |
PKCE state stored in localStorage during magic link flow. Uses localStorage instead of sessionStorage to support cross-tab flows (e.g., user clicks magic link in email which opens in a new tab). Keyed by state parameter to support concurrent requests. |
| ResendVerificationEmailRequest |
Request payload for resending email verification. |
| ResendVerificationEmailResponse |
Response from resend verification email request. |
| Session |
Represents an authenticated session, containing user information and tokens. |
| SignOutAllResponse |
Response from the signout-all endpoint. Indicates how many sessions were invalidated. |
| SignUpCredentials |
Credentials for user sign up. After signup, clients must call signIn() to obtain an access token. |
| SignUpResponse |
Response from the /signup endpoint. Matches backend SignUpResponse model. Note: No token is issued at signup. Clients must call signIn() with grant_type=password to obtain an access token. |
| TokenResponse |
OAuth 2.1 token response per RFC 6749. Returned by the /token endpoint for all grant types. Matches backend TokenResponse model. |
| User |
Represents a user object. |
| VerificationCodeExchangeRequest |
Request payload for exchanging a verification code for tokens. Used in the magic link callback flow. |
Type Aliases
| AuthEvent |
Auth event names emitted by the SDK |
| AuthMethod |
Authentication methods supported by Rayfin. |
| RayfinUserRole |
User role types matching backend UserRole enum. Backend supports: "Anonymous" and "Authenticated" (PascalCase). |
Functions
| browser |
Select browser-session authentication for a composed Rayfin client. Storage, refresh, multi-tab synchronization, and companion providers retain the behavior of Auth. Disposing the client releases auth resources without signing out or removing the persisted session. Already-issued refreshes may finish and persist rotated credentials; disposal does not wait for them or allow new refresh grants. Example
|
| generate |
Generates a code challenge from a code verifier using SHA-256. The challenge is the Base64URL-encoded SHA-256 hash of the verifier. Example
|
| generate |
Generates a cryptographically random code verifier for PKCE. The verifier is a Base64URL-encoded string of 32 random bytes (43 characters). Example
|
| generate |
Generates a cryptographically random state parameter for OAuth flows. The state is a Base64URL-encoded string of 16 random bytes (22 characters). Used to prevent CSRF attacks and to correlate requests with responses. Example
|
| get |
Returns the default role assigned to newly authenticated users. |
| is |
Returns whether the given string is a valid RayfinUserRole. |
Function Details
browserSession(AuthOptions)
Select browser-session authentication for a composed Rayfin client. Storage, refresh, multi-tab synchronization, and companion providers retain the behavior of Auth. Disposing the client releases auth resources without signing out or removing the persisted session. Already-issued refreshes may finish and persist rotated credentials; disposal does not wait for them or allow new refresh grants.
Example
const client = RayfinClient.create({
baseUrl: '',
publishableKey: 'pk-your-key',
auth: browserSession({ storage: true }),
services: {},
});
function browserSession(options?: AuthOptions): ClientAuthFactory<Auth>
Parameters
- options
- AuthOptions
Session storage and refresh options.
Returns
A factory that attaches and exposes the client's session API.
generateCodeChallenge(string)
Generates a code challenge from a code verifier using SHA-256. The challenge is the Base64URL-encoded SHA-256 hash of the verifier.
Example
const verifier = generateCodeVerifier();
const challenge = await generateCodeChallenge(verifier);
// Send challenge to server, keep verifier secret
function generateCodeChallenge(verifier: string): Promise<string>
Parameters
- verifier
-
string
The code verifier to hash.
Returns
Promise<string>
A promise that resolves with the code challenge string.
generateCodeVerifier()
Generates a cryptographically random code verifier for PKCE. The verifier is a Base64URL-encoded string of 32 random bytes (43 characters).
Example
const verifier = generateCodeVerifier();
// e.g., "dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
function generateCodeVerifier(): string
Returns
string
A random code verifier string.
generateState()
Generates a cryptographically random state parameter for OAuth flows. The state is a Base64URL-encoded string of 16 random bytes (22 characters).
Used to prevent CSRF attacks and to correlate requests with responses.
Example
const state = generateState();
// e.g., "xyzzy123ABC_def-GHI"
function generateState(): string
Returns
string
A random state string.
getDefaultRole()
Returns the default role assigned to newly authenticated users.
function getDefaultRole(): RayfinUserRole
Returns
The default role, "Authenticated".
isValidRole(string)
Returns whether the given string is a valid RayfinUserRole.
function isValidRole(role: string): role is RayfinUserRole
Parameters
- role
-
string
The role string to validate.
Returns
role is RayfinUserRole
true (narrowing to RayfinUserRole) if the value is "Anonymous" or "Authenticated".