@travetto/auth-web-passport 6.0.0-rc.4

package/README.md

@@ -0,0 +1,130 @@
+<!-- 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-passport/DOC.tsx and execute "npx trv doc" to rebuild -->
+# Web Auth Passport
+
+## Web authentication integration support for the Travetto framework
+
+**Install: @travetto/auth-web-passport**
+```bash
+npm install @travetto/auth-web-passport
+
+# or
+
+yarn add @travetto/auth-web-passport
+```
+
+This is a primary integration for the [Web Auth](https://github.com/travetto/travetto/tree/main/module/auth-web#readme "Web authentication integration support for the Travetto framework") module. 
+
+Within the node ecosystem, the most prevalent auth framework is [passport](http://passportjs.org).  With countless integrations, the desire to leverage as much of it as possible, is extremely high. To that end, this module provides support for [passport](http://passportjs.org) baked in. Registering and configuring a [passport](http://passportjs.org) strategy is fairly straightforward.
+
+**NOTE:** Given that [passport](http://passportjs.org) is oriented around [express](https://expressjs.com), this module relies on [Web Connect Support](https://github.com/travetto/travetto/tree/main/module/web-connect#readme "Web integration for Connect-Like Resources") as an adapter for the request/response handoff.  There are some limitations listed in the module, and those would translate to any [passport](http://passportjs.org) strategies that are being used.
+
+**Code: Sample Facebook/passport config**
+```typescript
+import { Strategy as FacebookStrategy } from 'passport-facebook';
+
+import { InjectableFactory } from '@travetto/di';
+import { Authenticator, Authorizer, Principal } from '@travetto/auth';
+import { PassportAuthenticator } from '@travetto/auth-web-passport';
+
+export class FbUser {
+  username: string;
+  permissions: string[];
+}
+
+export const FbAuthSymbol = Symbol.for('auth_facebook');
+
+export class AppConfig {
+  @InjectableFactory(FbAuthSymbol)
+  static facebookPassport(): Authenticator {
+    return new PassportAuthenticator('facebook',
+      new FacebookStrategy(
+        {
+          clientID: '<appId>',
+          clientSecret: '<appSecret>',
+          callbackURL: 'http://localhost:3000/auth/facebook/callback',
+          profileFields: ['id', 'username', 'displayName', 'photos', 'email'],
+        },
+        (accessToken, refreshToken, profile, cb) =>
+          cb(undefined, profile)
+      ),
+      (user: FbUser) => ({
+        id: user.username,
+        permissions: user.permissions,
+        details: user
+      })
+    );
+  }
+
+  @InjectableFactory()
+  static principalSource(): Authorizer {
+    return new class implements Authorizer {
+      async authorize(p: Principal) {
+        return p;
+      }
+    }();
+  }
+}
+```
+
+As you can see, [PassportAuthenticator](https://github.com/travetto/travetto/tree/main/module/auth-web-passport/src/authenticator.ts#L15) will take care of the majority of the work, and all that is required is:
+   *  Provide the name of the strategy (should be unique)
+   *  Provide the strategy instance.
+   *  The conversion functions which defines the mapping between external and local identities.
+
+**Note**: You will need to provide the callback for the strategy to ensure you pass the external principal back into the framework
+After that, the provider is no different than any other, and can be used accordingly.  Additionally, because [passport](http://passportjs.org) runs first, in it's entirety, you can use the provider as you normally would any [passport](http://passportjs.org) middleware.
+
+**Code: Sample endpoints using Facebook/passport provider**
+```typescript
+import { Controller, Get, Post, WebRequest, ContextParam, WebResponse } from '@travetto/web';
+import { Login, Authenticated, Logout } from '@travetto/auth-web';
+import { Principal } from '@travetto/auth';
+
+import { FbAuthSymbol } from './conf.ts';
+
+@Controller('/auth')
+export class SampleAuth {
+
+  @ContextParam()
+  request: WebRequest;
+
+  @ContextParam()
+  user: Principal;
+
+  @Get('/name')
+  async getName() {
+    return { name: 'bob' };
+  }
+
+  @Get('/facebook')
+  @Login(FbAuthSymbol)
+  async fbLogin() {
+
+  }
+
+  @Get('/self')
+  @Authenticated()
+  async getSelf() {
+    return this.user;
+  }
+
+  @Get('/facebook/callback')
+  @Login(FbAuthSymbol)
+  async fbLoginComplete() {
+    return WebResponse.redirect('/auth/self');
+  }
+
+  @Post('/logout')
+  @Logout()
+  async logout() { }
+
+  /**
+   * Simple Echo
+   */
+  @Post('/')
+  async echo(): Promise<unknown> {
+    return this.request.body;
+  }
+}
+```

package/__index__.ts

@@ -0,0 +1,2 @@
+export * from './src/authenticator.ts';
+export * from './src/util.ts';

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@travetto/auth-web-passport",
+  "version": "6.0.0-rc.4",
+  "description": "Web authentication integration support for the Travetto framework",
+  "keywords": [
+    "authentication",
+    "web",
+    "passport",
+    "travetto",
+    "decorators",
+    "typescript"
+  ],
+  "homepage": "https://travetto.io",
+  "license": "MIT",
+  "author": {
+    "email": "travetto.framework@gmail.com",
+    "name": "Travetto Framework"
+  },
+  "files": [
+    "__index__.ts",
+    "src"
+  ],
+  "main": "__index__.ts",
+  "repository": {
+    "url": "git+https://github.com/travetto/travetto.git",
+    "directory": "module/auth-web-passport"
+  },
+  "dependencies": {
+    "@travetto/auth": "^6.0.0-rc.2",
+    "@travetto/auth-web": "^6.0.0-rc.4",
+    "@travetto/config": "^6.0.0-rc.2",
+    "@travetto/web": "^6.0.0-rc.2",
+    "@travetto/web-connect": "^6.0.0-rc.2",
+    "@types/passport": "^1.0.17",
+    "passport": "^0.7.0"
+  },
+  "devDependencies": {
+    "@types/passport-facebook": "^3.0.3",
+    "passport-facebook": "^3.0.0"
+  },
+  "travetto": {
+    "displayName": "Web Auth Passport"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/authenticator.ts

@@ -0,0 +1,75 @@
+import passport from 'passport';
+
+import { Authenticator, AuthenticatorState, Principal } from '@travetto/auth';
+import { WebFilterContext } from '@travetto/web';
+import { WebConnectUtil } from '@travetto/web-connect';
+
+import { PassportUtil } from './util.ts';
+
+type SimplePrincipal = Omit<Principal, 'issuedAt' | 'expiresAt'>;
+type PassportUser = Express.User & { _raw?: unknown, _json?: unknown, source?: unknown };
+
+/**
+ * Authenticator via passport
+ */
+export class PassportAuthenticator<V extends PassportUser = PassportUser> implements Authenticator<object, WebFilterContext> {
+
+  #strategyName: string;
+  #strategy: passport.Strategy;
+  #toPrincipal: (user: V, issuer?: string) => SimplePrincipal;
+  #passportOptions: (ctx: WebFilterContext) => passport.AuthenticateOptions;
+  session = false;
+
+  /**
+   * Creating a new PassportAuthenticator
+   *
+   * @param strategyName Name of passport strategy
+   * @param strategy  A passport strategy
+   * @param toPrincipal  How to convert a user to an identity
+   * @param opts Extra passport options
+   */
+  constructor(
+    strategyName: string,
+    strategy: passport.Strategy,
+    toPrincipal: (user: V) => SimplePrincipal,
+    opts: passport.AuthenticateOptions | ((ctx: WebFilterContext) => passport.AuthenticateOptions) = {},
+  ) {
+    this.#strategyName = strategyName;
+    this.#strategy = strategy;
+    this.#toPrincipal = toPrincipal;
+    this.#passportOptions = typeof opts === 'function' ? opts : ((): Partial<passport.AuthenticateOptions> => opts);
+    passport.use(this.#strategyName, this.#strategy);
+  }
+
+  /**
+   * Extract the passport auth context
+   */
+  getState(context?: WebFilterContext | undefined): AuthenticatorState | undefined {
+    return context ? PassportUtil.readState<AuthenticatorState>(context.request) : undefined;
+  }
+
+  /**
+   * Authenticate a request given passport config
+   * @param ctx The travetto filter context
+   */
+  async authenticate(input: object, ctx: WebFilterContext): Promise<Principal | undefined> {
+    const requestOptions = this.#passportOptions(ctx);
+    const options = {
+      session: this.session,
+      failWithError: true,
+      ...requestOptions,
+      state: PassportUtil.enhanceState(ctx, requestOptions.state)
+    };
+
+    const user = await WebConnectUtil.invoke<V>(ctx, (req, res, next) =>
+      passport.authenticate(this.#strategyName, options, next)(req, res)
+    );
+
+    if (user) {
+      delete user._raw;
+      delete user._json;
+      delete user.source;
+      return this.#toPrincipal(user, this.#strategyName);
+    }
+  }
+}

package/src/util.ts

@@ -0,0 +1,63 @@
+import { WebFilterContext, WebRequest } from '@travetto/web';
+import { castTo, Util } from '@travetto/runtime';
+
+/**
+ * Passport utilities
+ */
+export class PassportUtil {
+
+  /**
+   * Read passport state string as bas64 encoded JSON value
+   * @param src The input src for a state read (string, or a request obj)
+   */
+  static readState<T = Record<string, unknown>>(src?: string | WebRequest): T | undefined {
+    const state = (typeof src === 'string' ? src :
+      (typeof src?.context.httpQuery?.state === 'string' ?
+        src?.context.httpQuery?.state : ''));
+    if (state) {
+      try {
+        return Util.decodeSafeJSON(state);
+      } catch { }
+    }
+  }
+
+  /**
+   * Write state value from plain object
+   * @param state
+   * @returns base64 encoded state value, if state is provided
+   */
+  static writeState(state?: Record<string, unknown>): string | undefined {
+    if (state) {
+      return Util.encodeSafeJSON(state);
+    }
+  }
+
+  /**
+   * Add to a given state value
+   * @param state The new state data to inject
+   * @param currentState The optional, current state/request
+   * @param key Optional location to nest new state data
+   * @returns
+   */
+  static addToState(state: string | Record<string, unknown>, current?: string | WebRequest, key?: string): string {
+    const pre = this.readState(current) ?? {};
+    const toAdd = typeof state === 'string' ? JSON.parse(state) : state;
+    const base: Record<string, unknown> = key ? castTo(pre[key] ??= {}) : pre;
+    for (const k of Object.keys(toAdd)) {
+      if (k === '__proto__' || k === 'constructor' || k === 'prototype') {
+        continue;
+      }
+      base[k] = toAdd[k];
+    }
+    return this.writeState(pre)!;
+  }
+
+  /**
+   * Enhance passport state with additional information information
+   * @param ctx The travetto filter context
+   * @param currentState The current state, if any
+   */
+  static enhanceState({ request }: WebFilterContext, currentState?: string): string {
+    return this.addToState({ referrer: request.headers.get('Referer') }, currentState);
+  }
+}