@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 window.localStorage; provide a custom implementation (or false for memory-only) via the Auth constructor options.

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

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: {},
});
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
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"
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"
getDefaultRole()

Returns the default role assigned to newly authenticated users.

isValidRole(string)

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".