@drmhse/sso-sdk 0.5.1 → 0.5.3

package/README.md

@@ -7,7 +7,7 @@ Core TypeScript SDK for AuthOS. It handles authentication flows, session persist
 
 Full documentation: [authos.dev/docs/sdk/](https://authos.dev/docs/sdk/)
 
-AI agent skills: [authos.dev/docs/ai-agent-skills/](https://authos.dev/docs/ai-agent-skills/) and [github.com/CkCreative/authos_skill](https://github.com/CkCreative/authos_skill)
+AI agent skills: [authos.dev/docs/ai-agent-skills/](https://authos.dev/docs/ai-agent-skills/) and [github.com/drmhse/authos_skill](https://github.com/drmhse/authos_skill)
 
 ## Install
 
@@ -47,16 +47,30 @@ const sso = new SsoClient({ baseURL: 'https://sso.example.com' });
 
 ### Tenant application
 
-Pass organization and service context when you need hosted auth, BYOO, or service-scoped tokens:
+Redirect users to AuthOS hosted login for the standard web flow. AuthOS handles provider selection, HRD, password, magic link, passkeys, MFA, and recovery before returning tokens to your callback:
 
 ```ts
-const loginUrl = sso.auth.getLoginUrl('github', {
+const loginUrl = sso.auth.getAuthorizeUrl({
   org: 'acme-corp',
   service: 'main-app',
   redirect_uri: 'https://app.acme.com/callback',
 });
 ```
 
+Use `getLoginUrl(provider, ...)` only when you are intentionally building a custom provider-selection flow.
+
+### Account security
+
+Send users to the hosted account-security portal to manage MFA, passkeys, backup codes, and trusted devices on the AuthOS origin:
+
+```ts
+const securityUrl = sso.auth.getAccountSecurityUrl({
+  org: 'acme-corp',
+  service: 'main-app',
+  return_to: 'https://app.acme.com/settings',
+});
+```
+
 ### Hosted auth context
 
 ```ts

package/dist/index.d.mts

@@ -254,6 +254,10 @@ interface LoginUrlParams {
      * Optional redirect URI (must be registered with the service)
      */
     redirect_uri?: string;
+    /**
+     * Optional caller state to return to the service callback.
+     */
+    state?: string;
     /**
      * Optional user code for device flow authorization
      */
@@ -265,6 +269,44 @@ interface LoginUrlParams {
      */
     connection_id?: string;
 }
+/**
+ * Parameters for constructing the hosted AuthOS login URL.
+ */
+interface AuthorizeUrlParams {
+    /**
+     * Organization slug
+     */
+    org: string;
+    /**
+     * Service slug
+     */
+    service: string;
+    /**
+     * Callback URI registered with the service
+     */
+    redirect_uri: string;
+    /**
+     * Optional caller state to return to the service callback.
+     */
+    state?: string;
+}
+/**
+ * Parameters for constructing the hosted account-security URL.
+ */
+interface AccountSecurityUrlParams {
+    /**
+     * Optional organization slug for tenant-aware branding/context
+     */
+    org?: string;
+    /**
+     * Optional service slug for application context
+     */
+    service?: string;
+    /**
+     * Optional URL to return to after managing account security
+     */
+    return_to?: string;
+}
 /**
  * Parameters for constructing admin login URL
  */
@@ -277,6 +319,10 @@ interface AdminLoginUrlParams {
      * Optional user code for device flow authorization
      */
     user_code?: string;
+    /**
+     * Optional internal Lite client path to return to after admin OAuth.
+     */
+    return_to?: string;
 }
 /**
  * Provider token response
@@ -327,6 +373,10 @@ interface RegisterRequest {
      * Optional service callback URI to preserve the original app return path in the verification link.
      */
     redirect_uri?: string;
+    /**
+     * Optional caller state to return to hosted service callbacks.
+     */
+    state?: string;
 }
 /**
  * Registration response
@@ -357,6 +407,10 @@ interface LoginRequest {
      * against the service before tokens are returned to the hosted UI.
      */
     redirect_uri?: string;
+    /**
+     * Optional caller state to return to hosted service callbacks.
+     */
+    state?: string;
 }
 /**
  * Forgot password request payload
@@ -366,6 +420,7 @@ interface ForgotPasswordRequest {
     org_slug?: string;
     service_slug?: string;
     redirect_uri?: string;
+    state?: string;
 }
 /**
  * Forgot password response
@@ -394,6 +449,7 @@ interface ResendVerificationRequest {
     org_slug?: string;
     service_slug?: string;
     redirect_uri?: string;
+    state?: string;
 }
 /**
  * Resend verification response
@@ -1156,6 +1212,7 @@ interface Service {
     google_scopes: string[];
     redirect_uris: string[];
     device_activation_uri?: string;
+    resource_uris?: string[];
     saml_enabled: boolean;
     saml_entity_id?: string;
     saml_acs_url?: string;
@@ -1224,6 +1281,7 @@ interface CreateServicePayload {
     google_scopes?: string[];
     redirect_uris: string[];
     device_activation_uri?: string;
+    resource_uris?: string[];
 }
 /**
  * Create service response
@@ -1252,6 +1310,7 @@ interface UpdateServicePayload {
     google_scopes?: string[];
     redirect_uris?: string[];
     device_activation_uri?: string;
+    resource_uris?: string[];
 }
 /**
  * Service with aggregated details (for listing)
@@ -1774,6 +1833,7 @@ interface PasskeyAuthStartRequest {
     org_slug?: string;
     service_slug?: string;
     redirect_uri?: string;
+    state?: string;
 }
 /**
  * Response from starting passkey authentication
@@ -2086,6 +2146,7 @@ interface UpdateUpstreamProviderPayload {
 interface SessionConfig {
     storageKeyPrefix?: string;
     autoRefresh?: boolean;
+    minValiditySeconds?: number;
 }
 /**
  * Snapshot of the current authentication state.
@@ -2102,6 +2163,7 @@ declare class SessionManager {
     private accessToken;
     private refreshToken;
     private refreshPromise;
+    private sessionVersion;
     private listeners;
     constructor(storage: TokenStorage, refreshHandler: (token: string) => Promise<RefreshTokenResponse>, config?: SessionConfig);
     /**
@@ -2303,6 +2365,32 @@ declare class AuthModule {
     private http;
     private session;
     constructor(http: HttpClient, session: SessionManager);
+    /**
+     * Constructs the hosted AuthOS login URL for an end-user application.
+     * AuthOS owns provider selection, HRD, password, magic-link, passkey, MFA,
+     * recovery, and callback token delivery for this flow.
+     *
+     * @param params Hosted authorize parameters (org, service, redirect_uri)
+     * @returns The full URL to redirect the user to
+     *
+     * @example
+     * ```typescript
+     * window.location.href = sso.auth.getAuthorizeUrl({
+     *   org: 'acme-corp',
+     *   service: 'main-app',
+     *   redirect_uri: 'https://app.acme.com/callback'
+     * });
+     * ```
+     */
+    getAuthorizeUrl(params: AuthorizeUrlParams): string;
+    /**
+     * Constructs the hosted account-security URL for managing user factors.
+     * Use this for AuthOS-owned MFA, passkeys, backup codes, and trusted devices.
+     *
+     * @param params Optional tenant/application context and return URL
+     * @returns The full URL to open for account security management
+     */
+    getAccountSecurityUrl(params?: AccountSecurityUrlParams): string;
     /**
      * Constructs the OAuth login URL for end-users.
      * This does not perform the redirect; the consuming application
@@ -5649,6 +5737,7 @@ declare class PasskeysModule {
         org_slug?: string;
         service_slug?: string;
         redirect_uri?: string;
+        state?: string;
     }): Promise<PasskeyAuthStartResponse>;
     /**
      * Finish the passkey authentication ceremony.
@@ -5663,6 +5752,7 @@ declare class PasskeysModule {
         org_slug?: string;
         service_slug?: string;
         redirect_uri?: string;
+        state?: string;
     }): Promise<PasskeyAuthFinishResponse>;
     /**
      * Convert Base64URL string to Uint8Array
@@ -5687,6 +5777,8 @@ interface MagicLinkRequest {
     service_slug?: string;
     /** Optional service callback URI */
     redirect_uri?: string;
+    /** Optional caller state to return to hosted service callbacks */
+    state?: string;
 }
 /**
  * Magic link response
@@ -5717,7 +5809,7 @@ declare class MagicLinks {
      * @param redirectUri Optional where to redirect after success
      * @returns URL to redirect to for verification
      */
-    getVerificationUrl(token: string, redirectUri?: string): string;
+    getVerificationUrl(token: string, redirectUri?: string, state?: string): string;
     /**
      * Verify a magic link token via API call
      * This is an alternative to redirect-based verification
@@ -5726,7 +5818,7 @@ declare class MagicLinks {
      * @param redirectUri Optional redirect URI
      * @returns Promise resolving to authentication response
      */
-    verify(token: string, redirectUri?: string): Promise<any>;
+    verify(token: string, redirectUri?: string, state?: string): Promise<any>;
     /**
      * Construct the complete magic link URL that would be sent via email
      *
@@ -5734,7 +5826,7 @@ declare class MagicLinks {
      * @param redirectUri Optional redirect URI
      * @returns Complete magic link URL
      */
-    constructMagicLink(token: string, redirectUri?: string): string;
+    constructMagicLink(token: string, redirectUri?: string, state?: string): string;
 }
 
 /**
@@ -5806,6 +5898,10 @@ interface SsoClientOptions {
      * Prefix for storage keys. Default: 'sso_'
      */
     storagePrefix?: string;
+    /**
+     * Refresh access tokens this many seconds before expiry. Default: 30.
+     */
+    tokenRefreshMinValiditySeconds?: number;
 }
 /**
  * Main SSO client class.
@@ -6087,4 +6183,4 @@ declare class SsoApiError extends Error {
     isNotFound(): boolean;
 }
 
-export { type AcceptInvitationPayload, type AdminLoginUrlParams, type AnalyticsQuery, type ApiKey, type ApiKeyCreateResponse, type ApproveOrganizationPayload, type AuditLog, type AuditLogEntry, type AuditLogQueryParams, type AuditLogResponse, type AuthContextRequest, type AuthContextResponse, AuthErrorCodes, AuthModule, type AuthOrganizationContext, type AuthServiceContext, type AuthSnapshot, type AuthenticationResponseJSON, type BackupCodesResponse, type BrandingConfiguration, BrowserStorage, type ChangePasswordRequest, type ChangePasswordResponse, type CompleteProviderTokenRequestPayload, type CompleteProviderTokenRequestResponse, type ConfigureSamlPayload, type ConfigureSamlResponse, CookieStorage, type CreateApiKeyPayload, type CreateCheckoutPayload, type CreateCheckoutResponse, type CreateInvitationPayload, type CreateOrganizationPayload, type CreateOrganizationResponse, type CreatePlanPayload, type CreateRoleRequest, type CreateScimTokenRequest, type CreateServicePayload, type CreateServiceResponse, type CreateSiemConfigRequest, type CreateUpstreamProviderPayload, type CreateWebhookRequest, type DeclineInvitationPayload, type DeviceCodeRequest, type DeviceCodeResponse, type DeviceVerifyResponse, type DomainConfiguration, type DomainVerificationMethod, type DomainVerificationResponse, type DomainVerificationResult, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserLoginEvent, type EndUserSession, type EndUserSubscription, type EventTypeInfo, type ExportUserDataResponse, type ForgetUserRequest, type ForgetUserResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GeoLocation, type GetAuditLogParams, type GetRiskSettingsResponse, type GrantLinkedAccountRequest, type GrowthTrendPoint, type Identity, type ImpersonateRequest, type ImpersonateResponse, type ImpersonationUserInfo, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type LinkedAccount, type LinkedAccountGrant, type LinkedAccountsResponse, type ListApiKeysResponse, type ListDevicesResponse, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type ListScimTokensResponse, type ListSiemConfigsResponse, type LoginActivityPoint, type LoginEventExport, type LoginRequest, type LoginTrendPoint, type LoginUrlParams, type LoginsByProvider, type LoginsByService, type LookupEmailRequest, type LookupEmailResponse, MagicLinks, type MemberListResponse, type MemberRole, type MemberServiceAccess, type Membership, type MembershipExport, MemoryStorage, type MfaEventExport, type MfaSetupResponse, type MfaStatusResponse, type MfaVerificationRequest, type MfaVerificationResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OAuthCredentials, type OAuthIdentityExport, type OAuthProvider, type Organization, type OrganizationMember, type OrganizationResponse, type OrganizationStatus, type OrganizationStatusBreakdown, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationInfo, type PaginationParams, type Passkey, type PasskeyActionResponse, type PasskeyAuthFinishRequest, type PasskeyAuthFinishResponse, type PasskeyAuthStartRequest, type PasskeyAuthStartResponse, type PasskeyExport, type PasskeyRegisterFinishRequest, type PasskeyRegisterFinishResponse, type PasskeyRegisterStartRequest, type PasskeyRegisterStartResponse, PasskeysModule, PermissionsModule, type Plan, type PlanResponse, type PlatformAnalyticsDateRangeParams, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PlatformOverviewMetrics, type PlatformUser, type PlatformUserListResponse, type PromotePlatformOwnerPayload, type ProviderDefinition, type ProviderToken, type ProviderTokenRequestDetails, type RecentLogin, type RecentOrganization, type RefreshTokenRequest, type RefreshTokenResponse, type RegisterRequest, type RegisterResponse, type RegistrationResponseJSON, type RejectOrganizationPayload, type ResendVerificationRequest, type ResendVerificationResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDeviceRequest, type RevokeDeviceResponse, type RevokeSessionsResponse, type RiskAction, type RiskAssessment, type RiskEventResponse, type RiskEventsQuery, type RoleResponse, type RotateServiceSecretResponse, type SamlCertificate, type SamlConfig, type ScimTokenResponse, type SelectOrganizationResponse, type Service, ServiceApiModule, type ServiceListResponse, type ServiceType, type ServiceWithDetails, ServicesModule, type SetCustomDomainRequest, type SetOAuthCredentialsPayload, type SetPasswordRequest, type SetPasswordResponse, type SetSmtpRequest, type SiemConfigResponse, type SiemProviderType, type SmtpConfigResponse, SsoApiError, SsoClient, type SsoClientOptions, type StartLinkResponse, type Subscription, type TestConnectionResponse, type TokenRequest, type TokenResponse, type TokenStorage, type TopOrganization, type TransferOwnershipPayload, type UpdateBrandingRequest, type UpdateMemberRolePayload, type UpdateMemberServiceAccessPayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdatePlanPayload, type UpdateRiskSettingsRequest, type UpdateRiskSettingsResponse, type UpdateRoleRequest, type UpdateServicePayload, type UpdateSiemConfigRequest, type UpdateUpstreamProviderPayload, type UpdateUserProfilePayload, type UpdateWebhookRequest, type UpstreamProvider, type UpstreamProviderType, type User, type UserDevice, UserModule, type UserPasskey, type UserProfile, type Webhook, type WebhookDelivery, type WebhookDeliveryListResponse, type WebhookDeliveryQueryParams, type WebhookListResponse, type WebhookResponse };
+export { type AcceptInvitationPayload, type AccountSecurityUrlParams, type AdminLoginUrlParams, type AnalyticsQuery, type ApiKey, type ApiKeyCreateResponse, type ApproveOrganizationPayload, type AuditLog, type AuditLogEntry, type AuditLogQueryParams, type AuditLogResponse, type AuthContextRequest, type AuthContextResponse, AuthErrorCodes, AuthModule, type AuthOrganizationContext, type AuthServiceContext, type AuthSnapshot, type AuthenticationResponseJSON, type AuthorizeUrlParams, type BackupCodesResponse, type BrandingConfiguration, BrowserStorage, type ChangePasswordRequest, type ChangePasswordResponse, type CompleteProviderTokenRequestPayload, type CompleteProviderTokenRequestResponse, type ConfigureSamlPayload, type ConfigureSamlResponse, CookieStorage, type CreateApiKeyPayload, type CreateCheckoutPayload, type CreateCheckoutResponse, type CreateInvitationPayload, type CreateOrganizationPayload, type CreateOrganizationResponse, type CreatePlanPayload, type CreateRoleRequest, type CreateScimTokenRequest, type CreateServicePayload, type CreateServiceResponse, type CreateSiemConfigRequest, type CreateUpstreamProviderPayload, type CreateWebhookRequest, type DeclineInvitationPayload, type DeviceCodeRequest, type DeviceCodeResponse, type DeviceVerifyResponse, type DomainConfiguration, type DomainVerificationMethod, type DomainVerificationResponse, type DomainVerificationResult, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserLoginEvent, type EndUserSession, type EndUserSubscription, type EventTypeInfo, type ExportUserDataResponse, type ForgetUserRequest, type ForgetUserResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GeoLocation, type GetAuditLogParams, type GetRiskSettingsResponse, type GrantLinkedAccountRequest, type GrowthTrendPoint, type Identity, type ImpersonateRequest, type ImpersonateResponse, type ImpersonationUserInfo, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type LinkedAccount, type LinkedAccountGrant, type LinkedAccountsResponse, type ListApiKeysResponse, type ListDevicesResponse, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type ListScimTokensResponse, type ListSiemConfigsResponse, type LoginActivityPoint, type LoginEventExport, type LoginRequest, type LoginTrendPoint, type LoginUrlParams, type LoginsByProvider, type LoginsByService, type LookupEmailRequest, type LookupEmailResponse, MagicLinks, type MemberListResponse, type MemberRole, type MemberServiceAccess, type Membership, type MembershipExport, MemoryStorage, type MfaEventExport, type MfaSetupResponse, type MfaStatusResponse, type MfaVerificationRequest, type MfaVerificationResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OAuthCredentials, type OAuthIdentityExport, type OAuthProvider, type Organization, type OrganizationMember, type OrganizationResponse, type OrganizationStatus, type OrganizationStatusBreakdown, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationInfo, type PaginationParams, type Passkey, type PasskeyActionResponse, type PasskeyAuthFinishRequest, type PasskeyAuthFinishResponse, type PasskeyAuthStartRequest, type PasskeyAuthStartResponse, type PasskeyExport, type PasskeyRegisterFinishRequest, type PasskeyRegisterFinishResponse, type PasskeyRegisterStartRequest, type PasskeyRegisterStartResponse, PasskeysModule, PermissionsModule, type Plan, type PlanResponse, type PlatformAnalyticsDateRangeParams, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PlatformOverviewMetrics, type PlatformUser, type PlatformUserListResponse, type PromotePlatformOwnerPayload, type ProviderDefinition, type ProviderToken, type ProviderTokenRequestDetails, type RecentLogin, type RecentOrganization, type RefreshTokenRequest, type RefreshTokenResponse, type RegisterRequest, type RegisterResponse, type RegistrationResponseJSON, type RejectOrganizationPayload, type ResendVerificationRequest, type ResendVerificationResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDeviceRequest, type RevokeDeviceResponse, type RevokeSessionsResponse, type RiskAction, type RiskAssessment, type RiskEventResponse, type RiskEventsQuery, type RoleResponse, type RotateServiceSecretResponse, type SamlCertificate, type SamlConfig, type ScimTokenResponse, type SelectOrganizationResponse, type Service, ServiceApiModule, type ServiceListResponse, type ServiceType, type ServiceWithDetails, ServicesModule, SessionManager, type SetCustomDomainRequest, type SetOAuthCredentialsPayload, type SetPasswordRequest, type SetPasswordResponse, type SetSmtpRequest, type SiemConfigResponse, type SiemProviderType, type SmtpConfigResponse, SsoApiError, SsoClient, type SsoClientOptions, type StartLinkResponse, type Subscription, type TestConnectionResponse, type TokenRequest, type TokenResponse, type TokenStorage, type TopOrganization, type TransferOwnershipPayload, type UpdateBrandingRequest, type UpdateMemberRolePayload, type UpdateMemberServiceAccessPayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdatePlanPayload, type UpdateRiskSettingsRequest, type UpdateRiskSettingsResponse, type UpdateRoleRequest, type UpdateServicePayload, type UpdateSiemConfigRequest, type UpdateUpstreamProviderPayload, type UpdateUserProfilePayload, type UpdateWebhookRequest, type UpstreamProvider, type UpstreamProviderType, type User, type UserDevice, UserModule, type UserPasskey, type UserProfile, type Webhook, type WebhookDelivery, type WebhookDeliveryListResponse, type WebhookDeliveryQueryParams, type WebhookListResponse, type WebhookResponse };

package/dist/index.d.ts

@@ -254,6 +254,10 @@ interface LoginUrlParams {
      * Optional redirect URI (must be registered with the service)
      */
     redirect_uri?: string;
+    /**
+     * Optional caller state to return to the service callback.
+     */
+    state?: string;
     /**
      * Optional user code for device flow authorization
      */
@@ -265,6 +269,44 @@ interface LoginUrlParams {
      */
     connection_id?: string;
 }
+/**
+ * Parameters for constructing the hosted AuthOS login URL.
+ */
+interface AuthorizeUrlParams {
+    /**
+     * Organization slug
+     */
+    org: string;
+    /**
+     * Service slug
+     */
+    service: string;
+    /**
+     * Callback URI registered with the service
+     */
+    redirect_uri: string;
+    /**
+     * Optional caller state to return to the service callback.
+     */
+    state?: string;
+}
+/**
+ * Parameters for constructing the hosted account-security URL.
+ */
+interface AccountSecurityUrlParams {
+    /**
+     * Optional organization slug for tenant-aware branding/context
+     */
+    org?: string;
+    /**
+     * Optional service slug for application context
+     */
+    service?: string;
+    /**
+     * Optional URL to return to after managing account security
+     */
+    return_to?: string;
+}
 /**
  * Parameters for constructing admin login URL
  */
@@ -277,6 +319,10 @@ interface AdminLoginUrlParams {
      * Optional user code for device flow authorization
      */
     user_code?: string;
+    /**
+     * Optional internal Lite client path to return to after admin OAuth.
+     */
+    return_to?: string;
 }
 /**
  * Provider token response
@@ -327,6 +373,10 @@ interface RegisterRequest {
      * Optional service callback URI to preserve the original app return path in the verification link.
      */
     redirect_uri?: string;
+    /**
+     * Optional caller state to return to hosted service callbacks.
+     */
+    state?: string;
 }
 /**
  * Registration response
@@ -357,6 +407,10 @@ interface LoginRequest {
      * against the service before tokens are returned to the hosted UI.
      */
     redirect_uri?: string;
+    /**
+     * Optional caller state to return to hosted service callbacks.
+     */
+    state?: string;
 }
 /**
  * Forgot password request payload
@@ -366,6 +420,7 @@ interface ForgotPasswordRequest {
     org_slug?: string;
     service_slug?: string;
     redirect_uri?: string;
+    state?: string;
 }
 /**
  * Forgot password response
@@ -394,6 +449,7 @@ interface ResendVerificationRequest {
     org_slug?: string;
     service_slug?: string;
     redirect_uri?: string;
+    state?: string;
 }
 /**
  * Resend verification response
@@ -1156,6 +1212,7 @@ interface Service {
     google_scopes: string[];
     redirect_uris: string[];
     device_activation_uri?: string;
+    resource_uris?: string[];
     saml_enabled: boolean;
     saml_entity_id?: string;
     saml_acs_url?: string;
@@ -1224,6 +1281,7 @@ interface CreateServicePayload {
     google_scopes?: string[];
     redirect_uris: string[];
     device_activation_uri?: string;
+    resource_uris?: string[];
 }
 /**
  * Create service response
@@ -1252,6 +1310,7 @@ interface UpdateServicePayload {
     google_scopes?: string[];
     redirect_uris?: string[];
     device_activation_uri?: string;
+    resource_uris?: string[];
 }
 /**
  * Service with aggregated details (for listing)
@@ -1774,6 +1833,7 @@ interface PasskeyAuthStartRequest {
     org_slug?: string;
     service_slug?: string;
     redirect_uri?: string;
+    state?: string;
 }
 /**
  * Response from starting passkey authentication
@@ -2086,6 +2146,7 @@ interface UpdateUpstreamProviderPayload {
 interface SessionConfig {
     storageKeyPrefix?: string;
     autoRefresh?: boolean;
+    minValiditySeconds?: number;
 }
 /**
  * Snapshot of the current authentication state.
@@ -2102,6 +2163,7 @@ declare class SessionManager {
     private accessToken;
     private refreshToken;
     private refreshPromise;
+    private sessionVersion;
     private listeners;
     constructor(storage: TokenStorage, refreshHandler: (token: string) => Promise<RefreshTokenResponse>, config?: SessionConfig);
     /**
@@ -2303,6 +2365,32 @@ declare class AuthModule {
     private http;
     private session;
     constructor(http: HttpClient, session: SessionManager);
+    /**
+     * Constructs the hosted AuthOS login URL for an end-user application.
+     * AuthOS owns provider selection, HRD, password, magic-link, passkey, MFA,
+     * recovery, and callback token delivery for this flow.
+     *
+     * @param params Hosted authorize parameters (org, service, redirect_uri)
+     * @returns The full URL to redirect the user to
+     *
+     * @example
+     * ```typescript
+     * window.location.href = sso.auth.getAuthorizeUrl({
+     *   org: 'acme-corp',
+     *   service: 'main-app',
+     *   redirect_uri: 'https://app.acme.com/callback'
+     * });
+     * ```
+     */
+    getAuthorizeUrl(params: AuthorizeUrlParams): string;
+    /**
+     * Constructs the hosted account-security URL for managing user factors.
+     * Use this for AuthOS-owned MFA, passkeys, backup codes, and trusted devices.
+     *
+     * @param params Optional tenant/application context and return URL
+     * @returns The full URL to open for account security management
+     */
+    getAccountSecurityUrl(params?: AccountSecurityUrlParams): string;
     /**
      * Constructs the OAuth login URL for end-users.
      * This does not perform the redirect; the consuming application
@@ -5649,6 +5737,7 @@ declare class PasskeysModule {
         org_slug?: string;
         service_slug?: string;
         redirect_uri?: string;
+        state?: string;
     }): Promise<PasskeyAuthStartResponse>;
     /**
      * Finish the passkey authentication ceremony.
@@ -5663,6 +5752,7 @@ declare class PasskeysModule {
         org_slug?: string;
         service_slug?: string;
         redirect_uri?: string;
+        state?: string;
     }): Promise<PasskeyAuthFinishResponse>;
     /**
      * Convert Base64URL string to Uint8Array
@@ -5687,6 +5777,8 @@ interface MagicLinkRequest {
     service_slug?: string;
     /** Optional service callback URI */
     redirect_uri?: string;
+    /** Optional caller state to return to hosted service callbacks */
+    state?: string;
 }
 /**
  * Magic link response
@@ -5717,7 +5809,7 @@ declare class MagicLinks {
      * @param redirectUri Optional where to redirect after success
      * @returns URL to redirect to for verification
      */
-    getVerificationUrl(token: string, redirectUri?: string): string;
+    getVerificationUrl(token: string, redirectUri?: string, state?: string): string;
     /**
      * Verify a magic link token via API call
      * This is an alternative to redirect-based verification
@@ -5726,7 +5818,7 @@ declare class MagicLinks {
      * @param redirectUri Optional redirect URI
      * @returns Promise resolving to authentication response
      */
-    verify(token: string, redirectUri?: string): Promise<any>;
+    verify(token: string, redirectUri?: string, state?: string): Promise<any>;
     /**
      * Construct the complete magic link URL that would be sent via email
      *
@@ -5734,7 +5826,7 @@ declare class MagicLinks {
      * @param redirectUri Optional redirect URI
      * @returns Complete magic link URL
      */
-    constructMagicLink(token: string, redirectUri?: string): string;
+    constructMagicLink(token: string, redirectUri?: string, state?: string): string;
 }
 
 /**
@@ -5806,6 +5898,10 @@ interface SsoClientOptions {
      * Prefix for storage keys. Default: 'sso_'
      */
     storagePrefix?: string;
+    /**
+     * Refresh access tokens this many seconds before expiry. Default: 30.
+     */
+    tokenRefreshMinValiditySeconds?: number;
 }
 /**
  * Main SSO client class.
@@ -6087,4 +6183,4 @@ declare class SsoApiError extends Error {
     isNotFound(): boolean;
 }
 
-export { type AcceptInvitationPayload, type AdminLoginUrlParams, type AnalyticsQuery, type ApiKey, type ApiKeyCreateResponse, type ApproveOrganizationPayload, type AuditLog, type AuditLogEntry, type AuditLogQueryParams, type AuditLogResponse, type AuthContextRequest, type AuthContextResponse, AuthErrorCodes, AuthModule, type AuthOrganizationContext, type AuthServiceContext, type AuthSnapshot, type AuthenticationResponseJSON, type BackupCodesResponse, type BrandingConfiguration, BrowserStorage, type ChangePasswordRequest, type ChangePasswordResponse, type CompleteProviderTokenRequestPayload, type CompleteProviderTokenRequestResponse, type ConfigureSamlPayload, type ConfigureSamlResponse, CookieStorage, type CreateApiKeyPayload, type CreateCheckoutPayload, type CreateCheckoutResponse, type CreateInvitationPayload, type CreateOrganizationPayload, type CreateOrganizationResponse, type CreatePlanPayload, type CreateRoleRequest, type CreateScimTokenRequest, type CreateServicePayload, type CreateServiceResponse, type CreateSiemConfigRequest, type CreateUpstreamProviderPayload, type CreateWebhookRequest, type DeclineInvitationPayload, type DeviceCodeRequest, type DeviceCodeResponse, type DeviceVerifyResponse, type DomainConfiguration, type DomainVerificationMethod, type DomainVerificationResponse, type DomainVerificationResult, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserLoginEvent, type EndUserSession, type EndUserSubscription, type EventTypeInfo, type ExportUserDataResponse, type ForgetUserRequest, type ForgetUserResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GeoLocation, type GetAuditLogParams, type GetRiskSettingsResponse, type GrantLinkedAccountRequest, type GrowthTrendPoint, type Identity, type ImpersonateRequest, type ImpersonateResponse, type ImpersonationUserInfo, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type LinkedAccount, type LinkedAccountGrant, type LinkedAccountsResponse, type ListApiKeysResponse, type ListDevicesResponse, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type ListScimTokensResponse, type ListSiemConfigsResponse, type LoginActivityPoint, type LoginEventExport, type LoginRequest, type LoginTrendPoint, type LoginUrlParams, type LoginsByProvider, type LoginsByService, type LookupEmailRequest, type LookupEmailResponse, MagicLinks, type MemberListResponse, type MemberRole, type MemberServiceAccess, type Membership, type MembershipExport, MemoryStorage, type MfaEventExport, type MfaSetupResponse, type MfaStatusResponse, type MfaVerificationRequest, type MfaVerificationResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OAuthCredentials, type OAuthIdentityExport, type OAuthProvider, type Organization, type OrganizationMember, type OrganizationResponse, type OrganizationStatus, type OrganizationStatusBreakdown, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationInfo, type PaginationParams, type Passkey, type PasskeyActionResponse, type PasskeyAuthFinishRequest, type PasskeyAuthFinishResponse, type PasskeyAuthStartRequest, type PasskeyAuthStartResponse, type PasskeyExport, type PasskeyRegisterFinishRequest, type PasskeyRegisterFinishResponse, type PasskeyRegisterStartRequest, type PasskeyRegisterStartResponse, PasskeysModule, PermissionsModule, type Plan, type PlanResponse, type PlatformAnalyticsDateRangeParams, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PlatformOverviewMetrics, type PlatformUser, type PlatformUserListResponse, type PromotePlatformOwnerPayload, type ProviderDefinition, type ProviderToken, type ProviderTokenRequestDetails, type RecentLogin, type RecentOrganization, type RefreshTokenRequest, type RefreshTokenResponse, type RegisterRequest, type RegisterResponse, type RegistrationResponseJSON, type RejectOrganizationPayload, type ResendVerificationRequest, type ResendVerificationResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDeviceRequest, type RevokeDeviceResponse, type RevokeSessionsResponse, type RiskAction, type RiskAssessment, type RiskEventResponse, type RiskEventsQuery, type RoleResponse, type RotateServiceSecretResponse, type SamlCertificate, type SamlConfig, type ScimTokenResponse, type SelectOrganizationResponse, type Service, ServiceApiModule, type ServiceListResponse, type ServiceType, type ServiceWithDetails, ServicesModule, type SetCustomDomainRequest, type SetOAuthCredentialsPayload, type SetPasswordRequest, type SetPasswordResponse, type SetSmtpRequest, type SiemConfigResponse, type SiemProviderType, type SmtpConfigResponse, SsoApiError, SsoClient, type SsoClientOptions, type StartLinkResponse, type Subscription, type TestConnectionResponse, type TokenRequest, type TokenResponse, type TokenStorage, type TopOrganization, type TransferOwnershipPayload, type UpdateBrandingRequest, type UpdateMemberRolePayload, type UpdateMemberServiceAccessPayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdatePlanPayload, type UpdateRiskSettingsRequest, type UpdateRiskSettingsResponse, type UpdateRoleRequest, type UpdateServicePayload, type UpdateSiemConfigRequest, type UpdateUpstreamProviderPayload, type UpdateUserProfilePayload, type UpdateWebhookRequest, type UpstreamProvider, type UpstreamProviderType, type User, type UserDevice, UserModule, type UserPasskey, type UserProfile, type Webhook, type WebhookDelivery, type WebhookDeliveryListResponse, type WebhookDeliveryQueryParams, type WebhookListResponse, type WebhookResponse };
+export { type AcceptInvitationPayload, type AccountSecurityUrlParams, type AdminLoginUrlParams, type AnalyticsQuery, type ApiKey, type ApiKeyCreateResponse, type ApproveOrganizationPayload, type AuditLog, type AuditLogEntry, type AuditLogQueryParams, type AuditLogResponse, type AuthContextRequest, type AuthContextResponse, AuthErrorCodes, AuthModule, type AuthOrganizationContext, type AuthServiceContext, type AuthSnapshot, type AuthenticationResponseJSON, type AuthorizeUrlParams, type BackupCodesResponse, type BrandingConfiguration, BrowserStorage, type ChangePasswordRequest, type ChangePasswordResponse, type CompleteProviderTokenRequestPayload, type CompleteProviderTokenRequestResponse, type ConfigureSamlPayload, type ConfigureSamlResponse, CookieStorage, type CreateApiKeyPayload, type CreateCheckoutPayload, type CreateCheckoutResponse, type CreateInvitationPayload, type CreateOrganizationPayload, type CreateOrganizationResponse, type CreatePlanPayload, type CreateRoleRequest, type CreateScimTokenRequest, type CreateServicePayload, type CreateServiceResponse, type CreateSiemConfigRequest, type CreateUpstreamProviderPayload, type CreateWebhookRequest, type DeclineInvitationPayload, type DeviceCodeRequest, type DeviceCodeResponse, type DeviceVerifyResponse, type DomainConfiguration, type DomainVerificationMethod, type DomainVerificationResponse, type DomainVerificationResult, type EndUser, type EndUserDetailResponse, type EndUserIdentity, type EndUserListResponse, type EndUserLoginEvent, type EndUserSession, type EndUserSubscription, type EventTypeInfo, type ExportUserDataResponse, type ForgetUserRequest, type ForgetUserResponse, type ForgotPasswordRequest, type ForgotPasswordResponse, type GeoLocation, type GetAuditLogParams, type GetRiskSettingsResponse, type GrantLinkedAccountRequest, type GrowthTrendPoint, type Identity, type ImpersonateRequest, type ImpersonateResponse, type ImpersonationUserInfo, type Invitation, type InvitationStatus, type InvitationWithOrg, InvitationsModule, type JwtClaims, type LinkedAccount, type LinkedAccountGrant, type LinkedAccountsResponse, type ListApiKeysResponse, type ListDevicesResponse, type ListEndUsersParams, type ListOrganizationsParams, type ListPlatformOrganizationsParams, type ListScimTokensResponse, type ListSiemConfigsResponse, type LoginActivityPoint, type LoginEventExport, type LoginRequest, type LoginTrendPoint, type LoginUrlParams, type LoginsByProvider, type LoginsByService, type LookupEmailRequest, type LookupEmailResponse, MagicLinks, type MemberListResponse, type MemberRole, type MemberServiceAccess, type Membership, type MembershipExport, MemoryStorage, type MfaEventExport, type MfaSetupResponse, type MfaStatusResponse, type MfaVerificationRequest, type MfaVerificationResponse, type MfaVerifyRequest, type MfaVerifyResponse, type OAuthCredentials, type OAuthIdentityExport, type OAuthProvider, type Organization, type OrganizationMember, type OrganizationResponse, type OrganizationStatus, type OrganizationStatusBreakdown, type OrganizationTier, OrganizationsModule, type PaginatedResponse, type PaginationInfo, type PaginationParams, type Passkey, type PasskeyActionResponse, type PasskeyAuthFinishRequest, type PasskeyAuthFinishResponse, type PasskeyAuthStartRequest, type PasskeyAuthStartResponse, type PasskeyExport, type PasskeyRegisterFinishRequest, type PasskeyRegisterFinishResponse, type PasskeyRegisterStartRequest, type PasskeyRegisterStartResponse, PasskeysModule, PermissionsModule, type Plan, type PlanResponse, type PlatformAnalyticsDateRangeParams, PlatformModule, type PlatformOrganizationResponse, type PlatformOrganizationsListResponse, type PlatformOverviewMetrics, type PlatformUser, type PlatformUserListResponse, type PromotePlatformOwnerPayload, type ProviderDefinition, type ProviderToken, type ProviderTokenRequestDetails, type RecentLogin, type RecentOrganization, type RefreshTokenRequest, type RefreshTokenResponse, type RegisterRequest, type RegisterResponse, type RegistrationResponseJSON, type RejectOrganizationPayload, type ResendVerificationRequest, type ResendVerificationResponse, type ResetPasswordRequest, type ResetPasswordResponse, type RevokeDeviceRequest, type RevokeDeviceResponse, type RevokeSessionsResponse, type RiskAction, type RiskAssessment, type RiskEventResponse, type RiskEventsQuery, type RoleResponse, type RotateServiceSecretResponse, type SamlCertificate, type SamlConfig, type ScimTokenResponse, type SelectOrganizationResponse, type Service, ServiceApiModule, type ServiceListResponse, type ServiceType, type ServiceWithDetails, ServicesModule, SessionManager, type SetCustomDomainRequest, type SetOAuthCredentialsPayload, type SetPasswordRequest, type SetPasswordResponse, type SetSmtpRequest, type SiemConfigResponse, type SiemProviderType, type SmtpConfigResponse, SsoApiError, SsoClient, type SsoClientOptions, type StartLinkResponse, type Subscription, type TestConnectionResponse, type TokenRequest, type TokenResponse, type TokenStorage, type TopOrganization, type TransferOwnershipPayload, type UpdateBrandingRequest, type UpdateMemberRolePayload, type UpdateMemberServiceAccessPayload, type UpdateOrganizationPayload, type UpdateOrganizationTierPayload, type UpdatePlanPayload, type UpdateRiskSettingsRequest, type UpdateRiskSettingsResponse, type UpdateRoleRequest, type UpdateServicePayload, type UpdateSiemConfigRequest, type UpdateUpstreamProviderPayload, type UpdateUserProfilePayload, type UpdateWebhookRequest, type UpstreamProvider, type UpstreamProviderType, type User, type UserDevice, UserModule, type UserPasskey, type UserProfile, type Webhook, type WebhookDelivery, type WebhookDeliveryListResponse, type WebhookDeliveryQueryParams, type WebhookListResponse, type WebhookResponse };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   PlatformModule: () => PlatformModule,
   ServiceApiModule: () => ServiceApiModule,
   ServicesModule: () => ServicesModule,
+  SessionManager: () => SessionManager,
   SsoApiError: () => SsoApiError,
   SsoClient: () => SsoClient,
   UserModule: () => UserModule
@@ -300,6 +301,22 @@ function createHttpAgent(baseURL) {
 }
 
 // src/session.ts
+var DEFAULT_MIN_VALIDITY_SECONDS = 30;
+function decodeJwtExpiration(token) {
+  const [, payload] = token.split(".");
+  if (!payload) {
+    return null;
+  }
+  try {
+    const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+    const decoded = globalThis.atob(padded);
+    const parsed = JSON.parse(decoded);
+    return typeof parsed.exp === "number" && Number.isFinite(parsed.exp) ? parsed.exp : null;
+  } catch {
+    return null;
+  }
+}
 var SessionManager = class {
   constructor(storage, refreshHandler, config = { storageKeyPrefix: "sso_" }) {
     this.storage = storage;
@@ -308,19 +325,27 @@ var SessionManager = class {
     this.accessToken = null;
     this.refreshToken = null;
     this.refreshPromise = null;
+    this.sessionVersion = 0;
     this.listeners = [];
   }
   /**
    * Initialize session from storage
    */
   async loadSession() {
-    this.accessToken = await this.storage.getItem(`${this.config.storageKeyPrefix}access_token`);
-    this.refreshToken = await this.storage.getItem(`${this.config.storageKeyPrefix}refresh_token`);
+    const version = this.sessionVersion;
+    const accessToken = await this.storage.getItem(`${this.config.storageKeyPrefix}access_token`);
+    const refreshToken = await this.storage.getItem(`${this.config.storageKeyPrefix}refresh_token`);
+    if (version !== this.sessionVersion) {
+      return;
+    }
+    this.accessToken = accessToken;
+    this.refreshToken = refreshToken;
   }
   /**
    * Set the session data (used after login/register)
    */
   async setSession(tokens) {
+    this.sessionVersion += 1;
     this.accessToken = tokens.access_token;
     await this.storage.setItem(`${this.config.storageKeyPrefix}access_token`, tokens.access_token);
     if (tokens.refresh_token) {
@@ -333,6 +358,7 @@ var SessionManager = class {
    * Clear session (logout)
    */
   async clearSession() {
+    this.sessionVersion += 1;
     this.accessToken = null;
     this.refreshToken = null;
     await this.storage.removeItem(`${this.config.storageKeyPrefix}access_token`);
@@ -343,6 +369,26 @@ var SessionManager = class {
    * Get the current access token, refreshing it if necessary/possible
    */
   async getToken() {
+    if (!this.accessToken) {
+      return null;
+    }
+    const expiresAt = decodeJwtExpiration(this.accessToken);
+    if (expiresAt === null) {
+      return this.accessToken;
+    }
+    const secondsUntilExpiry = expiresAt - Math.floor(Date.now() / 1e3);
+    const minValiditySeconds = this.config.minValiditySeconds ?? DEFAULT_MIN_VALIDITY_SECONDS;
+    if (secondsUntilExpiry <= 0 && !this.refreshToken) {
+      await this.clearSession();
+      return null;
+    }
+    if (secondsUntilExpiry <= minValiditySeconds && this.refreshToken) {
+      try {
+        return await this.refreshSession();
+      } catch {
+        return null;
+      }
+    }
     return this.accessToken;
   }
   /**
@@ -672,6 +718,49 @@ var AuthModule = class {
       }
     };
   }
+  /**
+   * Constructs the hosted AuthOS login URL for an end-user application.
+   * AuthOS owns provider selection, HRD, password, magic-link, passkey, MFA,
+   * recovery, and callback token delivery for this flow.
+   *
+   * @param params Hosted authorize parameters (org, service, redirect_uri)
+   * @returns The full URL to redirect the user to
+   *
+   * @example
+   * ```typescript
+   * window.location.href = sso.auth.getAuthorizeUrl({
+   *   org: 'acme-corp',
+   *   service: 'main-app',
+   *   redirect_uri: 'https://app.acme.com/callback'
+   * });
+   * ```
+   */
+  getAuthorizeUrl(params) {
+    const baseURL = (this.http.defaults.baseURL || "").replace(/\/+$/, "");
+    const searchParams = new URLSearchParams({
+      org: params.org,
+      service: params.service,
+      redirect_uri: params.redirect_uri
+    });
+    if (params.state) searchParams.append("state", params.state);
+    return `${baseURL}/authorize?${searchParams.toString()}`;
+  }
+  /**
+   * Constructs the hosted account-security URL for managing user factors.
+   * Use this for AuthOS-owned MFA, passkeys, backup codes, and trusted devices.
+   *
+   * @param params Optional tenant/application context and return URL
+   * @returns The full URL to open for account security management
+   */
+  getAccountSecurityUrl(params = {}) {
+    const baseURL = (this.http.defaults.baseURL || "").replace(/\/+$/, "");
+    const searchParams = new URLSearchParams();
+    if (params.org) searchParams.append("org", params.org);
+    if (params.service) searchParams.append("service", params.service);
+    if (params.return_to) searchParams.append("return_to", params.return_to);
+    const query = searchParams.toString();
+    return `${baseURL}/app/account-security${query ? `?${query}` : ""}`;
+  }
   /**
    * Constructs the OAuth login URL for end-users.
    * This does not perform the redirect; the consuming application
@@ -712,6 +801,9 @@ var AuthModule = class {
     if (params.redirect_uri) {
       searchParams.append("redirect_uri", params.redirect_uri);
     }
+    if (params.state) {
+      searchParams.append("state", params.state);
+    }
     if (params.user_code) {
       searchParams.append("user_code", params.user_code);
     }
@@ -745,6 +837,9 @@ var AuthModule = class {
     if (params?.user_code) {
       searchParams.append("user_code", params.user_code);
     }
+    if (params?.return_to) {
+      searchParams.append("return_to", params.return_to);
+    }
     const queryString = searchParams.toString();
     return `${baseURL}/auth/admin/${provider}${queryString ? `?${queryString}` : ""}`;
   }
@@ -1680,11 +1775,11 @@ var WebhooksModule = class {
   /**
    * Trigger a test event for a specific webhook (owner/admin only).
    * Generates a "webhook.test.ping" event to verify connectivity.
-   * 
+   *
    * @param orgSlug Organization slug
    * @param webhookId Webhook ID
    * @returns Result including delivery ID
-   * 
+   *
    * @example
    * ```typescript
    * const result = await sso.organizations.webhooks.test('acme-corp', 'webhook-123');
@@ -1949,7 +2044,7 @@ var OrganizationsModule = class {
        *   page: 1,
        *   limit: 20
        * });
-       * 
+       *
        * // Filter by specific service
        * const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
        *   service_slug: 'my-app',
@@ -2336,7 +2431,7 @@ var OrganizationsModule = class {
       /**
        * Get risk events for an organization.
        * Requires 'owner' or 'admin' role.
-       * 
+       *
        * @param orgSlug Organization slug
        * @param params Query parameters
        */
@@ -2536,7 +2631,7 @@ var OrganizationsModule = class {
   /**
    * Select/switch to a different organization context.
    * Issues a new JWT token with the organization context.
-   * 
+   *
    * This allows users to seamlessly switch between organizations
    * they are members of without re-authenticating.
    *
@@ -2547,7 +2642,7 @@ var OrganizationsModule = class {
    * ```typescript
    * // Switch to a different organization
    * const result = await sso.organizations.select('acme-corp');
-   * 
+   *
    * // The SDK automatically updates the session with new tokens
    * // API calls will now be made in the context of 'acme-corp'
    * ```
@@ -3734,10 +3829,10 @@ var PlatformModule = class {
       },
       /**
        * List all users on the platform with pagination.
-       * 
+       *
        * @param options Pagination options
        * @returns List of users and total count
-       * 
+       *
        * @example
        * ```typescript
        * const result = await sso.platform.users.list({ limit: 10, offset: 0 });
@@ -4767,11 +4862,14 @@ var MagicLinks = class {
    * @param redirectUri Optional where to redirect after success
    * @returns URL to redirect to for verification
    */
-  getVerificationUrl(token, redirectUri) {
+  getVerificationUrl(token, redirectUri, state) {
     const params = new URLSearchParams({ token });
     if (redirectUri) {
       params.append("redirect_uri", redirectUri);
     }
+    if (state) {
+      params.append("state", state);
+    }
     return `/api/auth/magic-link/verify?${params.toString()}`;
   }
   /**
@@ -4782,11 +4880,14 @@ var MagicLinks = class {
    * @param redirectUri Optional redirect URI
    * @returns Promise resolving to authentication response
    */
-  async verify(token, redirectUri) {
+  async verify(token, redirectUri, state) {
     const params = new URLSearchParams({ token });
     if (redirectUri) {
       params.append("redirect_uri", redirectUri);
     }
+    if (state) {
+      params.append("state", state);
+    }
     const response = await this.http.get(`/api/auth/magic-link/verify?${params.toString()}`);
     return response.data;
   }
@@ -4797,8 +4898,8 @@ var MagicLinks = class {
    * @param redirectUri Optional redirect URI
    * @returns Complete magic link URL
    */
-  constructMagicLink(token, redirectUri) {
-    return this.getVerificationUrl(token, redirectUri);
+  constructMagicLink(token, redirectUri, state) {
+    return this.getVerificationUrl(token, redirectUri, state);
   }
 };
 
@@ -4864,7 +4965,10 @@ var SsoClient = class {
         const res = await this.http.post("/api/auth/refresh", { refresh_token: refreshToken });
         return res.data;
       },
-      { storageKeyPrefix: options.storagePrefix || "sso_" }
+      {
+        storageKeyPrefix: options.storagePrefix || "sso_",
+        minValiditySeconds: options.tokenRefreshMinValiditySeconds
+      }
     );
     this.http.setSessionManager(this.session);
     this.analytics = new AnalyticsModule(this.http);
@@ -5028,6 +5132,7 @@ var SsoClient = class {
   PlatformModule,
   ServiceApiModule,
   ServicesModule,
+  SessionManager,
   SsoApiError,
   SsoClient,
   UserModule

package/dist/index.mjs

@@ -259,6 +259,22 @@ function createHttpAgent(baseURL) {
 }
 
 // src/session.ts
+var DEFAULT_MIN_VALIDITY_SECONDS = 30;
+function decodeJwtExpiration(token) {
+  const [, payload] = token.split(".");
+  if (!payload) {
+    return null;
+  }
+  try {
+    const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+    const decoded = globalThis.atob(padded);
+    const parsed = JSON.parse(decoded);
+    return typeof parsed.exp === "number" && Number.isFinite(parsed.exp) ? parsed.exp : null;
+  } catch {
+    return null;
+  }
+}
 var SessionManager = class {
   constructor(storage, refreshHandler, config = { storageKeyPrefix: "sso_" }) {
     this.storage = storage;
@@ -267,19 +283,27 @@ var SessionManager = class {
     this.accessToken = null;
     this.refreshToken = null;
     this.refreshPromise = null;
+    this.sessionVersion = 0;
     this.listeners = [];
   }
   /**
    * Initialize session from storage
    */
   async loadSession() {
-    this.accessToken = await this.storage.getItem(`${this.config.storageKeyPrefix}access_token`);
-    this.refreshToken = await this.storage.getItem(`${this.config.storageKeyPrefix}refresh_token`);
+    const version = this.sessionVersion;
+    const accessToken = await this.storage.getItem(`${this.config.storageKeyPrefix}access_token`);
+    const refreshToken = await this.storage.getItem(`${this.config.storageKeyPrefix}refresh_token`);
+    if (version !== this.sessionVersion) {
+      return;
+    }
+    this.accessToken = accessToken;
+    this.refreshToken = refreshToken;
   }
   /**
    * Set the session data (used after login/register)
    */
   async setSession(tokens) {
+    this.sessionVersion += 1;
     this.accessToken = tokens.access_token;
     await this.storage.setItem(`${this.config.storageKeyPrefix}access_token`, tokens.access_token);
     if (tokens.refresh_token) {
@@ -292,6 +316,7 @@ var SessionManager = class {
    * Clear session (logout)
    */
   async clearSession() {
+    this.sessionVersion += 1;
     this.accessToken = null;
     this.refreshToken = null;
     await this.storage.removeItem(`${this.config.storageKeyPrefix}access_token`);
@@ -302,6 +327,26 @@ var SessionManager = class {
    * Get the current access token, refreshing it if necessary/possible
    */
   async getToken() {
+    if (!this.accessToken) {
+      return null;
+    }
+    const expiresAt = decodeJwtExpiration(this.accessToken);
+    if (expiresAt === null) {
+      return this.accessToken;
+    }
+    const secondsUntilExpiry = expiresAt - Math.floor(Date.now() / 1e3);
+    const minValiditySeconds = this.config.minValiditySeconds ?? DEFAULT_MIN_VALIDITY_SECONDS;
+    if (secondsUntilExpiry <= 0 && !this.refreshToken) {
+      await this.clearSession();
+      return null;
+    }
+    if (secondsUntilExpiry <= minValiditySeconds && this.refreshToken) {
+      try {
+        return await this.refreshSession();
+      } catch {
+        return null;
+      }
+    }
     return this.accessToken;
   }
   /**
@@ -631,6 +676,49 @@ var AuthModule = class {
       }
     };
   }
+  /**
+   * Constructs the hosted AuthOS login URL for an end-user application.
+   * AuthOS owns provider selection, HRD, password, magic-link, passkey, MFA,
+   * recovery, and callback token delivery for this flow.
+   *
+   * @param params Hosted authorize parameters (org, service, redirect_uri)
+   * @returns The full URL to redirect the user to
+   *
+   * @example
+   * ```typescript
+   * window.location.href = sso.auth.getAuthorizeUrl({
+   *   org: 'acme-corp',
+   *   service: 'main-app',
+   *   redirect_uri: 'https://app.acme.com/callback'
+   * });
+   * ```
+   */
+  getAuthorizeUrl(params) {
+    const baseURL = (this.http.defaults.baseURL || "").replace(/\/+$/, "");
+    const searchParams = new URLSearchParams({
+      org: params.org,
+      service: params.service,
+      redirect_uri: params.redirect_uri
+    });
+    if (params.state) searchParams.append("state", params.state);
+    return `${baseURL}/authorize?${searchParams.toString()}`;
+  }
+  /**
+   * Constructs the hosted account-security URL for managing user factors.
+   * Use this for AuthOS-owned MFA, passkeys, backup codes, and trusted devices.
+   *
+   * @param params Optional tenant/application context and return URL
+   * @returns The full URL to open for account security management
+   */
+  getAccountSecurityUrl(params = {}) {
+    const baseURL = (this.http.defaults.baseURL || "").replace(/\/+$/, "");
+    const searchParams = new URLSearchParams();
+    if (params.org) searchParams.append("org", params.org);
+    if (params.service) searchParams.append("service", params.service);
+    if (params.return_to) searchParams.append("return_to", params.return_to);
+    const query = searchParams.toString();
+    return `${baseURL}/app/account-security${query ? `?${query}` : ""}`;
+  }
   /**
    * Constructs the OAuth login URL for end-users.
    * This does not perform the redirect; the consuming application
@@ -671,6 +759,9 @@ var AuthModule = class {
     if (params.redirect_uri) {
       searchParams.append("redirect_uri", params.redirect_uri);
     }
+    if (params.state) {
+      searchParams.append("state", params.state);
+    }
     if (params.user_code) {
       searchParams.append("user_code", params.user_code);
     }
@@ -704,6 +795,9 @@ var AuthModule = class {
     if (params?.user_code) {
       searchParams.append("user_code", params.user_code);
     }
+    if (params?.return_to) {
+      searchParams.append("return_to", params.return_to);
+    }
     const queryString = searchParams.toString();
     return `${baseURL}/auth/admin/${provider}${queryString ? `?${queryString}` : ""}`;
   }
@@ -1639,11 +1733,11 @@ var WebhooksModule = class {
   /**
    * Trigger a test event for a specific webhook (owner/admin only).
    * Generates a "webhook.test.ping" event to verify connectivity.
-   * 
+   *
    * @param orgSlug Organization slug
    * @param webhookId Webhook ID
    * @returns Result including delivery ID
-   * 
+   *
    * @example
    * ```typescript
    * const result = await sso.organizations.webhooks.test('acme-corp', 'webhook-123');
@@ -1908,7 +2002,7 @@ var OrganizationsModule = class {
        *   page: 1,
        *   limit: 20
        * });
-       * 
+       *
        * // Filter by specific service
        * const serviceUsers = await sso.organizations.endUsers.list('acme-corp', {
        *   service_slug: 'my-app',
@@ -2295,7 +2389,7 @@ var OrganizationsModule = class {
       /**
        * Get risk events for an organization.
        * Requires 'owner' or 'admin' role.
-       * 
+       *
        * @param orgSlug Organization slug
        * @param params Query parameters
        */
@@ -2495,7 +2589,7 @@ var OrganizationsModule = class {
   /**
    * Select/switch to a different organization context.
    * Issues a new JWT token with the organization context.
-   * 
+   *
    * This allows users to seamlessly switch between organizations
    * they are members of without re-authenticating.
    *
@@ -2506,7 +2600,7 @@ var OrganizationsModule = class {
    * ```typescript
    * // Switch to a different organization
    * const result = await sso.organizations.select('acme-corp');
-   * 
+   *
    * // The SDK automatically updates the session with new tokens
    * // API calls will now be made in the context of 'acme-corp'
    * ```
@@ -3693,10 +3787,10 @@ var PlatformModule = class {
       },
       /**
        * List all users on the platform with pagination.
-       * 
+       *
        * @param options Pagination options
        * @returns List of users and total count
-       * 
+       *
        * @example
        * ```typescript
        * const result = await sso.platform.users.list({ limit: 10, offset: 0 });
@@ -4726,11 +4820,14 @@ var MagicLinks = class {
    * @param redirectUri Optional where to redirect after success
    * @returns URL to redirect to for verification
    */
-  getVerificationUrl(token, redirectUri) {
+  getVerificationUrl(token, redirectUri, state) {
     const params = new URLSearchParams({ token });
     if (redirectUri) {
       params.append("redirect_uri", redirectUri);
     }
+    if (state) {
+      params.append("state", state);
+    }
     return `/api/auth/magic-link/verify?${params.toString()}`;
   }
   /**
@@ -4741,11 +4838,14 @@ var MagicLinks = class {
    * @param redirectUri Optional redirect URI
    * @returns Promise resolving to authentication response
    */
-  async verify(token, redirectUri) {
+  async verify(token, redirectUri, state) {
     const params = new URLSearchParams({ token });
     if (redirectUri) {
       params.append("redirect_uri", redirectUri);
     }
+    if (state) {
+      params.append("state", state);
+    }
     const response = await this.http.get(`/api/auth/magic-link/verify?${params.toString()}`);
     return response.data;
   }
@@ -4756,8 +4856,8 @@ var MagicLinks = class {
    * @param redirectUri Optional redirect URI
    * @returns Complete magic link URL
    */
-  constructMagicLink(token, redirectUri) {
-    return this.getVerificationUrl(token, redirectUri);
+  constructMagicLink(token, redirectUri, state) {
+    return this.getVerificationUrl(token, redirectUri, state);
   }
 };
 
@@ -4823,7 +4923,10 @@ var SsoClient = class {
         const res = await this.http.post("/api/auth/refresh", { refresh_token: refreshToken });
         return res.data;
       },
-      { storageKeyPrefix: options.storagePrefix || "sso_" }
+      {
+        storageKeyPrefix: options.storagePrefix || "sso_",
+        minValiditySeconds: options.tokenRefreshMinValiditySeconds
+      }
     );
     this.http.setSessionManager(this.session);
     this.analytics = new AnalyticsModule(this.http);
@@ -4986,6 +5089,7 @@ export {
   PlatformModule,
   ServiceApiModule,
   ServicesModule,
+  SessionManager,
   SsoApiError,
   SsoClient,
   UserModule

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drmhse/sso-sdk",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Zero-dependency TypeScript SDK for AuthOS, the multi-tenant authentication platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -24,6 +24,7 @@
   "scripts": {
     "build": "tsup src/index.ts --format cjs,esm --dts --clean",
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "test": "npm run build && node --test test/*.test.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src --ext .ts",
     "prepublishOnly": "npm run build"