@travetto/auth-web 6.0.0-rc.4

package/README.md

@@ -0,0 +1,292 @@
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify https://github.com/travetto/travetto/tree/main/module/auth-web/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Web Auth
+
+## Web authentication integration support for the Travetto framework
+
+**Install: @travetto/auth-web**
+```bash
+npm install @travetto/auth-web
+
+# or
+
+yarn add @travetto/auth-web
+```
+
+This is a primary integration for the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework") module with the [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") module. 
+
+The integration with the [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") module touches multiple levels. Primarily:
+   *  Authenticating
+   *  Maintaining Auth Context
+   *  Endpoint Decoration
+   *  Multi-Step Login
+
+## Authenticating
+Every external framework integration relies upon the [Authenticator](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L9) contract.  This contract defines the boundaries between both frameworks and what is needed to pass between. As stated elsewhere, the goal is to be as flexible as possible, and so the contract is as minimal as possible:
+
+**Code: Structure for the Identity Source**
+```typescript
+import { AnyMap } from '@travetto/runtime';
+import { Principal } from './principal.ts';
+
+/**
+ * Represents the general shape of additional login context, usually across multiple calls
+ *
+ * @concrete
+ */
+export interface AuthenticatorState extends AnyMap { }
+
+/**
+ * Supports validation payload of type T into an authenticated principal
+ *
+ * @concrete
+ */
+export interface Authenticator<T = unknown, C = unknown, P extends Principal = Principal> {
+  /**
+   * Retrieve the authenticator state for the given request
+   */
+  getState?(context?: C): Promise<AuthenticatorState | undefined> | AuthenticatorState | undefined;
+
+  /**
+   * Verify the payload, ensuring the payload is correctly identified.
+   *
+   * @returns Valid principal if authenticated
+   * @returns undefined if authentication is valid, but incomplete (multi-step)
+   * @throws AppError if authentication fails
+   */
+  authenticate(payload: T, context?: C): Promise<P | undefined> | P | undefined;
+}
+```
+
+The only required method to be defined is the `authenticate` method.  This takes in a pre-principal payload and a filter context with a [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11), and is responsible for:
+   *  Returning an [Principal](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L7) if authentication was successful
+   *  Throwing an error if it failed
+   *  Returning undefined if the authentication is multi-staged and has not completed yet
+A sample auth provider would look like:
+
+**Code: Sample Identity Source**
+```typescript
+import { AuthenticationError, Authenticator } from '@travetto/auth';
+
+type User = { username: string, password: string };
+
+export class SimpleAuthenticator implements Authenticator<User> {
+  async authenticate({ username, password }: User) {
+    if (username === 'test' && password === 'test') {
+      return {
+        id: 'test',
+        source: 'simple',
+        permissions: [],
+        details: {
+          username: 'test'
+        }
+      };
+    } else {
+      throw new AuthenticationError('Invalid credentials');
+    }
+  }
+}
+```
+
+The provider must be registered with a custom symbol to be used within the framework.  At startup, all registered [Authenticator](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L9)'s are collected and stored for reference at runtime, via symbol. For example:
+
+**Code: Potential Facebook provider**
+```typescript
+import { InjectableFactory } from '@travetto/di';
+
+import { SimpleAuthenticator } from './source.ts';
+
+export const FbAuthSymbol = Symbol.for('auth-facebook');
+
+export class AppConfig {
+  @InjectableFactory(FbAuthSymbol)
+  static facebookIdentity() {
+    return new SimpleAuthenticator();
+  }
+}
+```
+
+The symbol `FB_AUTH` is what will be used to reference providers at runtime.  This was chosen, over `class` references due to the fact that most providers will not be defined via a new class, but via an [@InjectableFactory](https://github.com/travetto/travetto/tree/main/module/di/src/decorator.ts#L70) method.
+
+## Maintaining Auth Context
+The [AuthContextInterceptor](https://github.com/travetto/travetto/tree/main/module/auth-web/src/interceptors/context.ts#L19) acts as the bridge between the [Authentication](https://github.com/travetto/travetto/tree/main/module/auth#readme "Authentication scaffolding for the Travetto framework") and [Web API](https://github.com/travetto/travetto/tree/main/module/web#readme "Declarative api for Web Applications with support for the dependency injection.") modules.  It serves to take an authenticated principal (via the [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11)/[WebResponse](https://github.com/travetto/travetto/tree/main/module/web/src/types/response.ts#L3)) and integrate it into the [AuthContext](https://github.com/travetto/travetto/tree/main/module/auth/src/context.ts#L14). Leveraging [WebAuthConfig](https://github.com/travetto/travetto/tree/main/module/auth-web/src/config.ts#L8)'s configuration allows for basic control of how the principal is encoded and decoded, primarily with the choice between using a header or a cookie, and which header, or cookie value is specifically referenced.  Additionally, the encoding process allows for auto-renewing of the token (on by default). The information is encoded into the [JWT](https://jwt.io/) appropriately, and when encoding using cookies, is also  set as the expiry time for the cookie.  
+
+**Note for Cookie Use:** The automatic renewal, update, seamless receipt and transmission of the [Principal](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L7) cookie act as a light-weight session.  Generally the goal is to keep the token as small as possible, but for small amounts of data, this pattern proves to be fairly sufficient at maintaining a decentralized state. 
+
+The [PrincipalCodec](https://github.com/travetto/travetto/tree/main/module/auth-web/src/types.ts#L10) contract is the primary interface for reading and writing [Principal](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L7) data out of the [WebRequest](https://github.com/travetto/travetto/tree/main/module/web/src/types/request.ts#L11). This contract is flexible by design, allowing for all sorts of usage. [JWTPrincipalCodec](https://github.com/travetto/travetto/tree/main/module/auth-web/src/codec.ts#L15) is the default [PrincipalCodec](https://github.com/travetto/travetto/tree/main/module/auth-web/src/types.ts#L10), leveraging [JWT](https://jwt.io/)s for encoding/decoding the principal information.
+
+**Code: JWTPrincipalCodec**
+```typescript
+import { createVerifier, create, Jwt, Verifier, SupportedAlgorithms } from 'njwt';
+
+import { AuthContext, AuthenticationError, AuthToken, Principal } from '@travetto/auth';
+import { Injectable, Inject } from '@travetto/di';
+import { WebResponse, WebRequest, WebAsyncContext, CookieJar } from '@travetto/web';
+import { AppError, castTo, TimeUtil } from '@travetto/runtime';
+
+import { CommonPrincipalCodecSymbol, PrincipalCodec } from './types.ts';
+import { WebAuthConfig } from './config.ts';
+
+/**
+ * JWT Principal codec
+ */
+@Injectable(CommonPrincipalCodecSymbol)
+export class JWTPrincipalCodec implements PrincipalCodec {
+
+  @Inject()
+  config: WebAuthConfig;
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Inject()
+  webAsyncContext: WebAsyncContext;
+
+  #verifier: Verifier;
+  #algorithm: SupportedAlgorithms = 'HS256';
+
+  postConstruct(): void {
+    this.#verifier = createVerifier()
+      .setSigningAlgorithm(this.#algorithm)
+      .withKeyResolver((kid, cb) => {
+        const rec = this.config.keyMap[kid];
+        return cb(rec ? null : new AuthenticationError('Invalid'), rec.key);
+      });
+  }
+
+  async verify(token: string): Promise<Principal> {
+    try {
+      const jwt: Jwt & { body: { core: Principal } } = await new Promise((res, rej) =>
+        this.#verifier.verify(token, (err, v) => err ? rej(err) : res(castTo(v)))
+      );
+      return jwt.body.core;
+    } catch (err) {
+      if (err instanceof Error && err.name.startsWith('Jwt')) {
+        throw new AuthenticationError(err.message, { category: 'permissions' });
+      }
+      throw err;
+    }
+  }
+
+  token(request: WebRequest): AuthToken | undefined {
+    const value = (this.config.mode === 'header') ?
+      request.headers.getWithPrefix(this.config.header, this.config.headerPrefix) :
+      this.webAsyncContext.getValue(CookieJar).get(this.config.cookie, { signed: false });
+    return value ? { type: 'jwt', value } : undefined;
+  }
+
+  async decode(request: WebRequest): Promise<Principal | undefined> {
+    const token = this.token(request);
+    return token ? await this.verify(token.value) : undefined;
+  }
+
+  async create(value: Principal, keyId: string = 'default'): Promise<string> {
+    const keyRec = this.config.keyMap[keyId];
+    if (!keyRec) {
+      throw new AppError('Requested unknown key for signing');
+    }
+    const jwt = create({}, '-')
+      .setExpiration(value.expiresAt!)
+      .setIssuedAt(TimeUtil.asSeconds(value.issuedAt!))
+      .setClaim('core', castTo({ ...value }))
+      .setIssuer(value.issuer!)
+      .setJti(value.sessionId!)
+      .setSubject(value.id)
+      .setHeader('kid', keyRec.id)
+      .setSigningKey(keyRec.key)
+      .setSigningAlgorithm(this.#algorithm);
+    return jwt.toString();
+  }
+
+  async encode(response: WebResponse, data: Principal | undefined): Promise<WebResponse> {
+    const token = data ? await this.create(data) : undefined;
+    const { header, headerPrefix, cookie } = this.config;
+    if (this.config.mode === 'header') {
+      response.headers.setWithPrefix(header, token, headerPrefix);
+    } else {
+      this.webAsyncContext.getValue(CookieJar).set({ name: cookie, value: token, signed: false, expires: data?.expiresAt });
+    }
+    return response;
+  }
+}
+```
+
+As you can see, the encode token just creates a [JWT](https://jwt.io/) based on the principal provided, and decoding verifies the token, and returns the principal. 
+
+A trivial/sample custom [PrincipalCodec](https://github.com/travetto/travetto/tree/main/module/auth-web/src/types.ts#L10) can be seen here:
+
+**Code: Custom Principal Codec**
+```typescript
+import { Principal } from '@travetto/auth';
+import { PrincipalCodec } from '@travetto/auth-web';
+import { Injectable } from '@travetto/di';
+import { BinaryUtil } from '@travetto/runtime';
+import { WebResponse, WebRequest } from '@travetto/web';
+
+@Injectable()
+export class CustomCodec implements PrincipalCodec {
+  secret: string;
+
+  decode(request: WebRequest): Promise<Principal | undefined> | Principal | undefined {
+    const [userId, sig] = request.headers.get('USER_ID')?.split(':') ?? [];
+    if (userId && sig === BinaryUtil.hash(userId + this.secret)) {
+      let p: Principal | undefined;
+      // Lookup user from db, remote system, etc.,
+      return p;
+    }
+    return;
+  }
+  encode(response: WebResponse, data: Principal | undefined): WebResponse {
+    if (data) {
+      response.headers.set('USER_ID', `${data.id}:${BinaryUtil.hash(data.id + this.secret)}`);
+    }
+    return response;
+  }
+}
+```
+
+This implementation is not suitable for production, but shows the general pattern needed to integrate with any principal source.
+
+## Endpoint Decoration
+[@Login](https://github.com/travetto/travetto/tree/main/module/auth-web/src/decorator.ts#L13) integrates with middleware that will authenticate the user as defined by the specified providers, or throw an error if authentication is unsuccessful.
+
+[@Logout](https://github.com/travetto/travetto/tree/main/module/auth-web/src/decorator.ts#L48) integrates with middleware that will automatically deauthenticate a user, throw an error if the user is unauthenticated.
+
+**Code: Using provider with endpoints**
+```typescript
+import { Controller, Get, ContextParam, WebResponse } from '@travetto/web';
+import { Login, Authenticated, Logout } from '@travetto/auth-web';
+import { Principal } from '@travetto/auth';
+
+import { FbAuthSymbol } from './facebook.ts';
+
+@Controller('/auth')
+export class SampleAuth {
+
+  @ContextParam()
+  user: Principal;
+
+  @Get('/simple')
+  @Login(FbAuthSymbol)
+  async simpleLogin() {
+    return WebResponse.redirect('/auth/self');
+  }
+
+  @Get('/self')
+  @Authenticated()
+  async getSelf() {
+    return this.user;
+  }
+
+  @Get('/logout')
+  @Logout()
+  async logout() {
+    return WebResponse.redirect('/auth/self');
+  }
+}
+```
+
+[@Authenticated](https://github.com/travetto/travetto/tree/main/module/auth-web/src/decorator.ts#L25) and [@Unauthenticated](https://github.com/travetto/travetto/tree/main/module/auth-web/src/decorator.ts#L37) will simply enforce whether or not a user is logged in and throw the appropriate error messages as needed. Additionally, the [Principal](https://github.com/travetto/travetto/tree/main/module/auth/src/types/principal.ts#L7) is accessible as a resource that can be exposed as a [@ContextParam](https://github.com/travetto/travetto/tree/main/module/web/src/decorator/param.ts#L61) on an [@Injectable](https://github.com/travetto/travetto/tree/main/module/di/src/decorator.ts#L29) class.
+
+## Multi-Step Login
+When authenticating, with a multi-step process, it is useful to share information between steps.  The `authenticatorState` of [AuthContext](https://github.com/travetto/travetto/tree/main/module/auth/src/context.ts#L14) field is intended to be a location in which that information is persisted. Currently only [passport](http://passportjs.org) support is included, when dealing with multi-step logins. This information can also be injected into a web endpoint method, using the [AuthenticatorState](https://github.com/travetto/travetto/tree/main/module/auth/src/types/authenticator.ts#L9) type;

package/__index__.ts

@@ -0,0 +1,8 @@
+export * from './src/interceptors/context.ts';
+export * from './src/interceptors/login.ts';
+export * from './src/interceptors/logout.ts';
+export * from './src/interceptors/verify.ts';
+export * from './src/codec.ts';
+export * from './src/config.ts';
+export * from './src/decorator.ts';
+export * from './src/types.ts';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@travetto/auth-web",
+  "version": "6.0.0-rc.4",
+  "description": "Web authentication integration support for the Travetto framework",
+  "keywords": [
+    "authentication",
+    "web",
+    "travetto",
+    "decorators",
+    "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-web"
+  },
+  "dependencies": {
+    "@travetto/auth": "^6.0.0-rc.2",
+    "@travetto/config": "^6.0.0-rc.2",
+    "@travetto/web": "^6.0.0-rc.2",
+    "njwt": "^2.0.1"
+  },
+  "peerDependencies": {
+    "@travetto/test": "^6.0.0-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@travetto/test": {
+      "optional": true
+    }
+  },
+  "travetto": {
+    "displayName": "Web Auth"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/codec.ts

@@ -0,0 +1,92 @@
+import { createVerifier, create, Jwt, Verifier, SupportedAlgorithms } from 'njwt';
+
+import { AuthContext, AuthenticationError, AuthToken, Principal } from '@travetto/auth';
+import { Injectable, Inject } from '@travetto/di';
+import { WebResponse, WebRequest, WebAsyncContext, CookieJar } from '@travetto/web';
+import { AppError, castTo, TimeUtil } from '@travetto/runtime';
+
+import { CommonPrincipalCodecSymbol, PrincipalCodec } from './types.ts';
+import { WebAuthConfig } from './config.ts';
+
+/**
+ * JWT Principal codec
+ */
+@Injectable(CommonPrincipalCodecSymbol)
+export class JWTPrincipalCodec implements PrincipalCodec {
+
+  @Inject()
+  config: WebAuthConfig;
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Inject()
+  webAsyncContext: WebAsyncContext;
+
+  #verifier: Verifier;
+  #algorithm: SupportedAlgorithms = 'HS256';
+
+  postConstruct(): void {
+    this.#verifier = createVerifier()
+      .setSigningAlgorithm(this.#algorithm)
+      .withKeyResolver((kid, cb) => {
+        const rec = this.config.keyMap[kid];
+        return cb(rec ? null : new AuthenticationError('Invalid'), rec.key);
+      });
+  }
+
+  async verify(token: string): Promise<Principal> {
+    try {
+      const jwt: Jwt & { body: { core: Principal } } = await new Promise((res, rej) =>
+        this.#verifier.verify(token, (err, v) => err ? rej(err) : res(castTo(v)))
+      );
+      return jwt.body.core;
+    } catch (err) {
+      if (err instanceof Error && err.name.startsWith('Jwt')) {
+        throw new AuthenticationError(err.message, { category: 'permissions' });
+      }
+      throw err;
+    }
+  }
+
+  token(request: WebRequest): AuthToken | undefined {
+    const value = (this.config.mode === 'header') ?
+      request.headers.getWithPrefix(this.config.header, this.config.headerPrefix) :
+      this.webAsyncContext.getValue(CookieJar).get(this.config.cookie, { signed: false });
+    return value ? { type: 'jwt', value } : undefined;
+  }
+
+  async decode(request: WebRequest): Promise<Principal | undefined> {
+    const token = this.token(request);
+    return token ? await this.verify(token.value) : undefined;
+  }
+
+  async create(value: Principal, keyId: string = 'default'): Promise<string> {
+    const keyRec = this.config.keyMap[keyId];
+    if (!keyRec) {
+      throw new AppError('Requested unknown key for signing');
+    }
+    const jwt = create({}, '-')
+      .setExpiration(value.expiresAt!)
+      .setIssuedAt(TimeUtil.asSeconds(value.issuedAt!))
+      .setClaim('core', castTo({ ...value }))
+      .setIssuer(value.issuer!)
+      .setJti(value.sessionId!)
+      .setSubject(value.id)
+      .setHeader('kid', keyRec.id)
+      .setSigningKey(keyRec.key)
+      .setSigningAlgorithm(this.#algorithm);
+    return jwt.toString();
+  }
+
+  async encode(response: WebResponse, data: Principal | undefined): Promise<WebResponse> {
+    const token = data ? await this.create(data) : undefined;
+    const { header, headerPrefix, cookie } = this.config;
+    if (this.config.mode === 'header') {
+      response.headers.setWithPrefix(header, token, headerPrefix);
+    } else {
+      this.webAsyncContext.getValue(CookieJar).set({ name: cookie, value: token, signed: false, expires: data?.expiresAt });
+    }
+    return response;
+  }
+}

package/src/config.ts

@@ -0,0 +1,30 @@
+import { Config } from '@travetto/config';
+import { Runtime, AppError, BinaryUtil } from '@travetto/runtime';
+import { Ignore, Secret } from '@travetto/schema';
+
+type KeyRec = { key: string, id: string };
+
+@Config('web.auth')
+export class WebAuthConfig {
+  applies: boolean = false;
+  mode: 'cookie' | 'header' = 'cookie';
+  header: string = 'Authorization';
+  cookie: string = 'trv_auth';
+  headerPrefix: string = 'Token';
+
+  @Secret()
+  signingKey?: string | string[];
+  @Ignore()
+  keyMap: Record<string, KeyRec> & { default?: KeyRec } = {};
+
+  postConstruct(): void {
+    if (!this.signingKey && Runtime.production) {
+      throw new AppError('The default signing key is only valid for development use, please specify a config value at web.auth.signingKey');
+    }
+    this.signingKey ??= 'dummy';
+
+    const all = [this.signingKey].flat().map(key => ({ key, id: BinaryUtil.hash(key, 8) }));
+    this.keyMap = Object.fromEntries(all.map(k => [k.id, k]));
+    this.keyMap.default = all[0];
+  }
+}

package/src/decorator.ts

@@ -0,0 +1,50 @@
+import { ControllerRegistry, EndpointDecorator } from '@travetto/web';
+
+import { AuthVerifyInterceptor } from './interceptors/verify.ts';
+import { AuthLoginInterceptor } from './interceptors/login.ts';
+import { AuthLogoutInterceptor } from './interceptors/logout.ts';
+
+/**
+ * Authenticate an endpoint with a list of available identity sources
+ * @param source The symbol to target the specific authenticator
+ * @param sources Additional providers to support
+ * @augments `@travetto/auth:Authenticate`
+ */
+export function Login(source: symbol, ...sources: symbol[]): EndpointDecorator {
+  return ControllerRegistry.createInterceptorConfigDecorator(AuthLoginInterceptor, {
+    providers: [source, ...sources],
+    applies: true
+  });
+}
+
+/**
+ * Ensure the controller/endpoint is authenticated, give a set of permissions
+ * @param permissions Set of required/disallowed permissions
+ * @augments `@travetto/auth:Authenticated`
+ */
+export function Authenticated(permissions: string[] = []): EndpointDecorator {
+  return ControllerRegistry.createInterceptorConfigDecorator(AuthVerifyInterceptor, {
+    state: 'authenticated',
+    permissions,
+    applies: true
+  });
+}
+
+/**
+ * Require the controller/endpoint to be unauthenticated
+ * @augments `@travetto/auth:Unauthenticated`
+ */
+export function Unauthenticated(): EndpointDecorator {
+  return ControllerRegistry.createInterceptorConfigDecorator(AuthVerifyInterceptor, {
+    state: 'unauthenticated',
+    applies: true
+  });
+}
+
+/**
+ * Logs a user out of the auth state
+ * @augments `@travetto/auth:Logout`
+ */
+export function Logout(): EndpointDecorator {
+  return ControllerRegistry.createInterceptorConfigDecorator(AuthLogoutInterceptor, { applies: true });
+}

package/src/interceptors/context.ts

@@ -0,0 +1,78 @@
+import { toConcrete } from '@travetto/runtime';
+import { WebInterceptor, WebAsyncContext, WebInterceptorCategory, WebChainedContext, WebResponse } from '@travetto/web';
+import { Injectable, Inject, DependencyRegistry } from '@travetto/di';
+import { AuthContext, AuthService, AuthToken, Principal } from '@travetto/auth';
+
+import { CommonPrincipalCodecSymbol, PrincipalCodec } from '../types.ts';
+import { WebAuthConfig } from '../config.ts';
+
+const toDate = (v: string | Date | undefined): Date | undefined => (typeof v === 'string') ? new Date(v) : v;
+
+/**
+ * Auth Context interceptor
+ *
+ * - Supports the ability to encode context via response and decode via the request.
+ * - Connects the principal to the AuthContext
+ * - Manages expiry checks/extensions
+ */
+@Injectable()
+export class AuthContextInterceptor implements WebInterceptor {
+
+  category: WebInterceptorCategory = 'application';
+
+  @Inject({ optional: true })
+  codec: PrincipalCodec;
+
+  @Inject()
+  config: WebAuthConfig;
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Inject()
+  authService: AuthService;
+
+  @Inject()
+  webAsyncContext: WebAsyncContext;
+
+  async postConstruct(): Promise<void> {
+    this.codec ??= await DependencyRegistry.getInstance(toConcrete<PrincipalCodec>(), CommonPrincipalCodecSymbol);
+    this.webAsyncContext.registerSource(toConcrete<Principal>(), () => this.authContext.principal);
+    this.webAsyncContext.registerSource(toConcrete<AuthToken>(), () => this.authContext.authToken);
+  }
+
+  async filter(ctx: WebChainedContext): Promise<WebResponse> {
+    // Skip if already authenticated
+    if (this.authContext.principal) {
+      return ctx.next();
+    }
+
+    try {
+      let lastExpiresAt: Date | undefined;
+      const decoded = await this.codec.decode(ctx.request);
+
+      if (decoded) {
+        lastExpiresAt = decoded.expiresAt = toDate(decoded.expiresAt);
+        decoded.issuedAt = toDate(decoded.issuedAt);
+      }
+
+      const checked = this.authService.enforceExpiry(decoded);
+      this.authContext.principal = checked;
+      this.authContext.authToken = await this.codec.token?.(ctx.request);
+
+      let value = await ctx.next();
+
+      const result = this.authContext.principal;
+      this.authService.manageExpiry(result);
+
+      if ((!!decoded !== !!checked) || result !== checked || lastExpiresAt !== result?.expiresAt) { // If it changed
+        value = await this.codec.encode(value, result);
+      }
+
+      return value;
+    } finally {
+      this.authContext.clear();
+    }
+  }
+
+}

package/src/interceptors/login.ts

@@ -0,0 +1,48 @@
+import { WebInterceptor, WebInterceptorCategory, WebChainedContext, WebResponse, WebInterceptorContext } from '@travetto/web';
+import { Injectable, Inject } from '@travetto/di';
+import { Config } from '@travetto/config';
+import { Ignore } from '@travetto/schema';
+import { AuthService } from '@travetto/auth';
+
+import { AuthContextInterceptor } from './context.ts';
+
+@Config('web.auth.login')
+export class WebAuthLoginConfig {
+  /**
+   * Execute login on endpoint
+   */
+  applies = false;
+  /**
+   * The auth providers to iterate through when attempting to authenticate
+   */
+  @Ignore()
+  providers: symbol[];
+}
+
+/**
+ * Login interceptor
+ *
+ * - Supports the ability to encode context via request/response.
+ * - Connects the principal to the request
+ */
+@Injectable()
+export class AuthLoginInterceptor implements WebInterceptor<WebAuthLoginConfig> {
+
+  category: WebInterceptorCategory = 'application';
+  dependsOn = [AuthContextInterceptor];
+
+  @Inject()
+  config: WebAuthLoginConfig;
+
+  @Inject()
+  service: AuthService;
+
+  applies({ config }: WebInterceptorContext<WebAuthLoginConfig>): boolean {
+    return config.applies;
+  }
+
+  async filter(ctx: WebChainedContext<WebAuthLoginConfig>): Promise<WebResponse> {
+    await this.service.authenticate(ctx.request.body, ctx, ctx.config.providers ?? []);
+    return ctx.next();
+  }
+}

package/src/interceptors/logout.ts

@@ -0,0 +1,47 @@
+import { WebInterceptor, WebInterceptorCategory, WebChainedContext, WebResponse, WebInterceptorContext } from '@travetto/web';
+import { Injectable, Inject } from '@travetto/di';
+import { Config } from '@travetto/config';
+import { AuthContext, AuthenticationError } from '@travetto/auth';
+
+import { AuthContextInterceptor } from './context.ts';
+
+@Config('web.auth.logout')
+export class WebAuthLogoutConfig {
+  /**
+   * Execute logout on endpoint
+   */
+  applies = false;
+}
+
+/**
+ * Logout interceptor
+ *
+ * Throws an error if the user is not logged in at time of logout
+ */
+@Injectable()
+export class AuthLogoutInterceptor implements WebInterceptor<WebAuthLogoutConfig> {
+
+  category: WebInterceptorCategory = 'application';
+  dependsOn = [AuthContextInterceptor];
+
+  @Inject()
+  config: WebAuthLogoutConfig;
+
+  @Inject()
+  authContext: AuthContext;
+
+  applies({ config }: WebInterceptorContext<WebAuthLogoutConfig>): boolean {
+    return config.applies;
+  }
+
+  async filter({ next }: WebChainedContext): Promise<WebResponse> {
+    try {
+      if (!this.authContext.principal) {
+        throw new AuthenticationError('Already logged out');
+      }
+      return await next();
+    } finally {
+      await this.authContext.clear();
+    }
+  }
+}

package/src/interceptors/verify.ts

@@ -0,0 +1,88 @@
+import { AppError, Util } from '@travetto/runtime';
+import { WebInterceptor, WebInterceptorCategory, WebChainedContext, WebResponse, WebInterceptorContext } from '@travetto/web';
+import { Injectable, Inject } from '@travetto/di';
+import { Config } from '@travetto/config';
+import { Ignore } from '@travetto/schema';
+import { AuthenticationError, AuthContext } from '@travetto/auth';
+
+import { AuthContextInterceptor } from './context.ts';
+
+function matchPermissionSet(rule: string[], perms: Set<string>): boolean {
+  for (const el of rule) {
+    if (!perms.has(el)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+@Config('web.auth.verify')
+export class WebAuthVerifyConfig {
+  /**
+   * Verify user is in a specific auth state
+   */
+  applies = false;
+  /**
+   * Default state to care about
+   */
+  state?: 'authenticated' | 'unauthenticated';
+  /**
+   * What are the permissions for verification, allowed or disallowed
+   */
+  permissions: string[] = [];
+
+  @Ignore()
+  matcher: (key: Set<string>) => boolean;
+}
+
+/**
+ * Authenticate interceptor
+ *
+ * Enforces if the user should be authenticated
+ */
+@Injectable()
+export class AuthVerifyInterceptor implements WebInterceptor<WebAuthVerifyConfig> {
+
+  category: WebInterceptorCategory = 'application';
+  dependsOn = [AuthContextInterceptor];
+
+  @Inject()
+  config: WebAuthVerifyConfig;
+
+  @Inject()
+  authContext: AuthContext;
+
+  finalizeConfig({ config }: WebInterceptorContext<WebAuthVerifyConfig>): WebAuthVerifyConfig {
+    config.matcher = Util.allowDeny<string[], [Set<string>]>(config.permissions ?? [],
+      x => x.split('|'),
+      matchPermissionSet,
+    );
+    return config;
+  }
+
+  applies({ config }: WebInterceptorContext<WebAuthVerifyConfig>): boolean {
+    return config.applies;
+  }
+
+  async filter({ config, next }: WebChainedContext<WebAuthVerifyConfig>): Promise<WebResponse> {
+    const principal = this.authContext.principal;
+
+    switch (config.state) {
+      case 'authenticated': {
+        if (!principal) {
+          throw new AuthenticationError('User is unauthenticated');
+        } else if (!config.matcher(new Set(principal.permissions))) {
+          throw new AppError('Access denied', { category: 'permissions' });
+        }
+        break;
+      }
+      case 'unauthenticated': {
+        if (principal) {
+          throw new AuthenticationError('User is authenticated');
+        }
+        break;
+      }
+    }
+    return next();
+  }
+}

package/src/internal/principal-schema.ts

@@ -0,0 +1,19 @@
+import { Schema, SchemaRegistry } from '@travetto/schema';
+import { toConcrete, AnyMap, asFull } from '@travetto/runtime';
+import { Principal } from '@travetto/auth';
+
+@Schema()
+export class PrincipalSchema implements Principal {
+  id: string;
+  details: AnyMap;
+  expiresAt?: Date | undefined;
+  issuedAt?: Date | undefined;
+  issuer?: string | undefined;
+  sessionId?: string | undefined;
+  permissions?: string[] | undefined;
+}
+
+SchemaRegistry.mergeConfigs(
+  asFull(SchemaRegistry.getOrCreatePending(toConcrete<Principal>())),
+  SchemaRegistry.getOrCreatePending(PrincipalSchema)
+);

package/src/types.ts

@@ -0,0 +1,23 @@
+import { AuthToken, Principal } from '@travetto/auth';
+import { WebRequest, WebResponse } from '@travetto/web';
+
+export const CommonPrincipalCodecSymbol = Symbol.for('@travetto/auth-web:common-codec');
+
+/**
+ * Web codec for reading/writing principal
+ * @concrete
+ */
+export interface PrincipalCodec {
+  /**
+   * Extract token for re-use elsewhere
+   */
+  token?(request: WebRequest): Promise<AuthToken | undefined> | AuthToken | undefined;
+  /**
+   * Encode data
+   */
+  encode(payload: WebResponse, data: Principal | undefined): Promise<WebResponse> | WebResponse;
+  /**
+   * Decode data
+   */
+  decode(request: WebRequest): Promise<Principal | undefined> | Principal | undefined;
+}

package/support/test/server.ts

@@ -0,0 +1,287 @@
+import timers from 'node:timers/promises';
+import assert from 'node:assert';
+
+import { Controller, Get, WebHeaders, WebResponse, Post } from '@travetto/web';
+import { Suite, Test } from '@travetto/test';
+import { DependencyRegistry, Inject, InjectableFactory } from '@travetto/di';
+import { AuthenticationError, Authenticator, AuthContext, AuthConfig } from '@travetto/auth';
+
+import { InjectableSuite } from '@travetto/di/support/test/suite.ts';
+import { BaseWebSuite } from '@travetto/web/support/test/suite/base.ts';
+
+import { Login, Authenticated, Logout } from '../../src/decorator.ts';
+import { WebAuthConfig } from '../../src/config.ts';
+import { CommonPrincipalCodecSymbol } from '../../src/types.ts';
+import { JWTPrincipalCodec } from '../../src/codec.ts';
+
+const TestAuthSymbol = Symbol.for('TEST_AUTH');
+
+class Config {
+  @InjectableFactory(TestAuthSymbol)
+  static getAuthenticator(cfg: AuthConfig): Authenticator {
+    cfg.rollingRenew = true;
+    cfg.maxAgeMs = 2000;
+
+    return {
+      async authenticate(body: { username?: string, password?: string }) {
+        if (body.username === 'super-user' && body.password === 'password') {
+          return {
+            id: '5',
+            details: { name: 'Billy' },
+            permissions: ['perm1', 'perm2'],
+            issuer: 'custom',
+          };
+        }
+        throw new AuthenticationError('User unknown');
+      }
+    };
+  }
+}
+
+@Controller('/test/auth')
+class TestAuthController {
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Post('/login')
+  @Login(TestAuthSymbol)
+  async simpleLogin() {
+    console.log('hello');
+  }
+
+  @Get('/self')
+  @Authenticated()
+  async getSelf() {
+    return this.authContext.principal;
+  }
+
+  @Get('/token')
+  @Authenticated()
+  async getToken() {
+    return this.authContext.authToken?.value;
+  }
+
+
+  @Get('/logout')
+  @Logout()
+  async logout() {
+    return WebResponse.redirect('/auth/self');
+  }
+}
+
+@Controller('/test/auth-all')
+@Authenticated()
+class TestAuthAllController {
+
+  @Inject()
+  authContext: AuthContext;
+
+  @Get('/self')
+  async getSelf() {
+    return this.authContext.principal;
+  }
+}
+
+@Suite()
+@InjectableSuite()
+export abstract class AuthWebServerSuite extends BaseWebSuite {
+
+  @Inject()
+  config: WebAuthConfig;
+
+  getCookie(headers: WebHeaders): string | undefined {
+    return headers.getSetCookie()[0];
+  }
+
+  getCookieValue(headers: WebHeaders): string | undefined {
+    return this.getCookie(headers)?.split(';')[0];
+  }
+
+  getCookieExpires(headers: WebHeaders): Date | undefined {
+    const v = this.getCookie(headers)?.match('expires=([^;]+)(;|$)')?.[1];
+    return v ? new Date(v) : undefined;
+  }
+
+  @Test()
+  async testBadAuth() {
+    const { context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'Todd',
+        password: 'Rod'
+      }
+    }, false);
+    assert(statusCode === 401);
+  }
+
+  @Test()
+  async testGoodAuth() {
+    this.config.mode = 'cookie';
+
+    const { headers, context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'super-user',
+        password: 'password'
+      }
+    }, false);
+    assert(headers.getSetCookie().length);
+    assert(statusCode === 201);
+  }
+
+  @Test()
+  async testBlockedAuthenticated() {
+    this.config.mode = 'header';
+
+    const { context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth/self' }
+    }, false);
+    assert(statusCode === 401);
+  }
+
+  @Test()
+  async testGoodAuthenticatedCookie() {
+    this.config.mode = 'cookie';
+
+    const { headers, context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'super-user',
+        password: 'password'
+      }
+    }, false);
+    assert(statusCode === 201);
+    const cookie = this.getCookieValue(headers);
+    assert(cookie);
+
+    const { context: { httpStatusCode: lastStatus } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth/self' },
+      headers: { cookie }
+    }, false);
+    assert(lastStatus === 200);
+  }
+
+  @Test()
+  async testGoodAuthenticatedHeader() {
+    this.config.mode = 'header';
+
+    const { headers, context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'super-user',
+        password: 'password'
+      }
+    }, false);
+    assert(statusCode === 201);
+
+    const { context: { httpStatusCode: lastStatus } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth/self' },
+      headers: {
+        Authorization: headers.get('Authorization')!
+      }
+    }, false);
+    assert(lastStatus === 200);
+  }
+
+  @Test()
+  async testAllAuthenticated() {
+    this.config.mode = 'header';
+
+    const { context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth-all/self' }
+    }, false);
+    assert(statusCode === 401);
+
+    const { headers, context: { httpStatusCode: authStatus } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'super-user',
+        password: 'password'
+      }
+    }, false);
+    assert(authStatus === 201);
+
+
+    const { context: { httpStatusCode: lastStatus } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth-all/self' },
+      headers: {
+        Authorization: headers.get('Authorization')!
+      }
+    }, false);
+    assert(lastStatus === 200);
+  }
+
+
+  @Test()
+  async testTokenRetrieval() {
+    this.config.mode = 'cookie';
+
+    const { headers, context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'super-user',
+        password: 'password'
+      }
+    }, false);
+    assert(statusCode === 201);
+    const cookie = this.getCookieValue(headers);
+    assert(cookie);
+
+    const { body, context: { httpStatusCode: lastStatus } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth/token' },
+      headers: { cookie }
+    }, false);
+    assert(lastStatus === 200);
+    assert(typeof body === 'string');
+
+    const codec = await DependencyRegistry.getInstance(JWTPrincipalCodec, CommonPrincipalCodecSymbol);
+    await assert.doesNotReject(() => codec.verify(body));
+  }
+
+  @Test()
+  async testCookieRollingRenewAuthenticated() {
+    this.config.mode = 'cookie';
+
+    const { headers, context: { httpStatusCode: statusCode } } = await this.request({
+      context: { httpMethod: 'POST', path: '/test/auth/login' },
+      body: {
+        username: 'super-user',
+        password: 'password'
+      }
+    }, false);
+    assert(statusCode === 201);
+
+    const start = Date.now();
+    const cookie = this.getCookieValue(headers);
+    assert(cookie);
+
+    const expires = this.getCookieExpires(headers);
+    assert(expires);
+
+    const { headers: selfHeaders, context: { httpStatusCode: lastStatus } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth/self' },
+      headers: { cookie }
+    }, false);
+    assert(this.getCookie(selfHeaders) === undefined);
+    assert(lastStatus === 200);
+
+    const used = (Date.now() - start);
+    assert(used < 1000);
+    await timers.setTimeout((2000 - used) / 2);
+
+    const { headers: selfHeadersRenew, context: { httpStatusCode: lastStatus2 } } = await this.request({
+      context: { httpMethod: 'GET', path: '/test/auth/self' },
+      headers: { cookie }
+    }, false);
+    assert(lastStatus2 === 200);
+    assert(this.getCookie(selfHeadersRenew));
+
+    const expiresRenew = this.getCookieExpires(selfHeadersRenew);
+    assert(expiresRenew);
+
+    const delta = expiresRenew.getTime() - expires.getTime();
+    assert(delta < 1800);
+    assert(delta > 500);
+  }
+}