@travetto/auth-session 6.0.0-rc.0

package/README.md

@@ -0,0 +1,65 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/auth-session/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Auth Session
+
+## Session provider for the travetto auth module.
+
+**Install: @travetto/auth-session**
+```bash
+npm install @travetto/auth-session
+
+# or
+
+yarn add @travetto/auth-session
+```
+
+This is a module that adds session support to the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework") framework, via [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") storage.  The concept here, is that the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework") module provides the solid foundation for ensuring authentication to the system, and transitively to the session data. The [Principal](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L8) provides a session identifier, which refers to a unique authentication session.  Each login will produce a novel session id.  This id provides the contract between [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework") and[Auth Session](https://github.com/travetto/travetto/tree/main/module/auth-session#readme "Session provider for the travetto auth module.").  
+
+This session identifier, is then used when retrieving data from [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") storage. This storage mechanism is not tied to a request/response model, but the [Rest Auth Session](https://github.com/travetto/travetto/tree/main/module/auth-rest-session#readme "Rest authentication session integration support for the Travetto framework") does provide a natural integration with the [RESTful API](https://github.com/travetto/travetto/tree/main/module/rest#readme "Declarative api for RESTful APIs with support for the dependency injection module.") module.   
+
+Within the framework the sessions are stored against any [Data Modeling Support](https://github.com/travetto/travetto/tree/main/module/model#readme "Datastore abstraction for core operations.") implementation that provides [ModelExpirySupport](https://github.com/travetto/travetto/tree/main/module/model/src/service/expiry.ts), as the data needs to be able to be expired appropriately.  The list of supported model providers are:
+   *  [Redis Model Support](https://github.com/travetto/travetto/tree/main/module/model-redis#readme "Redis backing for the travetto model module.")
+   *  [MongoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-mongo#readme "Mongo backing for the travetto model module.")
+   *  [S3 Model Support](https://github.com/travetto/travetto/tree/main/module/model-s3#readme "S3 backing for the travetto model module.")
+   *  [DynamoDB Model Support](https://github.com/travetto/travetto/tree/main/module/model-dynamodb#readme "DynamoDB backing for the travetto model module.")
+   *  [Elasticsearch Model Source](https://github.com/travetto/travetto/tree/main/module/model-elasticsearch#readme "Elasticsearch backing for the travetto model module, with real-time modeling support for Elasticsearch mappings.")
+   *  [File Model Support](https://github.com/travetto/travetto/tree/main/module/model-file#readme "File system backing for the travetto model module.")
+   *  [Memory Model Support](https://github.com/travetto/travetto/tree/main/module/model-memory#readme "Memory backing for the travetto model module.")
+While the expiry is not necessarily a hard requirement, the implementation without it can be quite messy.  To that end, the ability to add [ModelExpirySupport](https://github.com/travetto/travetto/tree/main/module/model/src/service/expiry.ts) to the model provider would be the natural extension point if more expiry support is needed.
+
+**Code: Sample usage of Session Service**
+```typescript
+class RestSessionConfig implements ManagedInterceptorConfig { }
+
+/**
+ * Loads session, and provides ability to create session as needed, persists when complete.
+ */
+@Injectable()
+export class AuthSessionInterceptor implements RestInterceptor {
+
+  dependsOn: Class<RestInterceptor>[] = [AuthContextInterceptor];
+  runsBefore: Class<RestInterceptor>[] = [];
+
+  @Inject()
+  service: SessionService;
+
+  @Inject()
+  config: RestSessionConfig;
+
+  async intercept(ctx: FilterContext, next: FilterNext): Promise<unknown> {
+    try {
+      await this.service.load();
+      Object.defineProperty(ctx.req, 'session', { get: () => this.service.getOrCreate() });
+      return await next();
+    } finally {
+      await this.service.persist();
+    }
+  }
+}
+```
+
+The [SessionService](https://github.com/travetto/travetto/tree/main/module/auth-session/src/service.ts#L16) provides the basic integration with the [AuthContext](https://github.com/travetto/travetto/tree/main/module/auth/src/context.ts#L16) to authenticate and isolate session data.  The usage is fairly simple, but the import pattern to follow is:
+   *  load
+   *  read/modify
+   *  persist
+And note, persist is intelligent enough to only update the data store if the expiration date has changed or if the data in the session has been modified.

package/__index__.ts

@@ -0,0 +1,3 @@
+export * from './src/service';
+export * from './src/model';
+export * from './src/session';

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@travetto/auth-session",
+  "version": "6.0.0-rc.0",
+  "description": "Session provider for the travetto auth module.",
+  "keywords": [
+    "auth",
+    "session",
+    "travetto",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src",
+    "support"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/auth-session"
+  },
+  "dependencies": {
+    "@travetto/auth": "^6.0.0-rc.0",
+    "@travetto/config": "^6.0.0-rc.0",
+    "@travetto/model": "^6.0.0-rc.0"
+  },
+  "peerDependencies": {
+    "@travetto/test": "^6.0.0-rc.0"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/test": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "displayName": "Auth Session"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/internal/types.ts

@@ -0,0 +1,4 @@
+/**
+ * Session data, will basically be a key/value map
+ */
+export class SessionDataTarget { }

package/src/model.ts

@@ -0,0 +1,18 @@
+import { Model, ExpiresAt } from '@travetto/model';
+import { Text } from '@travetto/schema';
+
+/**
+ * Session model service identifier
+ */
+export const SessionModelSymbol = Symbol.for('@travetto/auth-session:model');
+
+@Model({ autoCreate: false })
+export class SessionEntry {
+  id: string;
+  @Text()
+  data: string;
+  @ExpiresAt()
+  expiresAt?: Date;
+  issuedAt: Date;
+  maxAge?: number;
+}

package/src/service.ts

@@ -0,0 +1,157 @@
+import { Injectable, Inject } from '@travetto/di';
+import { isStorageSupported } from '@travetto/model/src/internal/service/common';
+import { Runtime, Util } from '@travetto/runtime';
+import { ModelExpirySupport, NotFoundError } from '@travetto/model';
+import { AsyncContext, AsyncContextValue } from '@travetto/context';
+import { AuthContext, AuthenticationError, AuthService } from '@travetto/auth';
+
+import { Session } from './session';
+import { SessionEntry, SessionModelSymbol } from './model';
+
+/**
+ * Rest service for supporting the session and managing the session state
+ * during the normal lifecycle of requests.
+ */
+@Injectable()
+export class SessionService {
+
+  @Inject()
+  context: AsyncContext;
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Inject()
+  authService: AuthService;
+
+  #modelService: ModelExpirySupport;
+
+  #session = new AsyncContextValue<Session>(this);
+
+  constructor(@Inject(SessionModelSymbol) service: ModelExpirySupport) {
+    this.#modelService = service;
+  }
+
+  /**
+   * Disconnect active session
+   */
+  clear(): void {
+    this.#session.set(undefined);
+  }
+
+  /**
+   * Initialize service if none defined
+   */
+  async postConstruct(): Promise<void> {
+    if (isStorageSupported(this.#modelService) && Runtime.dynamic) {
+      await this.#modelService.createModel?.(SessionEntry);
+    }
+  }
+
+  /**
+   * Load session by id
+   * @returns Session if valid
+   */
+  async #load(id: string): Promise<Session | undefined> {
+    try {
+      const record = await this.#modelService.get(SessionEntry, id);
+
+      const session = new Session({
+        ...record,
+        data: Util.decodeSafeJSON(record.data)
+      });
+
+      // Validate session
+      if (session.isExpired()) {
+        await this.#modelService.delete(SessionEntry, session.id).catch(() => { });
+        return new Session({ action: 'destroy' });
+      } else {
+        return session;
+      }
+    } catch (err) {
+      if (!(err instanceof NotFoundError)) {
+        throw err; // If not a not found error, throw
+      }
+    }
+  }
+
+  /**
+   * Persist session
+   */
+  async persist(): Promise<void> {
+    const session = this.#session.get();
+
+    // If missing or new and no data
+    if (!session || (session.action === 'create' && session.isEmpty())) {
+      return;
+    }
+
+    // Ensure latest expiry information before persisting
+    await this.authService.manageExpiry(this.authContext.principal);
+
+    const p = this.authContext.principal;
+
+    // If not destroying, write to response, and store
+    if (p && session.action !== 'destroy') {
+      session.expiresAt = p.expiresAt;
+      session.issuedAt = p.issuedAt!;
+
+      // If expiration time has changed, send new session information
+      if (session.action === 'create' || session.isChanged()) {
+        await this.#modelService.upsert(SessionEntry, SessionEntry.from({
+          ...session,
+          data: Util.encodeSafeJSON(session.data)
+        }));
+      }
+      // If destroying
+    } else if (session.id) { // If destroy and id
+      await this.#modelService.delete(SessionEntry, session.id).catch(() => { });
+    }
+  }
+
+  /**
+   * Get or recreate session
+   */
+  getOrCreate(): Session {
+    const principal = this.authContext.principal;
+    if (!principal) {
+      throw new AuthenticationError('Unable to establish session without first authenticating');
+    }
+    const existing = this.#session.get();
+    const val = (existing?.action === 'destroy' ? undefined : existing) ??
+      new Session({
+        id: principal.sessionId,
+        expiresAt: principal.expiresAt,
+        issuedAt: principal.issuedAt,
+        action: 'create',
+        data: {},
+      });
+    this.#session.set(val);
+    return val;
+  }
+
+  /**
+   * Get session if defined
+   */
+  get(): Session | undefined {
+    return this.#session.get();
+  }
+
+  /**
+   * Load from request
+   */
+  async load(): Promise<Session | undefined> {
+    if (!this.#session.get()) {
+      const principal = this.authContext.principal;
+      if (principal?.sessionId) {
+        this.#session.set(await this.#load(principal.sessionId));
+      }
+    }
+    return this.#session.get();
+  }
+
+  destroy(): void {
+    this.get()?.destroy();
+    this.clear();
+  }
+}

package/src/session.ts

@@ -0,0 +1,128 @@
+import { AnyMap, castKey, castTo } from '@travetto/runtime';
+
+/**
+ * @concrete ./internal/types#SessionDataTarget
+ * @augments `@travetto/rest:Context`
+ */
+export interface SessionData extends AnyMap { }
+
+/**
+ * Full session object, with metadata
+ * @augments `@travetto/rest:Context`
+ */
+export class Session<T extends SessionData = SessionData> {
+  /**
+   * The expiry time when the session was loaded
+   */
+  #expiresAtLoaded: Date | undefined;
+  /**
+   * The payload of the session at load
+   */
+  #payload: string;
+  /**
+   * The session identifier
+   */
+  readonly id: string;
+  /**
+   * Session signature
+   */
+  readonly signature?: string;
+
+  /**
+   * Session initial issue timestamp
+   */
+  issuedAt: Date;
+  /**
+   * Expires at time
+   */
+  expiresAt: Date | undefined;
+  /**
+   * What action should be taken against the session
+   */
+  action?: 'create' | 'destroy' | 'modify';
+  /**
+   * The session data
+   */
+  data: T | undefined;
+
+  /**
+   * Create a new Session object given a partial version of itself
+   */
+  constructor(data: Partial<Session>) {
+    // Mark the issued at as now
+    this.issuedAt = new Date();
+
+    // Overwrite with data
+    Object.assign(this, data);
+
+    // Mark the expiry load time
+    this.#expiresAtLoaded = this.expiresAt ?? new Date();
+
+    // Hash the session as it stands
+    this.#payload = JSON.stringify(this);
+  }
+
+  /**
+   * Get session value
+   */
+  getValue<V>(key: string): V | undefined {
+    return this.data && key in this.data ? this.data[key] : undefined;
+  }
+
+  /**
+   * Set session value
+   */
+  setValue<V>(key: string, value: V): void {
+    const data = (this.data ??= castTo({}))!;
+    data[castKey<T>(key)] = castTo(value);
+  }
+
+  /**
+   * Determine if session has changed
+   */
+  isChanged(): boolean {
+    return this.isTimeChanged() || this.#payload !== JSON.stringify(this);
+  }
+
+  /**
+   * Determine if the expiry time has changed
+   */
+  isTimeChanged(): boolean {
+    return this.expiresAt !== undefined && this.expiresAt !== this.#expiresAtLoaded;
+  }
+
+  /**
+   * See if the session is truly expired
+   */
+  isExpired(): boolean {
+    return !!this.expiresAt && this.expiresAt.getTime() < Date.now();
+  }
+
+  /**
+   * See if session is empty, has any data been written
+   */
+  isEmpty(): boolean {
+    return !Object.keys(this.data ?? {}).length;
+  }
+
+  /**
+   * Mark the session for destruction, delete the data
+   */
+  destroy(): void {
+    this.action = 'destroy';
+    delete this.data;
+  }
+
+  /**
+   * Serialize the session
+   */
+  toJSON(): unknown {
+    return {
+      id: this.id,
+      signature: this.signature,
+      expiresAt: this.expiresAt?.getTime(),
+      issuedAt: this.issuedAt?.getTime(),
+      data: this.data
+    };
+  }
+}

package/support/test/server.ts

@@ -0,0 +1,72 @@
+import assert from 'node:assert';
+
+import { Suite, Test } from '@travetto/test';
+import { Inject } from '@travetto/di';
+import { SessionService } from '@travetto/auth-session';
+import { AuthContext, AuthenticationError } from '@travetto/auth';
+import { AsyncContext, WithAsyncContext } from '@travetto/context';
+import { Util } from '@travetto/runtime';
+
+import { InjectableSuite } from '@travetto/di/support/test/suite';
+import { BaseRestSuite } from '@travetto/rest/support/test/base';
+
+@Suite()
+@InjectableSuite()
+export abstract class AuthSessionServerSuite extends BaseRestSuite {
+
+  timeScale = 1;
+
+  @Inject()
+  auth: AuthContext;
+
+  @Inject()
+  session: SessionService;
+
+  @Inject()
+  context: AsyncContext;
+
+  @WithAsyncContext()
+  @Test()
+  async testSessionEstablishment() {
+    await this.auth.init();
+
+    this.auth.principal = {
+      id: 'orange',
+      details: {},
+      sessionId: Util.uuid()
+    };
+
+    assert(this.session.get() === undefined);
+    assert(await this.session.load() === undefined);
+
+    const sess = this.session.getOrCreate();
+    assert(sess.id === this.auth.principal.sessionId);
+    sess.data = { name: 'bob' };
+    await this.session.persist();
+
+    this.session.clear(); // Disconnect
+
+    assert(await this.session.load() !== undefined);
+    const sess2 = this.session.getOrCreate();
+    assert(sess2.data?.name === 'bob');
+
+    this.auth.principal = {
+      id: 'orange',
+      details: {},
+      sessionId: Util.uuid()
+    };
+
+    this.session.clear(); // Disconnect
+
+    assert(await this.session.load() === undefined);
+    const sess3 = this.session.getOrCreate();
+    assert.deepStrictEqual(sess3.data, {});
+  }
+
+  @WithAsyncContext()
+  @Test()
+  async testUnauthenticatedSession() {
+    await assert.throws(() => this.session.getOrCreate(), AuthenticationError);
+
+  }
+}