@al/session
Version:
A client for maintaining Alert Logic session data
246 lines (245 loc) • 9.18 kB
TypeScript
/**
* An interface for establishing and persistenting an authenticated AIMS session.
*
* @author Kevin Nielsen <knielsen@alertlogic.com>
* @author Barry Skidmore <bskidmore@alertlogic.com>
* @author Robert Parker <robert.parker@alertlogic.com>
*
* @copyright 2019 Alert Logic, Inc.
*/
import { AIMSAccount, AIMSAuthentication, AIMSSessionDescriptor, AIMSUser, AlApiClient } from '@al/client';
import { AlBehaviorPromise, AlCabinet, AlTriggerStream } from '@al/common';
import { AlEntitlementCollection } from '@al/subscriptions';
import { AlActingAccountResolvedEvent } from './events';
export interface AlSessionOptions {
/**
* Controls whether or not authentication resolves account metadata, like entitlements and managed accounts. Defaults to `true`.
*/
resolveAccountMetadata?: boolean;
/**
* If account metadata is resolved, should the client use the consolidated/gestalt resolver endpoint? Defaults to `false`.
*/
useConsolidatedResolver?: boolean;
}
/**
* AlSessionInstance maintains session data for a specific session.
*/
export declare class AlSessionInstance {
/**
* A stream of events that occur over the lifespan of a user session
*/
notifyStream: AlTriggerStream;
/**
* Protected state properties
*/
protected sessionIsActive: boolean;
protected client: AlApiClient;
protected sessionData: AIMSSessionDescriptor;
/**
* Tracks when the acting account is changing (measured as interval between AlActingAccountChangedEvent and AlActingAccountResolvedEvent)
* and allows systematic access to the last set of resolved data.
*/
protected resolvedAccount: AlActingAccountResolvedEvent;
protected managedAccounts: AIMSAccount[];
protected resolutionGuard: AlBehaviorPromise<boolean>;
protected detectionGuard: AlBehaviorPromise<boolean>;
protected detectionProcesses: number;
protected storage: AlCabinet;
protected options: AlSessionOptions;
constructor(client?: AlApiClient);
reset(flushClientCache?: boolean): void;
setOptions(options: AlSessionOptions): void;
authenticate(username: string, passphrase: string, options?: {
actingAccount?: string | AIMSAccount;
locationId?: string;
}): Promise<boolean>;
authenticateWithSessionToken(sessionToken: string, mfaCode: string, options?: {
actingAccount?: string | AIMSAccount;
locationId?: string;
}): Promise<boolean>;
authenticateWithAccessToken(accessToken: string, options?: {
actingAccount?: string | AIMSAccount;
locationId?: string;
}): Promise<boolean>;
/**
* Sets and persists session data and begins account metadata resolution.
*
* Successful completion of this action triggers an AlSessionStartedEvent so that non-causal elements of an application can respond to
* the change of state.
*/
setAuthentication(proposal: AIMSSessionDescriptor, options?: {
actingAccount?: string | AIMSAccount;
locationId?: string;
}): Promise<AlActingAccountResolvedEvent>;
/**
* Sets the session's acting account.
*
* Successful completion of this action triggers an AlActingAccountChangedEvent so that non-causal elements of an application can respond to
* the change of effective account and entitlements.
*
* @param account {string|AIMSAccount} The AIMSAccount object representating the account to
* focus on.
*
* @returns A promise that resolves
*/
setActingAccount(account: string | AIMSAccount): Promise<AlActingAccountResolvedEvent>;
/**
* Sets the 'active' datacenter. This provides a default residency and API stack to interact with.
*/
setActiveDatacenter(insightLocationId: string): void;
/**
* Retrieves the 'active' datacenter, falling back on the acting account's or primary account's default_location
* as necessary.
*/
getActiveDatacenter(): string;
/**
* Convenience function to set token and expiry values
* Modelled on /aims/v1/:account_id/account
* To be called by AIMS Service
*/
setTokenInfo(token: string, tokenExpiration: number): void;
/**
* Activate Session
*/
activateSession(): boolean;
/**
* Deactivate Session
*/
deactivateSession(): boolean;
/**
* Is the Session Active?
*/
isActive(): boolean;
/**
* Get Session
*/
getSession(): AIMSSessionDescriptor;
/**
* Get Authentication
*/
getAuthentication(): AIMSAuthentication;
getPrimaryAccountId(): string;
getPrimaryAccount(): AIMSAccount;
/**
* Get the ID of the acting account (account the user is currently working in)
*/
getActingAccountId(): string;
/**
* Get acting Account Name - (account the user is currently working in)
*/
getActingAccountName(): string;
/**
* Get Default Location for the acting account
*/
getActingAccountDefaultLocation(): string;
/**
* Get Accessible Locations for the acting account
*/
getActingAccountAccessibleLocations(): string[];
/**
* Get the acting account entity in its entirety
*/
getActingAccount(): AIMSAccount;
/**
* Get Token
*/
getToken(): string;
/**
* Get Token Expiry
*/
getTokenExpiry(): number;
getUser(): AIMSUser;
/**
* Get User ID
*/
getUserId(): string;
/**
* Get User Name
*/
getUserName(): string;
/**
* Get User Email
*/
getUserEmail(): string;
/**
* @deprecated
* Alias for getActingAccountId
*/
getActingAccountID(): string;
getUserID(): string;
/**
* @deprecated
* Please use `getPrimaryAccountId()` instead
*/
getUserAccountID(): string;
/**
* @deprecated
* Get Accessible Locations for the users account
*/
getUserAccessibleLocations(): string[];
/**
* Convenience method to defer logic until ALSession has reached a stable state.
* For the purposes of this service, "ready" is defined as having completed one or more session detection
* cycles AND ( user is unauthenticated OR acting account is resolved ).
*/
ready(): Promise<void>;
/**
* Convenience method to wait until authentication status and metadata have been resolved.
*
* PLEASE NOTE: that this async function will not resolve until authentication is complete and subscriptions metadata
* has been retrieved and collated; in an unauthenticated context, it will never resolve!
*/
resolved(): Promise<void>;
/**
* Retrieves the primary account's entitlements, or null if there is no session.
*/
getPrimaryEntitlementsSync(): AlEntitlementCollection | null;
/**
* Convenience method to retrieve the entitlements for the primary account.
* See caveats for `AlSession.authenticated` method, which also apply to this method.
*/
getPrimaryEntitlements(): Promise<AlEntitlementCollection>;
/**
* Retrieves the acting account's entitlements, or null if there is no session.
*/
getEffectiveEntitlementsSync(): AlEntitlementCollection | null;
/**
* Convenience method to retrieve the entitlements for the current acting account.
* See caveats for `AlSession.authenticated` method, which also apply to this method.
*/
getEffectiveEntitlements(): Promise<AlEntitlementCollection>;
/**
* Convenience method to retrieve the array of accounts managed by the current acting account.
* See caveats for `AlSession.authenticated` method, which also apply to this method.
*/
getManagedAccounts(): Promise<AIMSAccount[]>;
/**
* Allows an external mechanism to indicate that it is detecting a session.
*/
startDetection(): void;
/**
* Allows an external mechanism to indicate that it is done detecting a session.
*/
endDetection(): void;
/**
* Private Internal/Utility Methods
*/
/**
* Get the current timestamp (seconds since the epoch)
*/
protected getCurrentTimestamp(): number;
/**
* A utility method to resolve a partially populated AlActingAccountResolvedEvent instance.
*
* This method will retrieve the full account details, managed accounts, and entitlements for this account
* and then emit an AlActingAccountResolvedEvent through the session's notifyStream.
*/
protected resolveActingAccount(account: AIMSAccount): Promise<AlActingAccountResolvedEvent>;
protected resolveActingAccountConsolidated(account: AIMSAccount): Promise<AlActingAccountResolvedEvent>;
/**
* This is a vastly simplified version of the json schema validator provided by AJV. It isn't as thorough -- it doesn't descend into the 3rd tier of data structures
* or lower -- but it should be sufficient to validate that the right entities are being provided, and not require so many extraneous packages.
*/
protected validateSessionDescriptor(descriptor: any): void;
}
export declare const AlSession: AlSessionInstance;