Sessions
The SessionManager class is responsible for creating, verifying, and managing session tokens. It integrates with a database and a key management system to ensure secure token handling.
Specification
Session
The Session class manages session tokens, specifically handling their storage, retrieval, and lifecycle.
static async createSession(...):Promise<Session>
Creates and initialises a 'Session' instance.
Parameters:
An object containing:
sessionTokenPath: File path for storing the session token.
fs: File system module (default require('fs')).
logger: Logger instance (default new Logger(this.name)).
sessionToken: Optional session token for initialization.
fresh: Flag to indicate if the session should start fresh (default false).
Returns:
Promise<Session>: Resolves to an instance of Session.
Usage Example:
const session = await Session.createSession({
sessionTokenPath: '/path/to/token',
fs: require('fs'),
logger: new Logger('Session'),
sessionToken: 'yourSessionToken',
fresh: true,
});
public async start(...):Promise<void>
Starts the session, optionally clearing existing token and writing a new token if required.
Parameters:
An object containing:
sessionToken: Optional session token for initialization
fresh: Flag to indicate if session should be fresh (default is false)
Usage Example:
await session.start({
sessionToken: 'newSessionToken',
fresh: true,
});
public async stop(...): Promise<void>
Stops the session
Usage Example:
await session.stop();
public async destroy(...)
Destroys the session, removes the session token file.
Usage Example:
await session.destroy();
public async readToken():Promise<SessionToken | undefined>
Reads the session token from the file.
Returns:
Promise<SessionToken | undefined>: Resolves to the session token if it exists, otherwise undefined.
Usage Example:
const sessionToken = await session.readToken();
if (sessionToken) {
console.log('Session token:', sessionToken);
} else {
console.log('No session token available.');
}
public async writeToken(sessionToken: SessionToken):Promise<void>`
Writes the session token to the file
Parameters:
sessionToken: The session token to write.
Usage Example:
await session.writeToken('yourNewSessionToken');
SessionManager
static async createSessionManager(...): Promise<SessionManager>
Creates and initialises an instance of SessionManager. This static method sets up the necessary database and key ring dependencies and starts the session manager.
Parameters:
An object containing:
db: The database instance.
keyRing: The key management system.
expiry: Optional expiry time for the session tokens.
logger: Optional logger instance.
fresh: Optional flag to indicate if the session manager should start fresh.
Returns:
Promise<SessionManager>: A promise that resolves to an instance of SessionManager.
Usage Example:
const sessionManager = await SessionManager.createSessionManager({
db: databaseInstance,
keyRing: keyRingInstance,
expiry: 3600, // token expiry in seconds
logger: new Logger('SessionManager'),
fresh: false,
});
public async start(...): Promise<void>
Starts the session manager. This method sets up the session key and prepares the manager for operation.
Parameters:
An optional object containing:
fresh: Indicates whether to clear existing session data.
Usage Example:
await sessionManager.start({ fresh: true });
public async stop(...): Promise<void>
Stops the session manager. This method ensures a clean shutdown of the manager.
Usage Example:
await sessionManager.stop();
public async destroy(...)
Destroys the session manager instance, clearing all session-related data from the database.
Usage Example:
await sessionManager.destroy();
public async resetKey(tran?: DBTransaction):Promise<void>
Resets the session key. This generates a new key for session token encryption/
Parameters:
tran?: Database transaction.
Usage Example:
await sessionManager.resetKey();
// or with a transaction
await sessionManager.resetKey(dbTransaction);
public async createToken(...):Promise<SessionToken>
Creates a new session token.
Parameters:
tran?: Database transaction.
expiry?: Custom expiry for the token
Returns:
Promise<SessionToken>: Promise resolves to a new session token.
Usage Example:
const sessionToken = await sessionManager.createToken(1800); // 30 minutes expiry
// or with a transaction
const sessionToken = await sessionManager.createToken(1800, dbTransaction);
public async verifyToken(...):Promise<boolean>
Creates a new session token.
Parameters:
token: The session token to verify.
tran?: Database transaction.
Returns:
Promise<boolean>: Resolves to true if valid, else false.
Usage Example:
const isValid = await sessionManager.verifyToken(yourSessionToken);
if (isValid) {
console.log('Token is valid.');
} else {
console.log('Token is invalid.');
}
public async setupKey():Promise<Buffer>
Sets up the session key. This method ensures that a valid session key is available, generating a new one if necessary.
Returns:
Promise<Buffer>: Resolves to session key.
Usage Example:
const sessionKey = await sessionManager.setupKey();