Skip to main content

User Sessions

Introduction to User Sessions​

User sessions are crucial for managing security, auditing, and metrics in modern applications. Vramework provides an optional session service to handle permissions and validate user sessions effectively.

Session Service API​

The session service in Vramework follows a simple structure. It may evolve to handle more data from requests, like the origin, but currently, the session creation responsibility remains inside of the userland login/session related functions.

export interface SessionService<UserSession = CoreUserSession> {
    getUserSession: (credentialsRequired: boolean, headers: Record<string, string>) => Promise<UserSession | undefined>;
}

If a session service is registered within the singleton services, Vramework will automatically use it to validate the user session.

Default Session Service​

The default implementation provided by Vramework is called VrameworkSessionService.

Retrieving a Session​

The VrameworkSessionService attempts to retrieve a session using the following mechanisms, in this order:

1. API Key in Header (x-api-key)​

An API key can be passed via the x-api-key header. Vramework will call the provided getSessionForAPIKey function to retrieve the user session. If the API key is present but not handled, an error will be thrown.

2. JWT Token in Authorization Header​

This follows the standard JWT workflow. The JWT token is retrieved from the Authorization header and decoded using the JWTService.

Vramework can retrieve a session via cookies. The cookie name can be set via the cookieNames option. In cases where the cookie name is determined by the host, use the cookieNameIsOrigin option.

Once the cookie is located, Vramework calls getSessionForCookieValue to retrieve the user session.

Transforming Sessions​

Sometimes, additional data needs to be included in the session beyond what is stored in a JWT. For example, sensitive information that shouldn't be stored in the token itself. Vramework allows this transformation using transformSession, which can add or modify session data.

Example Initialization​

Here's an example of initializing a session service with JWT support and session transformation:

const jwtService = new JWTService<UserSession>(async () => [
  {
    keyid: 'my-first-key',
    secret: 'the-yellow-puppet'
  },
  {
    keyid: 'my-new-key',
    secret: 'the-purple-banana'
  }
]);

const vrameworkSessionService = new VrameworkSessionService(
  jwtService,
  {
    getSessionForAPIKey: async (apiKey: string) => {
      if (apiKey === 'top-secret') {
        return topSecretUserSession;
      }
    },
    transformSession: async (session: any) => {
      return {
        ...session,
        privateSessionData: {
          dateOfBirth: '20230401'
        }
      };
    }
  }
);

This configuration allows Vramework to validate and transform sessions, ensuring flexibility and security in handling user data.