@crossauth/fastify 0.0.2

package/dist/fastifyresserver.d.ts

@@ -0,0 +1,93 @@
+import { FastifyRequest, FastifyInstance } from 'fastify';
+import { Server, IncomingMessage, ServerResponse } from 'http';
+import { User } from '@crossauth/common';
+import { OAuthResourceServer, UserStorage, OAuthResourceServerOptions, OAuthTokenConsumer } from '@crossauth/backend';
+
+/**
+ * Options for {@link FastifyOAuthResourceServer}
+ */
+export interface FastifyOAuthResourceServerOptions extends OAuthResourceServerOptions {
+    /** If you set this and your access tokens have a user (`sub` claim),
+     * the `user` field in the request will be populated with a valid
+     * access token,
+     */
+    userStorage?: UserStorage;
+    /**
+     * If you enabled `protectedEndpoints` in
+     * {@link FastifyOAuthResourceServer.constructor}
+     * and the access token is invalid, a 401 reply will be sent before
+     * your endpoint is hit.  This will be the body,  Default {}.
+     */
+    errorBody?: {
+        [key: string]: any;
+    };
+    /**
+     * If you define this, matching resource server endpoints will return
+     * a status code of 401 Access Denied if the key is invalid or the
+     * given scopes are not present.
+     */
+    protectedEndpoints?: {
+        [key: string]: {
+            scope?: string[];
+            acceptSessionAuthorization?: boolean;
+        };
+    };
+}
+/**
+ * OAuth resource server.
+ *
+ * You can subclass this, simply instantiate it, or create it through
+ * {@link FastifyServer}.
+ *
+ * There are two way of using this class.  If you don't set
+ * `protectedEndpoints` in
+ * {@link FastifyOAuthResourceServer.constructor}, then in your
+ * protected endpoints, call {@link FastifyOAuthResourceServer.authorized}
+ * to check if the access token is valid and get any user credentials.
+ *
+ * If you do set `protectedEndpoints` in
+ * {@link FastifyOAuthResourceServer.constructor}
+ * then a `preHandler` iscreated.
+ * The preHandler
+ * hook will set the `accessTokenPayload`, `user` and `scope` fields
+ * on the Fastify request object based on the content
+ * of the access token in the `Authorization` header if it is valid.
+ * If it is not valid it will set the `authError` and `authErrorDescription`.
+ * If the access token is invalid, or there is an error, a 401 or 500
+ * response is sent before executing your endpoint code.  As per
+ * OAuth requirements, if the response is a 401, the WWW-Authenticate header
+ * is set.  If a scope is required this is included in that header.
+ */
+export declare class FastifyOAuthResourceServer extends OAuthResourceServer {
+    private userStorage?;
+    private protectedEndpoints;
+    private errorBody;
+    /**
+     * Constructor
+     * @param app the Fastify app
+     * @param tokenConsumers the token consumers, one per issuer
+     * @param options See {@link FastifyOAuthResourceServerOptions}
+     */
+    constructor(app: FastifyInstance<Server, IncomingMessage, ServerResponse>, tokenConsumers: OAuthTokenConsumer[], options?: FastifyOAuthResourceServerOptions);
+    private authenticateHeader;
+    /**
+     * If there is no bearer token, returns `undefinerd`.  If there is a
+     * bearer token and it is a valid access token, returns the token
+     * payload.  If there was an error, returns it in OAuth form.
+     * @param request the Fastify request
+     * @returns an objuect with the following fiekds
+     *   - `authorized` : `true` or `false`
+     *   - `tokenPayload` : the token payload if the token is valid
+     *   - `error` : if the token is not valid
+     *   - `error_description` : if the token is not valid
+     */
+    authorized(request: FastifyRequest): Promise<{
+        authorized: boolean;
+        tokenPayload?: {
+            [key: string]: any;
+        };
+        user?: User;
+        error?: string;
+        error_description?: string;
+    } | undefined>;
+}

package/dist/fastifyserver.d.ts

@@ -0,0 +1,293 @@
+import { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import { Server, IncomingMessage, ServerResponse } from 'http';
+import { CrossauthError, User } from '@crossauth/common';
+import { KeyStorage, OAuthClientStorage } from '@crossauth/backend';
+import { FastifySessionServer, FastifySessionServerOptions, CsrfBodyType } from './fastifysession';
+import { FastifySessionAdapter } from './fastifysessionadapter';
+import { FastifyApiKeyServerOptions } from './fastifyapikey';
+import { FastifyAuthorizationServer, FastifyAuthorizationServerOptions } from './fastifyoauthserver';
+import { FastifyOAuthClient, FastifyOAuthClientOptions } from './fastifyoauthclient';
+import { FastifyOAuthResourceServer, FastifyOAuthResourceServerOptions } from './fastifyresserver';
+
+export declare const ERROR_400 = "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>400 Bad Request</title>\n</head><body>\n<h1>400 Bad Request</h1>\n<p>The server was unable to handle your request.</p>\n</body></html>\n";
+export declare const ERROR_401 = "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>401 Unauthorized</title>\n</head><body>\n<h1>401 Unauthorized</h1>\n<p>You are not authorized to access this URL.</p>\n</body></html>\n";
+export declare const ERROR_403 = "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>403 Forbidden</title>\n</head><body>\n<h1>403 Forbidden</h1>\n<p>You are not authorized to make this request.</p>\n</body></html>\n";
+export declare const ERROR_500 = "<!DOCTYPE HTML PUBLIC \"-//IETF//DTD HTML 2.0//EN\">\n<html><head>\n<title>500 Server Error</title>\n</head><body>\n<h1>500 Error</h1>\n<p>Sorry, an unknown error has occured</p>\n</body></html>\n";
+export declare const DEFAULT_ERROR: {
+    400: string;
+    401: string;
+    500: string;
+};
+/**
+ * Options for {@link FastifyServer }.
+ *
+ * See {@link FastifyServer } constructor for description of parameters
+ */
+export interface FastifyServerOptions extends FastifySessionServerOptions, FastifyApiKeyServerOptions, FastifyAuthorizationServerOptions, FastifyOAuthClientOptions, FastifyOAuthResourceServerOptions {
+    /** You can pass your own fastify instance or omit this, in which case Crossauth will create one */
+    app?: FastifyInstance<Server, IncomingMessage, ServerResponse>;
+    /** If this is passed, it is registered as a Nunjucks view folder with autoscape on */
+    views?: string;
+    isAdminFn?: (user: User) => boolean;
+}
+/**
+ * Type for the function that is called to pass an error back to the user
+ *
+ * The function is passed this instance, the request that generated the
+ * error, the response object for sending the respons to and the
+ * exception that was raised.
+ */
+export type FastifyErrorFn = (server: FastifyServer, request: FastifyRequest, reply: FastifyReply, ce: CrossauthError) => Promise<FastifyReply>;
+/**
+ * This class provides a complete (but without HTML files) auth backend server
+ * for Fastify applications
+ *
+ * If you do not pass an Fastify app to this class, it will create one.
+ * By default, pages are rendered
+ * with Nunjucks.  If you prefer another renderer that is compatible with
+ * Fastify, create your
+ * own Fastify app and configure the renderer using @fastify/view.
+ *
+ * By default, all views are expected to be in a directory called `views`
+ * relative to the directory the
+ * server is started in.  This can be overwritten by setting the `views` option.
+ *
+ * Note that `views`, and the Nunjucks pages are not used by the API
+ * endpoints (those starting in /api).  These just return JSON.
+ *
+ * **Component Servers**
+ *
+ * This class contains a number of servers which don't all have to be
+ * created, depending on what authentication you want to support.  If
+ * instantiated, they can work together.
+ *
+ * - `sessionServer`   Session cookie management server.  Uses sesion ID
+ *                     and CSRF cookies.  See {@link FastifySessionServer}.
+ * - `sessionAdapter`  If you want an OAuth client but not want to use
+ *                     Fastify's session server, you can provide your own
+ *                     with this.  Won't work with auth server.
+ * - `oAuthAuthServer` OAuth authorization server.  See
+ *                     {@link FastifyAuthorizationServer}
+ * - `oAuthClient`     OAuth client.  See {@link FastifyOAuthClient}.
+ * - `oAuthClients`    An array of OAuthClients if you want more than one.
+ *                     Use either this or `oAuthClient` but not both.
+ *                     See {@link FastifyOAuthClient}.
+ * - `oAuthResServer`  OAuth resource server.  See
+ *                     {@link FastifyOAuthResourceServer}.
+ *
+ * There is also an API key server which is not available as a variable as
+ * it has no functions other than the hook it registers.
+ * See {@link FastifyApiKeyServer}.
+ *
+ * For a list of user-level URLs that can be enabled, and their input and output
+ * requirements, see {@link FastifySessionServer}.  FOr a list of
+ * admin endpoints that can be enabled, see {@link FastifyAdminEndpoints}.
+ *
+ * **Authenticators**
+ *
+ * One and two factor authentication is supported.  Authentication is provided
+ * by classes implementing {@link Authenticator}.  They are passed as an
+ * object to this class, keyed on the name that appears in the user record
+ * as `factor1` or `factor2`.
+ *
+ * For example, if you have passwords in your user database, you can use
+ * {@link @crossauth/backend!LocalPasswordAuthenticator}.  If this method of authentication
+ * is called `password` in the `factor1` field of the user record,
+ * pass it in the `authenticators` parameter in the constructor with a key
+ * of `password`.
+ *
+ */
+export declare class FastifyServer {
+    private views;
+    private static isAdminFn;
+    /** The Fastify app, which was either passed in the constructor or
+     *  created if none was passed in.
+     */
+    readonly app: FastifyInstance<Server, IncomingMessage, ServerResponse>;
+    /** See class comment */
+    readonly sessionServer?: FastifySessionServer;
+    /**
+     * See class comment
+     *
+     * Will be the same as `sessionServer` if that is passed instawd
+     */
+    readonly sessionAdapter?: FastifySessionAdapter;
+    /** See class comment */
+    readonly oAuthAuthServer?: FastifyAuthorizationServer;
+    /** See class comment */
+    readonly oAuthClient?: FastifyOAuthClient;
+    /** See class comment */
+    readonly oAuthClients?: FastifyOAuthClient[];
+    /** See class comment */
+    readonly oAuthResServer?: FastifyOAuthResourceServer;
+    /** Config for `@fastify/cors` */
+    private cors;
+    /**
+     * Integrates fastify session, API key and OAuth servers
+     * @param config object with entries as follow:
+     *     - `session` if passed, instantiate the session server (see class
+     *       documentation).  The value is an object with a `keyStorage` field
+     *       which must be present and should be the {@link KeyStorage} instance
+     *       where session IDs are stored.  A field called `options` whose
+     *       value is an {@link FastifySessionServerOptions} may also be
+     *       provided.
+     *     - `apiKey` if passed, instantiate the session server (see class
+     *       documentation).  The value is an object with a `keyStorage` field
+     *       which must be present and should be the {@link KeyStorage} instance
+     *       where API keys are stored.  A field called `options` whose
+     *       value is an {@link FastifyApiKeyServerOptions} may also be
+     *       provided.
+     *     - `oAuthAuthServer` if passed, instantiate the session server (see class
+     *       documentation).  The value is an object with a `keyStorage` field
+     *       which must be present and should be the {@link KeyStorage} instance
+     *       where authorization codes are stored.  This may be the same as
+     *       the table storing session IDs or may be different.  A field
+     *       called `clientStorage` with a value of type {@link OAuthClientStorage}
+     *       must be provided and is where OAuth client details are stored.
+     *       A field called `options` whose
+     *       value is an {@link FastifyAuthorizationServerOptions} may also be
+     *       provided.
+     *     - `oAuthClient` if present, an OAuth client will be created.
+     *       There must be a field called `authServerBaseUrl` and is the
+     *       bsae URL for the authorization server.  When validating access
+     *       tokens, the `iss` claim must match this.
+     *     - `oAuthClients` if present, an array of OAuth clients will be created.
+     *       There must be a field called `authServerBaseUrl` and is the
+     *       bsae URL for the authorization serve for each.  When validating access
+     *       tokens, the `iss` claim must match this.
+     *       Do not use both this and `oAuthClient`.
+     *     - `oAuthResServer` if present. an OAuth resource server will be
+     *       created.  It has one optional field: `protectedEndpoints`.  The
+     *       value is an object whose key is a URL (relative to the base
+     *       URL of the application).  The value is an object that contains
+     *       one optional parameter: `scope`, a string.  The client/user calling
+     *       the endpoint must have authorized this scope to call this endpoint,
+     *       otherwise an access denied error is returned.
+     *  @param options application-wide options of type
+     *       {@link FastifyServerOptions}.
+     *
+     */
+    constructor({ session, sessionAdapter, apiKey, oAuthAuthServer, oAuthClient, oAuthClients, oAuthResServer }: {
+        session?: {
+            keyStorage: KeyStorage;
+            options?: FastifySessionServerOptions;
+        };
+        sessionAdapter?: FastifySessionAdapter;
+        apiKey?: {
+            keyStorage: KeyStorage;
+            options?: FastifyApiKeyServerOptions;
+        };
+        oAuthAuthServer?: {
+            clientStorage: OAuthClientStorage;
+            keyStorage: KeyStorage;
+            options?: FastifyAuthorizationServerOptions;
+        };
+        oAuthClient?: {
+            authServerBaseUrl: string;
+            options?: FastifyOAuthClientOptions;
+        };
+        oAuthClients?: {
+            authServerBaseUrl: string;
+            options?: FastifyOAuthClientOptions;
+        }[];
+        oAuthResServer?: {
+            options?: FastifyOAuthResourceServerOptions;
+        };
+    }, options?: FastifyServerOptions);
+    /**
+     * This is a convenience function that just wraps
+     * {@link FastifySessionServer.validateCsrfToken}.
+     * @param request the fastify request
+     * @returns a string of the CSRF cookie value or undefined if it
+     * is not valid.
+     */
+    validateCsrfToken(request: FastifyRequest<{
+        Body: CsrfBodyType;
+    }>): string | undefined;
+    /**
+     * Calls the passed error function passed if the CSRF
+     * token in the request is invalid.
+     *
+     * Use this to require a CSRF token in your endpoints.
+     *
+     * @param request the Fastify request
+     * @param reply the Fastify reply object
+     * @param errorFn the error function to call if the CSRF token is invalid
+     * @returns if no error, returns an object with `error` set to false and
+     * `reply` set to the passed reply object.  Otherwise returns the reply
+     * from calling `errorFn`.
+     */
+    errorIfCsrfInvalid(request: FastifyRequest<{
+        Body: CsrfBodyType;
+    }>, reply: FastifyReply, errorFn?: FastifyErrorFn): Promise<{
+        reply: FastifyReply;
+        error: boolean;
+    }>;
+    /**
+     * Calls the passed error function passed if the user is not logged in.
+     *
+     * Use this to password protect endpoints.
+     *
+     * @param request the Fastify request
+     * @param reply the Fastify reply object
+     * @param errorFn the error function to call if the user is not logged in.
+     * @returns if no error, returns an object with `error` set to false and
+     * `reply` set to the passed reply object.  Otherwise returns the reply
+     * from calling `errorFn`.
+     */
+    errorIfNotLoggedIn(request: FastifyRequest<{
+        Body: CsrfBodyType;
+    }>, reply: FastifyReply, errorFn?: FastifyErrorFn): Promise<FastifyReply | undefined>;
+    /**
+     * Sends a reply by rendering the `errorPage` if present, or a standard
+     * error page if it isn't.
+     *
+     * The renderer configured for the reply object is called (Nunjucks
+     * by default) with the following data parameters:
+     * - `errorCode` See {@link @crossauth/common!ErrorCode}.
+     * - `errorCodeName` the text version of `errorCode`.
+     * - `msg` the error message
+     * - `httpStatus` the HTTP status code.
+     *
+     * @param reply the Fastify reply object
+     * @param status the HTTP status code to return
+     * @param errorPage the error page to render.
+     * @param error an error message string.  Ignored if `e` is defined.
+     * @param e optionall, an exception.  This will be logged and the message
+     *          will be sent to the error page.
+     * @returns the reply from rendering the error page.
+     *
+     */
+    static sendPageError(reply: FastifyReply, status: number, errorPage?: string, error?: string, e?: any): FastifyReply<import('fastify').RawServerDefault, IncomingMessage, ServerResponse<IncomingMessage>, import('fastify').RouteGenericInterface, unknown, import('fastify').FastifySchema, import('fastify').FastifyTypeProviderDefault, unknown>;
+    /**
+     * Creates a session ID but not associated with a user in the database.
+     *
+     * This is useful for tracking data between requests before a user
+     * has logged in
+     * @param request the Fastify request
+     * @param reply the Fastify reply
+     * @param data data to put in the sesion's `data` field.
+     * @returns the new session cookie value.
+     */
+    createAnonymousSession(request: FastifyRequest, reply: FastifyReply, data?: {
+        [key: string]: any;
+    }): Promise<string>;
+    /**
+     * Calls the `isAdminFn` passed during construction.
+     * @param user the user to check
+     * @returns true if the passed user is an admin, false otherwise.
+     */
+    static isAdmin(user: User): boolean;
+    /**
+     * Starts the Fastify app on the given port.
+     * @param port the port to listen on
+     */
+    start(port?: number): void;
+    /**
+     * Returns a hash of the session ID.  Used for logging (for security,
+     * the actual session ID is not logged)
+     * @param request the Fastify request
+     * @returns hash of the session ID
+     */
+    getHashOfSessionId(request: FastifyRequest): string;
+}