@meistrari/auth-core 1.35.0 → 1.36.0

package/README.md

@@ -17,6 +17,8 @@ A TypeScript/JavaScript SDK for interacting with the Auth API service.
 - **Application Authentication**
   - OAuth PKCE application flows
   - OAuth Device Authorization Grant endpoints
+  - OAuth Client Credentials Grant for service accounts
+  - Organization-scoped application token caching, renewal, and retry handling
   - Application token refresh, logout, and organization switching
 - **API Keys**
   - User-scoped API key CRUD
@@ -57,6 +59,10 @@ const tokens = await authClient.application.completeAuthorizationFlow(code, 'pkc
 console.log('Application user:', tokens.user.email)
 ```
 
+## Guides
+
+- [Client Credentials Grant](https://github.com/meistrari/auth-api/blob/main/packages/core/docs/CLIENT_CREDENTIALS.md) — server-to-server authentication using the recommended `ApplicationTokenStorage` helper
+
 ## API Reference
 
 See it on [Pantry](https://pantry.tela.tools/ingredients/auth-core/api)

package/dist/index.d.mts

@@ -370,6 +370,30 @@ type JWTPayloadData = {
 declare const JWTPayload: z$1.ZodType<JWTPayloadData>;
 type JWTPayload = JWTPayload$1 & JWTPayloadData;
 
+/**
+ * Checks if a JWT token has expired or will expire within a specified time window.
+ *
+ * @param token - The JWT token string to check
+ * @param expiresInMs - Optional time window in milliseconds. If provided, returns `true` if the token will expire within this time window
+ * @returns `true` if the token is expired (or will expire within the specified window), `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *
+ * // Check if token is already expired
+ * if (isTokenExpired(token)) {
+ *   console.log('Token has expired')
+ * }
+ *
+ * // Check if token will expire in the next 5 minutes
+ * if (isTokenExpired(token, 5 * 60 * 1000)) {
+ *   console.log('Token will expire in the next 5 minutes')
+ * }
+ * ```
+ */
+declare function isTokenExpired(token: string, expiresInMs?: number): boolean;
+
 declare const OAuthStepUpProvider: z.ZodEnum<{
     google: "google";
     microsoft: "microsoft";
@@ -631,6 +655,24 @@ type CompleteAuthorizationFlowResponse = {
     /** Assurance context embedded in the issued access token. */
     assurance: JWTPayload['assurance'];
 };
+/**
+ * Credentials used to authenticate an application service account.
+ */
+type ClientCredentialsGrant = {
+    /** The application identifier. */
+    clientId: string;
+    /** A valid secret issued for the application. */
+    clientSecret: string;
+    /** The organization to scope the access token to. */
+    organizationId: string;
+};
+/**
+ * Response returned after a successful client credentials exchange.
+ *
+ * Client credentials issue only a short-lived access token, so this response
+ * intentionally does not include a refresh token.
+ */
+type ClientCredentialsTokenResponse = Omit<CompleteAuthorizationFlowResponse, 'refreshToken'>;
 /**
  * Response returned by the "who am I" endpoint.
  *
@@ -815,6 +857,7 @@ declare function isSessionAssuranceSufficient(sessionAssurance: JWTPayload['assu
  * Provides functionality for:
  * - OAuth authorization code flow (PKCE)
  * - Device authorization flow (RFC 8628)
+ * - Client credentials flow for service accounts
  * - Token management (refresh, exchange)
  * - Organization switching
  */
@@ -905,6 +948,16 @@ declare class ApplicationService {
      * @throws {ApplicationSessionAssuranceError} Assurance policy changed or is no longer met — start a new flow
      */
     exchangeDeviceCodeForTokens(deviceCode: string): Promise<CompleteAuthorizationFlowResponse>;
+    /**
+     * Exchanges application client credentials for a service-account access token.
+     *
+     * The returned token is scoped to the requested organization and cannot be
+     * refreshed. Exchange the credentials again when a new token is needed.
+     *
+     * @param credentials - Application credentials and target organization
+     * @returns A short-lived access token with service-account and organization details
+     */
+    exchangeClientCredentialsForToken(credentials: ClientCredentialsGrant): Promise<ClientCredentialsTokenResponse>;
     /**
      * Completes an authorization flow for a specific application.
      *
@@ -4402,15 +4455,15 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
 } & {
     applications: {
         getApplicationAuthContext: (applicationId: string) => Promise<{
-            data: ApplicationAuthContextResponse;
-            error: null;
-        } | {
             data: null;
             error: {
                 message?: string | undefined;
                 status: number;
                 statusText: string;
             };
+        } | {
+            data: ApplicationAuthContextResponse;
+            error: null;
         }>;
         listCandidateOrganizations: (applicationId: string) => Promise<{
             data: ListCandidateOrganizationsResponse;
@@ -4482,6 +4535,17 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
             data: CompleteAuthorizationFlowResponse;
             error: null;
         }>;
+        exchangeClientCredentialsForToken: (credentials: ClientCredentialsGrant) => Promise<{
+            data: ClientCredentialsTokenResponse;
+            error: null;
+        } | {
+            data: null;
+            error: {
+                message?: string | undefined;
+                status: number;
+                statusText: string;
+            };
+        }>;
         completeAuthorizationFlow: (code: string, codeVerifier: string) => Promise<{
             data: null;
             error: {
@@ -5767,6 +5831,39 @@ type CreateAdminApplicationEntitlementOptions = {
     /** Organization that should be entitled to the application. */
     organizationId: string;
 };
+/**
+ * Options accepted when creating a client secret for an application.
+ */
+type CreateAdminApplicationSecretOptions = {
+    /** Optional display name for the secret. */
+    name?: string;
+};
+/**
+ * Client secret metadata returned by application management endpoints.
+ */
+type AdminApplicationSecret = {
+    id: string;
+    applicationId: string;
+    name: string | null;
+    /** First characters of the secret, kept for later identification. */
+    start: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+};
+/**
+ * Service-account identity backing client-credentials tokens for an application.
+ */
+type AdminApplicationIdentity = {
+    id: string;
+    email: string;
+};
+/**
+ * Newly-created client secret. The plaintext secret is returned only once.
+ */
+type CreatedAdminApplicationSecret = AdminApplicationSecret & {
+    secret: string;
+    serviceAccountUser: AdminApplicationIdentity;
+};
 /**
  * Options accepted when fetching a single organization as a global admin.
  */
@@ -6193,6 +6290,8 @@ type AdminApplication = {
     redirectUris: string[];
     homeUrl: string | null;
     config: ApplicationConfig | null;
+    serviceAccountUserId: string | null;
+    serviceAccountUser?: AdminApplicationIdentity | null;
     createdBy: string;
     updatedBy: string;
     createdAt: string;
@@ -6368,6 +6467,36 @@ declare class AdminService {
      * @returns The created entitlement
      */
     createApplicationEntitlement(applicationId: string, options: CreateAdminApplicationEntitlementOptions): Promise<AdminApplicationEntitlementRecord>;
+    /**
+     * Lists client secrets for an application.
+     *
+     * @param applicationId - ID of the application to inspect
+     * @returns Secret metadata without plaintext values
+     */
+    listApplicationSecrets(applicationId: string): Promise<AdminApplicationSecret[]>;
+    /**
+     * Creates a client secret for an application.
+     *
+     * @param applicationId - ID of the application to update
+     * @param options - Optional secret display name
+     * @returns The created secret, including the plaintext value shown only once
+     */
+    createApplicationSecret(applicationId: string, options?: CreateAdminApplicationSecretOptions): Promise<CreatedAdminApplicationSecret>;
+    /**
+     * Deletes one client secret for an application.
+     *
+     * @param applicationId - ID of the application to update
+     * @param secretId - ID of the secret to delete
+     * @returns The deleted secret metadata
+     */
+    deleteApplicationSecret(applicationId: string, secretId: string): Promise<AdminApplicationSecret>;
+    /**
+     * Retires an application's service-account identity.
+     *
+     * @param applicationId - ID of the application to update
+     * @returns The updated application
+     */
+    retireApplicationServiceAccount(applicationId: string): Promise<AdminApplicationRecord>;
     /**
      * Lists all organizations, optionally with member and application previews
      * and totals when a preview size is requested.
@@ -7478,32 +7607,59 @@ declare class AuthClient {
     constructor(apiUrl: string, fetchOptions?: BetterFetchOption);
 }
 
-type DecodedJWTPayload = Omit<JWTPayload, 'assurance'> & {
-    assurance?: JWTPayloadAssurance;
+/** Configuration for an in-memory application token cache. */
+type ApplicationTokenStorageOptions = {
+    /** Base URL of the Auth API. */
+    authApiUrl: string;
+    /** Application identifier used for client-credentials exchanges. */
+    clientId: string;
+    /** Application secret used for client-credentials exchanges. */
+    clientSecret: string;
+    /** Full-jitter upper bound for the first retry delay. Defaults to 100 milliseconds. */
+    initialBackoffMs?: number;
+    /** Maximum number of exchange attempts, including the initial request. Defaults to 3. */
+    maxAttempts?: number;
+    /** Maximum number of organization tokens retained in memory. Defaults to 300. */
+    maxOrganizations?: number;
+};
+/** Per-call retry overrides for {@link ApplicationTokenStorage.getToken}. */
+type GetTokenOptions = {
+    /** Full-jitter upper bound for the first retry delay. */
+    initialBackoffMs?: number;
+    /** Maximum number of exchange attempts, including the initial request. */
+    maxAttempts?: number;
 };
 /**
- * Checks if a JWT token has expired or will expire within a specified time window.
- *
- * @param token - The JWT token string to check
- * @param expiresInMs - Optional time window in milliseconds. If provided, returns `true` if the token will expire within this time window
- * @returns `true` if the token is expired (or will expire within the specified window), `false` otherwise
- *
- * @example
- * ```typescript
- * const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
- *
- * // Check if token is already expired
- * if (isTokenExpired(token)) {
- *   console.log('Token has expired')
- * }
+ * Caches organization-scoped application tokens in memory.
  *
- * // Check if token will expire in the next 5 minutes
- * if (isTokenExpired(token, 5 * 60 * 1000)) {
- *   console.log('Token will expire in the next 5 minutes')
- * }
- * ```
+ * Tokens are reissued one minute before expiry. Cache hits promote their
+ * organization to the most-recently-used position, and insertions beyond the
+ * configured limit evict the least recently used organization. Transient
+ * exchange failures use full-jitter exponential backoff.
  */
-declare function isTokenExpired(token: string, expiresInMs?: number): boolean;
+declare class ApplicationTokenStorage {
+    private readonly auth;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly initialBackoffMs;
+    private readonly inFlight;
+    private readonly maxAttempts;
+    private readonly maxOrganizations;
+    private readonly tokens;
+    /** Creates an application token cache for one client-credentials identity. */
+    constructor({ authApiUrl, clientId, clientSecret, initialBackoffMs, maxAttempts, maxOrganizations, }: ApplicationTokenStorageOptions);
+    /** Returns a fresh access token scoped to the requested organization. */
+    getToken(organizationId: string, { initialBackoffMs, maxAttempts, }?: GetTokenOptions): Promise<string>;
+    private exchangeTokenWithRetry;
+    /** Performs the client-credentials exchange for one organization. */
+    protected exchangeToken(organizationId: string): Promise<string>;
+    /** Waits before the next exchange attempt. */
+    protected wait(delayMs: number): Promise<void>;
+}
+
+type DecodedJWTPayload = Omit<JWTPayload, 'assurance'> & {
+    assurance?: JWTPayloadAssurance;
+};
 /**
  * Validates a JWT token by checking its expiration and verifying its signature
  * against the JWKS endpoint.
@@ -7542,5 +7698,5 @@ declare function validateToken(token: string, apiUrl: string): Promise<boolean>;
  */
 declare function extractTokenPayload(token: string): DecodedJWTPayload;
 
-export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthBeginStepUpResponse, OAuthCompleteStepUpResponse, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, STEP_UP_MAX_AGE_SECONDS, SendOtpResponse, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceResponse, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, createAPIClient, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };
-export type { APIClient, AcceptInvitationResult, AdminApplication, AdminApplicationEntitlement, AdminApplicationEntitlementRecord, AdminApplicationMember, AdminApplicationOrganization, AdminApplicationRecord, AdminApplicationRole, AdminEntitlementRule, AdminEntitlementRuleType, AdminEntitlementWithRules, AdminMember, AdminOrganization, AdminOrganizationApplication, AdminOrganizationMember, AdminOrganizationMemberApplication, AdminOrganizationMemberRecord, AdminOrganizationMemberTeam, AdminOrganizationSummary, AdminOrganizationTeam, AdminOrganizationTeamRecord, AdminUser, AdminUserAccess, AdminUserAccessApplication, AdminUserAccessOrganization, AdminUserAccessTeam, AdminUserInvitation, AdminUserOrganization, ApiKey, ApiKeyWithoutSecret, Application, ApplicationAuthContextResponse, AssuranceFields, BaseOrganization, BeginOAuthStepUpParams, BillingMode, CompleteAuthorizationFlowResponse, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminApplicationRoleOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, CreateApiKeyPayload, CreateTeamPayload, DecodedJWTPayload, DeviceAuthorizationActionResponse, DeviceAuthorizationContextResponse, DeviceAuthorizationResponse, DeviceContextApplication, EmailOTPSignInOptions, FullOrganization, GetAdminOrganizationOptions, GetAdminOrganizationsSummaryOptions, Invitation, InviteAdminOrganizationUsersOptions, InviteAdminOrganizationUsersResult, InviteUserToOrganizationOptions, JWTPayloadData, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminUsersOptions, ListAdminUsersResult, ListCandidateOrganizationsResponse, ListMembersOptions, Member, ExtendedOrganization as Organization, OrganizationSettings, RemoveAdminMemberOptions, RemoveUserFromOrganizationOptions, ResendAdminInviteOptions, Role, SendVerificationOTPOptions, Session, SessionAssuranceActions, SessionData, SetAdminEntitlementRulesOptions, SetAdminUserApplicationRoleOptions, SetAdminUserTeamOptions, SignInWithEmailAndPasswordOptions, SignInWithSamlOptions, SocialSignInOptions, StartAuthorizationFlowResponse, Strict, Team, TeamMember, UpdateAdminApplicationRoleOptions, UpdateAdminEntitlementOptions, UpdateAdminMemberRoleOptions, UpdateAdminOrganizationOptions, UpdateApiKeyPayload, UpdateMemberRoleOptions, UpdateOrganizationPayload, UpdateTeamPayload, User, UserProfile, WhoAmIInclude, WhoAmIOptions, WhoAmIOrganization, WhoAmIResponse };
+export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, ApplicationTokenStorage, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthBeginStepUpResponse, OAuthCompleteStepUpResponse, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, STEP_UP_MAX_AGE_SECONDS, SendOtpResponse, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceResponse, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, createAPIClient, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };
+export type { APIClient, AcceptInvitationResult, AdminApplication, AdminApplicationEntitlement, AdminApplicationEntitlementRecord, AdminApplicationIdentity, AdminApplicationMember, AdminApplicationOrganization, AdminApplicationRecord, AdminApplicationRole, AdminApplicationSecret, AdminEntitlementRule, AdminEntitlementRuleType, AdminEntitlementWithRules, AdminMember, AdminOrganization, AdminOrganizationApplication, AdminOrganizationMember, AdminOrganizationMemberApplication, AdminOrganizationMemberRecord, AdminOrganizationMemberTeam, AdminOrganizationSummary, AdminOrganizationTeam, AdminOrganizationTeamRecord, AdminUser, AdminUserAccess, AdminUserAccessApplication, AdminUserAccessOrganization, AdminUserAccessTeam, AdminUserInvitation, AdminUserOrganization, ApiKey, ApiKeyWithoutSecret, Application, ApplicationAuthContextResponse, ApplicationTokenStorageOptions, AssuranceFields, BaseOrganization, BeginOAuthStepUpParams, BillingMode, ClientCredentialsGrant, ClientCredentialsTokenResponse, CompleteAuthorizationFlowResponse, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminApplicationRoleOptions, CreateAdminApplicationSecretOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, CreateApiKeyPayload, CreateTeamPayload, CreatedAdminApplicationSecret, DecodedJWTPayload, DeviceAuthorizationActionResponse, DeviceAuthorizationContextResponse, DeviceAuthorizationResponse, DeviceContextApplication, EmailOTPSignInOptions, FullOrganization, GetAdminOrganizationOptions, GetAdminOrganizationsSummaryOptions, GetTokenOptions, Invitation, InviteAdminOrganizationUsersOptions, InviteAdminOrganizationUsersResult, InviteUserToOrganizationOptions, JWTPayloadData, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminUsersOptions, ListAdminUsersResult, ListCandidateOrganizationsResponse, ListMembersOptions, Member, ExtendedOrganization as Organization, OrganizationSettings, RemoveAdminMemberOptions, RemoveUserFromOrganizationOptions, ResendAdminInviteOptions, Role, SendVerificationOTPOptions, Session, SessionAssuranceActions, SessionData, SetAdminEntitlementRulesOptions, SetAdminUserApplicationRoleOptions, SetAdminUserTeamOptions, SignInWithEmailAndPasswordOptions, SignInWithSamlOptions, SocialSignInOptions, StartAuthorizationFlowResponse, Strict, Team, TeamMember, UpdateAdminApplicationRoleOptions, UpdateAdminEntitlementOptions, UpdateAdminMemberRoleOptions, UpdateAdminOrganizationOptions, UpdateApiKeyPayload, UpdateMemberRoleOptions, UpdateOrganizationPayload, UpdateTeamPayload, User, UserProfile, WhoAmIInclude, WhoAmIOptions, WhoAmIOrganization, WhoAmIResponse };

package/dist/index.d.ts

@@ -370,6 +370,30 @@ type JWTPayloadData = {
 declare const JWTPayload: z$1.ZodType<JWTPayloadData>;
 type JWTPayload = JWTPayload$1 & JWTPayloadData;
 
+/**
+ * Checks if a JWT token has expired or will expire within a specified time window.
+ *
+ * @param token - The JWT token string to check
+ * @param expiresInMs - Optional time window in milliseconds. If provided, returns `true` if the token will expire within this time window
+ * @returns `true` if the token is expired (or will expire within the specified window), `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *
+ * // Check if token is already expired
+ * if (isTokenExpired(token)) {
+ *   console.log('Token has expired')
+ * }
+ *
+ * // Check if token will expire in the next 5 minutes
+ * if (isTokenExpired(token, 5 * 60 * 1000)) {
+ *   console.log('Token will expire in the next 5 minutes')
+ * }
+ * ```
+ */
+declare function isTokenExpired(token: string, expiresInMs?: number): boolean;
+
 declare const OAuthStepUpProvider: z.ZodEnum<{
     google: "google";
     microsoft: "microsoft";
@@ -631,6 +655,24 @@ type CompleteAuthorizationFlowResponse = {
     /** Assurance context embedded in the issued access token. */
     assurance: JWTPayload['assurance'];
 };
+/**
+ * Credentials used to authenticate an application service account.
+ */
+type ClientCredentialsGrant = {
+    /** The application identifier. */
+    clientId: string;
+    /** A valid secret issued for the application. */
+    clientSecret: string;
+    /** The organization to scope the access token to. */
+    organizationId: string;
+};
+/**
+ * Response returned after a successful client credentials exchange.
+ *
+ * Client credentials issue only a short-lived access token, so this response
+ * intentionally does not include a refresh token.
+ */
+type ClientCredentialsTokenResponse = Omit<CompleteAuthorizationFlowResponse, 'refreshToken'>;
 /**
  * Response returned by the "who am I" endpoint.
  *
@@ -815,6 +857,7 @@ declare function isSessionAssuranceSufficient(sessionAssurance: JWTPayload['assu
  * Provides functionality for:
  * - OAuth authorization code flow (PKCE)
  * - Device authorization flow (RFC 8628)
+ * - Client credentials flow for service accounts
  * - Token management (refresh, exchange)
  * - Organization switching
  */
@@ -905,6 +948,16 @@ declare class ApplicationService {
      * @throws {ApplicationSessionAssuranceError} Assurance policy changed or is no longer met — start a new flow
      */
     exchangeDeviceCodeForTokens(deviceCode: string): Promise<CompleteAuthorizationFlowResponse>;
+    /**
+     * Exchanges application client credentials for a service-account access token.
+     *
+     * The returned token is scoped to the requested organization and cannot be
+     * refreshed. Exchange the credentials again when a new token is needed.
+     *
+     * @param credentials - Application credentials and target organization
+     * @returns A short-lived access token with service-account and organization details
+     */
+    exchangeClientCredentialsForToken(credentials: ClientCredentialsGrant): Promise<ClientCredentialsTokenResponse>;
     /**
      * Completes an authorization flow for a specific application.
      *
@@ -4402,15 +4455,15 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
 } & {
     applications: {
         getApplicationAuthContext: (applicationId: string) => Promise<{
-            data: ApplicationAuthContextResponse;
-            error: null;
-        } | {
             data: null;
             error: {
                 message?: string | undefined;
                 status: number;
                 statusText: string;
             };
+        } | {
+            data: ApplicationAuthContextResponse;
+            error: null;
         }>;
         listCandidateOrganizations: (applicationId: string) => Promise<{
             data: ListCandidateOrganizationsResponse;
@@ -4482,6 +4535,17 @@ declare function createAPIClient(apiUrl: string, fetchOptions?: BetterFetchOptio
             data: CompleteAuthorizationFlowResponse;
             error: null;
         }>;
+        exchangeClientCredentialsForToken: (credentials: ClientCredentialsGrant) => Promise<{
+            data: ClientCredentialsTokenResponse;
+            error: null;
+        } | {
+            data: null;
+            error: {
+                message?: string | undefined;
+                status: number;
+                statusText: string;
+            };
+        }>;
         completeAuthorizationFlow: (code: string, codeVerifier: string) => Promise<{
             data: null;
             error: {
@@ -5767,6 +5831,39 @@ type CreateAdminApplicationEntitlementOptions = {
     /** Organization that should be entitled to the application. */
     organizationId: string;
 };
+/**
+ * Options accepted when creating a client secret for an application.
+ */
+type CreateAdminApplicationSecretOptions = {
+    /** Optional display name for the secret. */
+    name?: string;
+};
+/**
+ * Client secret metadata returned by application management endpoints.
+ */
+type AdminApplicationSecret = {
+    id: string;
+    applicationId: string;
+    name: string | null;
+    /** First characters of the secret, kept for later identification. */
+    start: string;
+    createdAt: string;
+    lastUsedAt: string | null;
+};
+/**
+ * Service-account identity backing client-credentials tokens for an application.
+ */
+type AdminApplicationIdentity = {
+    id: string;
+    email: string;
+};
+/**
+ * Newly-created client secret. The plaintext secret is returned only once.
+ */
+type CreatedAdminApplicationSecret = AdminApplicationSecret & {
+    secret: string;
+    serviceAccountUser: AdminApplicationIdentity;
+};
 /**
  * Options accepted when fetching a single organization as a global admin.
  */
@@ -6193,6 +6290,8 @@ type AdminApplication = {
     redirectUris: string[];
     homeUrl: string | null;
     config: ApplicationConfig | null;
+    serviceAccountUserId: string | null;
+    serviceAccountUser?: AdminApplicationIdentity | null;
     createdBy: string;
     updatedBy: string;
     createdAt: string;
@@ -6368,6 +6467,36 @@ declare class AdminService {
      * @returns The created entitlement
      */
     createApplicationEntitlement(applicationId: string, options: CreateAdminApplicationEntitlementOptions): Promise<AdminApplicationEntitlementRecord>;
+    /**
+     * Lists client secrets for an application.
+     *
+     * @param applicationId - ID of the application to inspect
+     * @returns Secret metadata without plaintext values
+     */
+    listApplicationSecrets(applicationId: string): Promise<AdminApplicationSecret[]>;
+    /**
+     * Creates a client secret for an application.
+     *
+     * @param applicationId - ID of the application to update
+     * @param options - Optional secret display name
+     * @returns The created secret, including the plaintext value shown only once
+     */
+    createApplicationSecret(applicationId: string, options?: CreateAdminApplicationSecretOptions): Promise<CreatedAdminApplicationSecret>;
+    /**
+     * Deletes one client secret for an application.
+     *
+     * @param applicationId - ID of the application to update
+     * @param secretId - ID of the secret to delete
+     * @returns The deleted secret metadata
+     */
+    deleteApplicationSecret(applicationId: string, secretId: string): Promise<AdminApplicationSecret>;
+    /**
+     * Retires an application's service-account identity.
+     *
+     * @param applicationId - ID of the application to update
+     * @returns The updated application
+     */
+    retireApplicationServiceAccount(applicationId: string): Promise<AdminApplicationRecord>;
     /**
      * Lists all organizations, optionally with member and application previews
      * and totals when a preview size is requested.
@@ -7478,32 +7607,59 @@ declare class AuthClient {
     constructor(apiUrl: string, fetchOptions?: BetterFetchOption);
 }
 
-type DecodedJWTPayload = Omit<JWTPayload, 'assurance'> & {
-    assurance?: JWTPayloadAssurance;
+/** Configuration for an in-memory application token cache. */
+type ApplicationTokenStorageOptions = {
+    /** Base URL of the Auth API. */
+    authApiUrl: string;
+    /** Application identifier used for client-credentials exchanges. */
+    clientId: string;
+    /** Application secret used for client-credentials exchanges. */
+    clientSecret: string;
+    /** Full-jitter upper bound for the first retry delay. Defaults to 100 milliseconds. */
+    initialBackoffMs?: number;
+    /** Maximum number of exchange attempts, including the initial request. Defaults to 3. */
+    maxAttempts?: number;
+    /** Maximum number of organization tokens retained in memory. Defaults to 300. */
+    maxOrganizations?: number;
+};
+/** Per-call retry overrides for {@link ApplicationTokenStorage.getToken}. */
+type GetTokenOptions = {
+    /** Full-jitter upper bound for the first retry delay. */
+    initialBackoffMs?: number;
+    /** Maximum number of exchange attempts, including the initial request. */
+    maxAttempts?: number;
 };
 /**
- * Checks if a JWT token has expired or will expire within a specified time window.
- *
- * @param token - The JWT token string to check
- * @param expiresInMs - Optional time window in milliseconds. If provided, returns `true` if the token will expire within this time window
- * @returns `true` if the token is expired (or will expire within the specified window), `false` otherwise
- *
- * @example
- * ```typescript
- * const token = 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
- *
- * // Check if token is already expired
- * if (isTokenExpired(token)) {
- *   console.log('Token has expired')
- * }
+ * Caches organization-scoped application tokens in memory.
  *
- * // Check if token will expire in the next 5 minutes
- * if (isTokenExpired(token, 5 * 60 * 1000)) {
- *   console.log('Token will expire in the next 5 minutes')
- * }
- * ```
+ * Tokens are reissued one minute before expiry. Cache hits promote their
+ * organization to the most-recently-used position, and insertions beyond the
+ * configured limit evict the least recently used organization. Transient
+ * exchange failures use full-jitter exponential backoff.
  */
-declare function isTokenExpired(token: string, expiresInMs?: number): boolean;
+declare class ApplicationTokenStorage {
+    private readonly auth;
+    private readonly clientId;
+    private readonly clientSecret;
+    private readonly initialBackoffMs;
+    private readonly inFlight;
+    private readonly maxAttempts;
+    private readonly maxOrganizations;
+    private readonly tokens;
+    /** Creates an application token cache for one client-credentials identity. */
+    constructor({ authApiUrl, clientId, clientSecret, initialBackoffMs, maxAttempts, maxOrganizations, }: ApplicationTokenStorageOptions);
+    /** Returns a fresh access token scoped to the requested organization. */
+    getToken(organizationId: string, { initialBackoffMs, maxAttempts, }?: GetTokenOptions): Promise<string>;
+    private exchangeTokenWithRetry;
+    /** Performs the client-credentials exchange for one organization. */
+    protected exchangeToken(organizationId: string): Promise<string>;
+    /** Waits before the next exchange attempt. */
+    protected wait(delayMs: number): Promise<void>;
+}
+
+type DecodedJWTPayload = Omit<JWTPayload, 'assurance'> & {
+    assurance?: JWTPayloadAssurance;
+};
 /**
  * Validates a JWT token by checking its expiration and verifying its signature
  * against the JWKS endpoint.
@@ -7542,5 +7698,5 @@ declare function validateToken(token: string, apiUrl: string): Promise<boolean>;
  */
 declare function extractTokenPayload(token: string): DecodedJWTPayload;
 
-export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthBeginStepUpResponse, OAuthCompleteStepUpResponse, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, STEP_UP_MAX_AGE_SECONDS, SendOtpResponse, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceResponse, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, createAPIClient, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };
-export type { APIClient, AcceptInvitationResult, AdminApplication, AdminApplicationEntitlement, AdminApplicationEntitlementRecord, AdminApplicationMember, AdminApplicationOrganization, AdminApplicationRecord, AdminApplicationRole, AdminEntitlementRule, AdminEntitlementRuleType, AdminEntitlementWithRules, AdminMember, AdminOrganization, AdminOrganizationApplication, AdminOrganizationMember, AdminOrganizationMemberApplication, AdminOrganizationMemberRecord, AdminOrganizationMemberTeam, AdminOrganizationSummary, AdminOrganizationTeam, AdminOrganizationTeamRecord, AdminUser, AdminUserAccess, AdminUserAccessApplication, AdminUserAccessOrganization, AdminUserAccessTeam, AdminUserInvitation, AdminUserOrganization, ApiKey, ApiKeyWithoutSecret, Application, ApplicationAuthContextResponse, AssuranceFields, BaseOrganization, BeginOAuthStepUpParams, BillingMode, CompleteAuthorizationFlowResponse, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminApplicationRoleOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, CreateApiKeyPayload, CreateTeamPayload, DecodedJWTPayload, DeviceAuthorizationActionResponse, DeviceAuthorizationContextResponse, DeviceAuthorizationResponse, DeviceContextApplication, EmailOTPSignInOptions, FullOrganization, GetAdminOrganizationOptions, GetAdminOrganizationsSummaryOptions, Invitation, InviteAdminOrganizationUsersOptions, InviteAdminOrganizationUsersResult, InviteUserToOrganizationOptions, JWTPayloadData, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminUsersOptions, ListAdminUsersResult, ListCandidateOrganizationsResponse, ListMembersOptions, Member, ExtendedOrganization as Organization, OrganizationSettings, RemoveAdminMemberOptions, RemoveUserFromOrganizationOptions, ResendAdminInviteOptions, Role, SendVerificationOTPOptions, Session, SessionAssuranceActions, SessionData, SetAdminEntitlementRulesOptions, SetAdminUserApplicationRoleOptions, SetAdminUserTeamOptions, SignInWithEmailAndPasswordOptions, SignInWithSamlOptions, SocialSignInOptions, StartAuthorizationFlowResponse, Strict, Team, TeamMember, UpdateAdminApplicationRoleOptions, UpdateAdminEntitlementOptions, UpdateAdminMemberRoleOptions, UpdateAdminOrganizationOptions, UpdateApiKeyPayload, UpdateMemberRoleOptions, UpdateOrganizationPayload, UpdateTeamPayload, User, UserProfile, WhoAmIInclude, WhoAmIOptions, WhoAmIOrganization, WhoAmIResponse };
+export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, ApplicationTokenStorage, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthBeginStepUpResponse, OAuthCompleteStepUpResponse, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, STEP_UP_MAX_AGE_SECONDS, SendOtpResponse, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceResponse, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, createAPIClient, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };
+export type { APIClient, AcceptInvitationResult, AdminApplication, AdminApplicationEntitlement, AdminApplicationEntitlementRecord, AdminApplicationIdentity, AdminApplicationMember, AdminApplicationOrganization, AdminApplicationRecord, AdminApplicationRole, AdminApplicationSecret, AdminEntitlementRule, AdminEntitlementRuleType, AdminEntitlementWithRules, AdminMember, AdminOrganization, AdminOrganizationApplication, AdminOrganizationMember, AdminOrganizationMemberApplication, AdminOrganizationMemberRecord, AdminOrganizationMemberTeam, AdminOrganizationSummary, AdminOrganizationTeam, AdminOrganizationTeamRecord, AdminUser, AdminUserAccess, AdminUserAccessApplication, AdminUserAccessOrganization, AdminUserAccessTeam, AdminUserInvitation, AdminUserOrganization, ApiKey, ApiKeyWithoutSecret, Application, ApplicationAuthContextResponse, ApplicationTokenStorageOptions, AssuranceFields, BaseOrganization, BeginOAuthStepUpParams, BillingMode, ClientCredentialsGrant, ClientCredentialsTokenResponse, CompleteAuthorizationFlowResponse, CreateAdminApplicationEntitlementOptions, CreateAdminApplicationOptions, CreateAdminApplicationRoleOptions, CreateAdminApplicationSecretOptions, CreateAdminOrganizationOptions, CreateAdminOrganizationTeamOptions, CreateApiKeyPayload, CreateTeamPayload, CreatedAdminApplicationSecret, DecodedJWTPayload, DeviceAuthorizationActionResponse, DeviceAuthorizationContextResponse, DeviceAuthorizationResponse, DeviceContextApplication, EmailOTPSignInOptions, FullOrganization, GetAdminOrganizationOptions, GetAdminOrganizationsSummaryOptions, GetTokenOptions, Invitation, InviteAdminOrganizationUsersOptions, InviteAdminOrganizationUsersResult, InviteUserToOrganizationOptions, JWTPayloadData, ListAdminApplicationsOptions, ListAdminApplicationsResult, ListAdminOrganizationMembersOptions, ListAdminOrganizationMembersResult, ListAdminOrganizationTeamsOptions, ListAdminOrganizationTeamsResult, ListAdminOrganizationsOptions, ListAdminOrganizationsResult, ListAdminUsersOptions, ListAdminUsersResult, ListCandidateOrganizationsResponse, ListMembersOptions, Member, ExtendedOrganization as Organization, OrganizationSettings, RemoveAdminMemberOptions, RemoveUserFromOrganizationOptions, ResendAdminInviteOptions, Role, SendVerificationOTPOptions, Session, SessionAssuranceActions, SessionData, SetAdminEntitlementRulesOptions, SetAdminUserApplicationRoleOptions, SetAdminUserTeamOptions, SignInWithEmailAndPasswordOptions, SignInWithSamlOptions, SocialSignInOptions, StartAuthorizationFlowResponse, Strict, Team, TeamMember, UpdateAdminApplicationRoleOptions, UpdateAdminEntitlementOptions, UpdateAdminMemberRoleOptions, UpdateAdminOrganizationOptions, UpdateApiKeyPayload, UpdateMemberRoleOptions, UpdateOrganizationPayload, UpdateTeamPayload, User, UserProfile, WhoAmIInclude, WhoAmIOptions, WhoAmIOrganization, WhoAmIResponse };

package/dist/index.mjs

@@ -8,7 +8,20 @@ import { defaultStatements } from 'better-auth/plugins/organization/access';
 import z, { z as z$1 } from 'zod';
 export { APIError } from 'better-auth';
 
-const version = "1.35.0";
+function isTokenExpired(token, expiresInMs) {
+  const payload = JSON.parse(atob(token.split(".")[1] ?? ""));
+  if (!payload.exp)
+    return false;
+  const nowInSeconds = Date.now() / 1e3;
+  const expirationTime = payload.exp;
+  if (expiresInMs !== void 0) {
+    const futureTimeInSeconds = nowInSeconds + expiresInMs / 1e3;
+    return futureTimeInSeconds >= expirationTime;
+  }
+  return nowInSeconds > expirationTime;
+}
+
+const version = "1.36.0";
 
 function parsedEnumValues(schema) {
   return Object.fromEntries(
@@ -187,15 +200,17 @@ const JWTPayload = z$1.object({
 });
 
 const DEVICE_CODE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+const CLIENT_CREDENTIALS_GRANT = "client_credentials";
 function normalizeOrganizationsResponse(response) {
   if (Array.isArray(response)) {
     return {
       data: response
     };
   }
+  const candidate = response;
   return {
-    ...response,
-    data: Array.isArray(response.data) ? response.data : []
+    ...candidate,
+    data: Array.isArray(candidate.data) ? candidate.data : []
   };
 }
 function applicationsPluginClient() {
@@ -273,6 +288,17 @@ function applicationsPluginClient() {
               }
             });
           },
+          exchangeClientCredentialsForToken: async (credentials) => {
+            return await $fetch("/applications/token", {
+              method: "POST",
+              body: {
+                grantType: CLIENT_CREDENTIALS_GRANT,
+                clientId: credentials.clientId,
+                clientSecret: credentials.clientSecret,
+                organizationId: credentials.organizationId
+              }
+            });
+          },
           completeAuthorizationFlow: async (code, codeVerifier) => {
             return await $fetch("/applications/token", {
               method: "POST",
@@ -408,12 +434,23 @@ function createAPIClient(apiUrl, fetchOptions = {}) {
   });
 }
 
-async function readErrorMessage(response) {
+class ApplicationRouteError extends Error {
+  code;
+  details;
+  status;
+  constructor(response, body) {
+    super(body?.error ?? body?.message ?? response.statusText);
+    this.name = "ApplicationRouteError";
+    this.status = response.status;
+    this.code = body?.code;
+    this.details = body?.details;
+  }
+}
+async function readErrorBody(response) {
   try {
-    const body = await response.json();
-    return body.error ?? body.message ?? response.statusText;
+    return await response.json();
   } catch {
-    return response.statusText;
+    return null;
   }
 }
 class AdminService {
@@ -459,7 +496,7 @@ class AdminService {
       ...request.body !== void 0 ? { body: JSON.stringify(request.body) } : {}
     });
     if (!response.ok)
-      throw new Error(await readErrorMessage(response));
+      throw new ApplicationRouteError(response, await readErrorBody(response));
     return await response.json();
   }
   /**
@@ -546,6 +583,53 @@ class AdminService {
       body: options
     });
   }
+  /**
+   * Lists client secrets for an application.
+   *
+   * @param applicationId - ID of the application to inspect
+   * @returns Secret metadata without plaintext values
+   */
+  async listApplicationSecrets(applicationId) {
+    return await this.requestApplicationRoute(`applications/${encodeURIComponent(applicationId)}/secrets`);
+  }
+  /**
+   * Creates a client secret for an application.
+   *
+   * @param applicationId - ID of the application to update
+   * @param options - Optional secret display name
+   * @returns The created secret, including the plaintext value shown only once
+   */
+  async createApplicationSecret(applicationId, options = {}) {
+    return await this.requestApplicationRoute(`applications/${encodeURIComponent(applicationId)}/secrets`, {
+      method: "POST",
+      body: options
+    });
+  }
+  /**
+   * Deletes one client secret for an application.
+   *
+   * @param applicationId - ID of the application to update
+   * @param secretId - ID of the secret to delete
+   * @returns The deleted secret metadata
+   */
+  async deleteApplicationSecret(applicationId, secretId) {
+    return await this.requestApplicationRoute(
+      `applications/${encodeURIComponent(applicationId)}/secrets/${encodeURIComponent(secretId)}`,
+      { method: "DELETE" }
+    );
+  }
+  /**
+   * Retires an application's service-account identity.
+   *
+   * @param applicationId - ID of the application to update
+   * @returns The updated application
+   */
+  async retireApplicationServiceAccount(applicationId) {
+    return await this.requestApplicationRoute(
+      `applications/${encodeURIComponent(applicationId)}/service-account`,
+      { method: "DELETE" }
+    );
+  }
   /**
    * Lists all organizations, optionally with member and application previews
    * and totals when a preview size is requested.
@@ -1359,6 +1443,22 @@ class ApplicationService {
       throwDeviceGrantError(error);
     }
   }
+  /**
+   * Exchanges application client credentials for a service-account access token.
+   *
+   * The returned token is scoped to the requested organization and cannot be
+   * refreshed. Exchange the credentials again when a new token is needed.
+   *
+   * @param credentials - Application credentials and target organization
+   * @returns A short-lived access token with service-account and organization details
+   */
+  async exchangeClientCredentialsForToken(credentials) {
+    const response = await this.client.applications.exchangeClientCredentialsForToken(credentials);
+    if (!response.data) {
+      throw new Error("No data returned from the API", { cause: response.error });
+    }
+    return response.data;
+  }
   /**
    * Completes an authorization flow for a specific application.
    *
@@ -2162,18 +2262,128 @@ class AuthClient {
   }
 }
 
-function isTokenExpired(token, expiresInMs) {
-  const payload = JSON.parse(atob(token.split(".")[1] ?? ""));
-  if (!payload.exp)
-    return false;
-  const nowInSeconds = Date.now() / 1e3;
-  const expirationTime = payload.exp;
-  if (expiresInMs !== void 0) {
-    const futureTimeInSeconds = nowInSeconds + expiresInMs / 1e3;
-    return futureTimeInSeconds >= expirationTime;
+const TOKEN_REFRESH_WINDOW_MS = 6e4;
+const DEFAULT_INITIAL_BACKOFF_MS = 100;
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_MAX_ORGANIZATIONS = 300;
+function validateMaxAttempts(maxAttempts) {
+  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
+    throw new RangeError("maxAttempts must be a positive integer");
+  }
+}
+function validateInitialBackoff(initialBackoffMs) {
+  if (!Number.isFinite(initialBackoffMs) || initialBackoffMs < 0) {
+    throw new RangeError("initialBackoffMs must be a non-negative finite number");
+  }
+}
+function getErrorStatus(error) {
+  const candidates = [error];
+  const visited = /* @__PURE__ */ new Set();
+  while (candidates.length > 0) {
+    const candidate = candidates.shift();
+    if (!candidate || typeof candidate !== "object" || visited.has(candidate))
+      continue;
+    visited.add(candidate);
+    const errorCandidate = candidate;
+    if (typeof errorCandidate.status === "number")
+      return errorCandidate.status;
+    candidates.push(errorCandidate.cause, errorCandidate.error);
+  }
+  return void 0;
+}
+function isTransientError(error) {
+  const status = getErrorStatus(error);
+  return status === void 0 || status === 429 || status >= 500 && status < 600;
+}
+class ApplicationTokenStorage {
+  auth;
+  clientId;
+  clientSecret;
+  initialBackoffMs;
+  inFlight = /* @__PURE__ */ new Map();
+  maxAttempts;
+  maxOrganizations;
+  tokens = /* @__PURE__ */ new Map();
+  /** Creates an application token cache for one client-credentials identity. */
+  constructor({
+    authApiUrl,
+    clientId,
+    clientSecret,
+    initialBackoffMs = DEFAULT_INITIAL_BACKOFF_MS,
+    maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    maxOrganizations = DEFAULT_MAX_ORGANIZATIONS
+  }) {
+    if (!Number.isInteger(maxOrganizations) || maxOrganizations < 1) {
+      throw new RangeError("maxOrganizations must be a positive integer");
+    }
+    validateMaxAttempts(maxAttempts);
+    validateInitialBackoff(initialBackoffMs);
+    this.auth = new AuthClient(authApiUrl);
+    this.clientId = clientId;
+    this.clientSecret = clientSecret;
+    this.initialBackoffMs = initialBackoffMs;
+    this.maxAttempts = maxAttempts;
+    this.maxOrganizations = maxOrganizations;
+  }
+  /** Returns a fresh access token scoped to the requested organization. */
+  async getToken(organizationId, {
+    initialBackoffMs = this.initialBackoffMs,
+    maxAttempts = this.maxAttempts
+  } = {}) {
+    validateMaxAttempts(maxAttempts);
+    validateInitialBackoff(initialBackoffMs);
+    const cachedToken = this.tokens.get(organizationId);
+    if (cachedToken && !isTokenExpired(cachedToken, TOKEN_REFRESH_WINDOW_MS)) {
+      this.tokens.delete(organizationId);
+      this.tokens.set(organizationId, cachedToken);
+      return cachedToken;
+    }
+    const pendingExchange = this.inFlight.get(organizationId);
+    if (pendingExchange) {
+      return await pendingExchange;
+    }
+    const exchange = this.exchangeTokenWithRetry(organizationId, maxAttempts, initialBackoffMs).then((token) => {
+      this.tokens.delete(organizationId);
+      this.tokens.set(organizationId, token);
+      if (this.tokens.size > this.maxOrganizations) {
+        const leastRecentlyUsedOrganization = this.tokens.keys().next().value;
+        if (leastRecentlyUsedOrganization !== void 0) {
+          this.tokens.delete(leastRecentlyUsedOrganization);
+        }
+      }
+      return token;
+    }).finally(() => this.inFlight.delete(organizationId));
+    this.inFlight.set(organizationId, exchange);
+    return await exchange;
+  }
+  async exchangeTokenWithRetry(organizationId, maxAttempts, initialBackoffMs) {
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await this.exchangeToken(organizationId);
+      } catch (error) {
+        if (attempt === maxAttempts || !isTransientError(error))
+          throw error;
+        const exponentialDelay = initialBackoffMs * 2 ** (attempt - 1);
+        await this.wait(Math.random() * exponentialDelay);
+      }
+    }
+    throw new Error("Client credentials exchange exhausted without a result");
+  }
+  /** Performs the client-credentials exchange for one organization. */
+  async exchangeToken(organizationId) {
+    const { accessToken } = await this.auth.application.exchangeClientCredentialsForToken({
+      clientId: this.clientId,
+      clientSecret: this.clientSecret,
+      organizationId
+    });
+    return accessToken;
+  }
+  /** Waits before the next exchange attempt. */
+  async wait(delayMs) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
   }
-  return nowInSeconds > expirationTime;
 }
+
 async function validateToken(token, apiUrl) {
   if (isTokenExpired(token)) {
     return false;
@@ -2195,4 +2405,4 @@ function extractTokenPayload(token) {
   return payload;
 }
 
-export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, STEP_UP_MAX_AGE_SECONDS, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };
+export { AAL, AALBrand, AALs, ACR, ACRBrand, ACRs, AMR, AMRBrand, AMRs, ApiKeyMetadata, ApplicationConfig, ApplicationError, ApplicationSessionAssuranceConfig, ApplicationSessionAssuranceError, ApplicationTokenStorage, AuthClient, AuthMethod, AuthMethodBrand, AuthMethods, AuthorizationFlowError, DEFAULT_APPLICATION_CONFIG, DEFAULT_JWT_ASSURANCE, DEFAULT_SESSION_ASSURANCE_CONFIG, DeviceAccessDeniedError, DeviceAuthorizationPendingError, DeviceAuthorizationSlowDownError, DeviceCodeExpiredError, DeviceTransientServerError, EmailOTPService, EmailRequired, InvalidCallbackURL, InvalidSocialProvider, JWTPayload, JWTPayloadAssurance, JWTPayloadUser, JWTPayloadWorkspace, OAuthStepUpProvider, RefreshTokenExpiredError, Roles, SENSITIVE_ACTION_ASSURANCE_POLICY, STEP_UP_MAX_AGE_SECONDS, SessionAssurancePolicy, SessionAssuranceRequiredError, SessionAssuranceRequiredPayload, SessionAssuranceService, StepUpOption, UserNotLoggedInError, ac, assuranceFields, canStepUpWithAmr, extractTokenPayload, getAalRank, invitationAdditionalFields, isAssuranceSufficientForPolicy, isSessionAssuranceSufficient, isTokenExpired, memberAdditionalFields, mergeStepUpAssurance, organizationAdditionalFields, parseSessionAssuranceRequiredPayload, rolesAccessControl, sessionAssurancePluginClient, userAdditionalFields, validateToken };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meistrari/auth-core",
-  "version": "1.35.0",
+  "version": "1.36.0",
   "type": "module",
   "exports": {
     ".": {