@crossauth/sveltekit 0.0.2

package/dist/sveltekitsession.d.ts

@@ -0,0 +1,629 @@
+import { KeyStorage, UserStorage, OAuthClientStorage, SessionManager, Authenticator, Cookie, SessionManagerOptions } from '@crossauth/backend';
+import { Key, User, UserInputFields, OAuthClient } from '@crossauth/common';
+import { RequestEvent, MaybePromise } from '@sveltejs/kit';
+import { SvelteKitUserEndpoints } from './sveltekituserendpoints';
+import { SvelteKitAdminEndpoints } from './sveltekitadminendpoints';
+import { SvelteKitUserClientEndpoints } from './sveltekituserclientendpoints';
+import { SvelteKitAdminClientEndpoints } from './sveltekitadminclientendpoints';
+import { SvelteKitSessionAdapter } from './sveltekitsessionadapter';
+
+export declare const CSRFHEADER = "X-CROSSAUTH-CSRF";
+type Header = {
+    name: string;
+    value: string;
+};
+/**
+ * Options for {@link SvelteKitSessionServer}.
+ */
+export interface SvelteKitSessionServerOptions extends SessionManagerOptions {
+    /**
+     * If enabling user login, must provide the user storage
+     */
+    userStorage?: UserStorage;
+    /**
+     * If enabling client endpoints, must provide the client storage
+     */
+    clientStorage?: OAuthClientStorage;
+    /**
+     * Factor 1 and 2 authenticators.
+     *
+     * The key is what appears in the `factor1` and `factor2` filed in the
+     * Users table.
+     */
+    authenticators?: {
+        [key: string]: Authenticator;
+    };
+    /**
+     * URL to call when factor2 authentication is required
+     */
+    factor2Url?: string;
+    /**
+     * URL to call when login is required.
+     *
+     * Default "/"
+     */
+    loginUrl?: string;
+    /**
+     * Default URL to go to after login (can be overridden by `next` POST param)
+     *
+     * Default "/"
+     */
+    loginRedirectUrl?: string;
+    /**
+     * URL to call when change password is required.
+     *
+     * Default "/changepassword"
+     */
+    changePasswordUrl?: string;
+    /**
+     * URL to call when change password is required.
+     *
+     * Default "/resetpassword"
+     */
+    requestPasswordResetUrl?: string;
+    /**
+     * URL to call when change factor2 is required.
+     *
+     * Default "/changefactor2"
+     */
+    changeFactor2Url?: string;
+    /** OAuth to support.  A comma-separated list from {@link @crossauth/common!OAuthFlows}.
+     * If [`all`], there must be none other in the list.
+     *
+     * This is needed not only by the authorization server but also the
+     * session server if you are creating endpoints for manipulating
+     * the OAuth client table.
+     *
+     * Default ['all']
+     */
+    validFlows?: string[];
+    /** Function that throws a {@link @crossauth/common!CrossauthError}
+     *  with {@link @crossauth/common!ErrorCode} `FormEntry` if the user
+     * doesn't confirm to local rules.  Doesn't validate passwords  */
+    validateUserFn?: (user: UserInputFields) => string[];
+    /** Function that creates a user from form fields.
+     * Default one takes fields that begin with `user_`, removing the `user_`
+     * prefix and filtering out anything not in the userEditableFields list in
+     * the user storage.
+         */
+    createUserFn?: (event: RequestEvent, data: {
+        [key: string]: string | undefined;
+    }, userEditableFields: string[]) => UserInputFields;
+    /** Function that updates a user from form fields.
+     * Default one takes fields that begin with `user_`, removing the `user_`
+     *  prefix and filtering out anything not in the userEditableFields list in
+     * the user storage.
+         */
+    updateUserFn?: (user: User, event: RequestEvent, data: {
+        [key: string]: string | undefined;
+    }, userEditableFields: string[]) => User;
+    /** Called when a new session token is going to be saved
+     *  Add additional fields to your session storage here.  Return a map of
+     * keys to values.  Don't consume form data.
+     * Use {@link JsonOrFormData }, which takes a copy first. */
+    addToSession?: (event: RequestEvent, formData: {
+        [key: string]: string;
+    }) => {
+        [key: string]: string | number | boolean | Date | undefined;
+    };
+    /** Called after the session ID is validated.
+     * Use this to add additional checks based on the request.
+     * Throw an exception if cecks fail
+     */
+    validateSession?: (session: Key, user: User | undefined, request: RequestEvent) => void;
+    /**
+     * These page endpoints need the second factor to be entered.  Visiting
+     * the page redirects the user to the factor2 page.
+     *
+     * You should include at least any URLs which validate a user, also
+     * the url for configuring 2FA.
+     *
+     * You can have wildcard which is useful for including path info,
+     * eg `/resetpassword/*`
+     *
+     * THe default is empty.
+     */
+    factor2ProtectedPageEndpoints?: string[];
+    /**
+     * These page endpoints need the second factor to be entered.  Making
+     * a call to these endpoints results in a response of
+     * `{"ok": true, "factor2Required": true `}.  The user should then
+     * make a call to `/api/factor2`.   If the credetials are correct, the
+     * response will be that of the original request.
+     *
+     * You can have wildcard which is useful for including path info,
+     * eg `/resetpassword/*`
+     */
+    factor2ProtectedApiEndpoints?: string[];
+    /**
+     * These page endpoints need the the user to be logged in.  If not,
+     * the user is directed to the login page.
+     *
+     * You can have wildcard which is useful for including path info,
+     * eg `/resetpassword/*`
+     *
+     * The default is empty.
+     *
+     */
+    loginProtectedPageEndpoints?: string[];
+    /**
+     * These page endpoints need the the user to be logged in.  If not,
+     * the user is is sent an unauthorized response
+     *
+     * The default is empty
+     */
+    loginProtectedApiEndpoints?: string[];
+    /**
+     * See `adminPageEndpoints`
+     */
+    unauthorizedUrl?: string;
+    /**
+     * These page endpoints need an admin user to be logged in.
+     *
+     * This
+     * is defined by the isAdminFn option in {@link SvelteKitServerOptions}.
+     * The default one is to check the `admin` boolean field in the user
+     * object. If there is no user, or the user is not an admin, a 401
+     * page is returned,
+     *
+     * The default is empty
+     *
+     * If unauthorizedUrl is defined, that will be rendered.  Otherwise
+     * a simple text message will be displayed.
+     *
+     */
+    adminPageEndpoints?: string[];
+    /**
+     * Same as adminPageEndpoints but returns a JSON error instead of an
+     * error page
+     *
+     * This
+     * is defined by the isAdminFn option in {@link SvelteKitServerOptions}.
+     * The default one is to check the `admin` boolean field in the user
+     * object. If there is no user, or the user is not an admin, a 401
+     * page is returned,
+     *
+     * The default is empty
+     *
+     */
+    adminApiEndpoints?: string[];
+    /**
+     * Turns on email verification.  This will cause the verification tokens to
+     * be sent when the account
+     * is activated and when email is changed.  Default false.
+     */
+    enableEmailVerification?: boolean;
+    /**
+     * Turns on password reset.  Default false.
+     */
+    enablePasswordReset?: boolean;
+    /**
+     * CSRF protection is on by default but can be disabled by setting
+     * this to false.
+     *
+     * Sveltekit has its own CSRF protection enabled by default.  If you
+     * disable it here, make sure you are not doing anything that bypasses
+     * Sveltekit's own protection.
+     */
+    enableCsrfProtection?: boolean;
+    /**
+     * This parameter affects users who are not logged in with a session ID
+     * but with an OAuth access token.  Such users can only update their user
+     * record if the scoped named in this variable has been authorized by
+     * that user for the client.
+     *
+     * By default, no scopes are authorized to edit the user.
+     */
+    editUserScope?: string;
+    /**
+     * Admin pages provide functionality for searching for users.  By
+     * default the search string must exactly match the client name
+     * (after normalizing
+     * and lowercasing).  Override this behaviour with this function
+     * @param searchTerm the search term
+     * @param userStorage the user storage to search
+     * @returns array of matching users
+     */
+    userSearchFn?: (searchTerm: string, userStorage: UserStorage, skip?: number, take?: number) => Promise<User[]>;
+    /**
+     * Admin pages provide functionality for searching for OAuth clients.  By
+     * default the search string must exactly match the client_name exactly.
+     * Override this behaviour with this function
+     * @param searchTerm the search term
+     * @param clientStorage the client storage to search
+     * @returns array of matching users
+     */
+    clientSearchFn?: (searchTerm: string, clientStorage: OAuthClientStorage, skip: number, take: number, userid?: string | number | null) => Promise<OAuthClient[]>;
+    /** Pass the Sveltekit redirect function */
+    redirect?: any;
+    /** Pass the Sveltekit error function */
+    error?: any;
+}
+/**
+ * The Sveltekit session server.
+ *
+ * You shouldn't have to instantiate this directly.  It is created when
+ * you create a {@link SveltekitServer} object.
+ */
+export declare class SvelteKitSessionServer implements SvelteKitSessionAdapter {
+    /**
+     * Hook to check if the user is logged in and set data in `locals`
+     * accordingly.
+     */
+    readonly sessionHook: (input: {
+        event: RequestEvent;
+    }) => MaybePromise<{
+        headers: Header[];
+    }>;
+    readonly twoFAHook: (input: {
+        event: RequestEvent;
+    }) => MaybePromise<{
+        twofa: boolean;
+        ok: boolean;
+        response?: Response;
+    }>;
+    /**
+     * Key storage taken from constructor args.
+     * See {@link SvelteKitSessionServer.constructor}.
+     */
+    readonly keyStorage: KeyStorage;
+    /**
+     * Session Manager taken from constructor args.
+     * See {@link SvelteKitSessionServer.constructor}.
+     */
+    readonly sessionManager: SessionManager;
+    /**
+     * User storage taken from constructor args.
+     * See {@link SvelteKitSessionServer.constructor}.
+     */
+    readonly userStorage?: UserStorage;
+    /**
+     * User storage taken from constructor args.
+     * See {@link SvelteKitSessionServer.constructor}.
+     */
+    readonly clientStorage?: OAuthClientStorage;
+    /**
+     * Funtion to validate users upon creation.  Taken from the options during
+     * construction or the default value.
+     * See {@link FastifySessionServerOptions}.
+     */
+    validateUserFn: (user: UserInputFields) => string[];
+    /**
+     * Funtion to create a user record from form fields.  Taken from the options during
+     * construction or the default value.
+     * See {@link FastifySessionServerOptions}.
+     */
+    createUserFn: (event: RequestEvent, data: {
+        [key: string]: string | undefined;
+    }, userEditableFields: string[]) => UserInputFields;
+    /**
+     * Funtion to update a user record from form fields.  Taken from the options during
+     * construction or the default value.
+     * See {@link FastifySessionServerOptions}.
+     */
+    updateUserFn: (user: User, event: RequestEvent, data: {
+        [key: string]: string | undefined;
+    }, userEditableFields: string[]) => User;
+    /**
+     * The set of authenticators taken from constructor args.
+     * See {@link FastifySessionServer.constructor}.
+     */
+    readonly authenticators: {
+        [key: string]: Authenticator;
+    };
+    /**
+     * The set of allowed authenticators taken from the options during
+     * construction.
+     *
+     * The default is `[{name: "none", friendlyName: "none"}]`
+     */
+    readonly allowedFactor2: {
+        name: string;
+        friendlyName: string;
+        configurable: boolean;
+    }[];
+    /**
+     * The set of allowed authenticators taken from the options during
+     * construction.
+     *
+     * The default is `["none"]`.
+     */
+    readonly allowedFactor2Names: string[];
+    /** Called when a new session token is going to be saved
+     *  Add additional fields to your session storage here.  Return a map of
+     * keys to values  */
+    addToSession?: (event: RequestEvent, formData: {
+        [key: string]: string;
+    }) => {
+        [key: string]: string | number | boolean | Date | undefined;
+    };
+    /**
+     * The set of allowed authenticators taken from the options during
+     * construction.
+     */
+    private validateSession?;
+    private factor2ProtectedPageEndpoints;
+    private factor2ProtectedApiEndpoints;
+    private loginProtectedPageEndpoints;
+    private loginProtectedApiEndpoints;
+    private adminPageEndpoints;
+    private adminApiEndpoints;
+    readonly unauthorizedUrl: string | undefined;
+    readonly enableCsrfProtection = true;
+    /** Whether email verification is enabled.
+     *
+     * Reads from constructor options
+     */
+    readonly enableEmailVerification = false;
+    /** Whether password reset is enabled.
+     *
+     * Reads from constructor options
+     */
+    readonly enablePasswordReset = false;
+    private factor2Url;
+    /**
+     * Use these to access the `load` and `action` endpoints for functions
+     * provided by Crossauth.  These are the ones intended for users to
+     * have access to.
+     *
+     * See {@link SvelteKitUserEndpoints}
+     */
+    readonly userEndpoints: SvelteKitUserEndpoints;
+    /**
+     * Use these to access the `load` and `action` endpoints for functions
+     * provided by Crossauth that relate to manipulating OAuth clients in the
+     * database.  These are the ones intended for users to
+     * have access to.
+     *
+     * See {@link SvelteKitUserEndpoints}
+     */
+    readonly userClientEndpoints: SvelteKitUserClientEndpoints;
+    /**
+     * Use these to access the `load` and `action` endpoints for functions
+     * provided by Crossauth that relate to manipulating OAuth clients in the
+     * database as admin.  These are the ones intended for users to
+     * have access to.
+     *
+     * See {@link SvelteKitAdminEndpoints}
+     */
+    readonly adminClientEndpoints: SvelteKitAdminClientEndpoints;
+    /**
+     * Use these to access the `load` and `action` endpoints for functions
+     * provides by Crossauth.  These are the ones intended for admins to
+     * have access to.
+     *
+     * See {@link SvelteKitAdminEndpoints}
+     */
+    readonly adminEndpoints: SvelteKitAdminEndpoints;
+    readonly redirect: any;
+    readonly error: any;
+    /**
+     * This is read from options during construction.
+     *
+     * See {@link SvelteKitServerOptions}.
+     */
+    readonly editUserScope?: string;
+    /**
+     * Constructor
+     * @param keyStorage where session IDs, email verification and reset tokens are stored
+     * @param authenticators valid authenticators that can be in `factor1` or `factor2`
+     *    of the user.  See class documentation for {@link SvelteKitServer} for an example.
+     * @param options See {@link SvelteKitSessionServerOptions}.
+     */
+    constructor(keyStorage: KeyStorage, authenticators: {
+        [key: string]: Authenticator;
+    }, options?: SvelteKitSessionServerOptions);
+    /**
+     * Returns the session cookie value from the Sveltekit request event
+     * @param event the request event
+     * @returns the whole cookie value
+     */
+    getSessionCookieValue(event: RequestEvent): string | undefined;
+    /**
+     * Returns the session cookie value from the Sveltekit request event
+     * @param event the request event
+     * @returns the whole cookie value
+     */
+    getCsrfCookieValue(event: RequestEvent): string | undefined;
+    private clearCookie;
+    /**
+     * Sets headers in the request event.
+     *
+     * Used internally by {@link SveltekitServer}.  Shouldn't be necessary
+     * to call this directly.
+     * @param headers the headres to set
+     * @param resp the response object to set them in
+     */
+    setHeaders(headers: Header[], resp: Response): void;
+    /**
+     * Sets the CSRF cookie.
+     *
+     * Used internally.  Shouldn't be necessary
+     * to call this directly.
+     * @param cookie the new cookie and parameters
+     * @param event the request event
+     */
+    setCsrfCookie(cookie: Cookie, event: RequestEvent): void;
+    private setHeader;
+    /**
+     * Returns a hash of the session cookie value.
+     *
+     * Used only in reporting, so that logs don't contain the actual session ID.
+     *
+     * @param event the Sveltelkit request event
+     * @returns a stering hash of the cookie value
+     */
+    getHashOfSessionCookie(event: RequestEvent): string;
+    /**
+     * Returns a hash of the CSRF cookie value.
+     *
+     * Used only in reporting, so that logs don't contain the actual CSRF cookie value.
+     *
+     * @param event the Sveltelkit request event
+     * @returns a stering hash of the cookie value
+     */
+    getHashOfCsrfCookie(event: RequestEvent): string;
+    /**
+     * Returns a CSRF token if the CSRF cookie is valid.
+     *
+     * Used internally.  Shouldn't be necessary
+     * to call this directly.
+     *
+     * @param event the request event
+     * @param headers headers the token will be added to, as well as
+     *   adding it to locals
+     * @returns the string CSRF token for inclusion in forms
+     */
+    csrfToken(event: RequestEvent, headers: Header[]): Promise<string | undefined>;
+    /**
+     * Used internally to update an existing Sveltekit request object with
+     * a new body and headers.
+     *
+     * Used when restoring a request that was interrupted for 2FA
+     *
+     * @param event the request event
+     * @param params JSON params to add to the new body
+     * @param contentType the new content type
+     * @returns the updated request event
+     */
+    static updateRequest(event: RequestEvent, params: {
+        [key: string]: string;
+    }, contentType: string): RequestEvent<Partial<Record<string, string>>, string | null>;
+    /**
+     * 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(event: RequestEvent): string;
+    /**
+     * Returns whether or not 2FA authentication was initiated as a result
+     * of visiting a page protected by it
+     * @param event the request event
+     * @returns true or false
+     */
+    factor2PageVisitStarted(event: RequestEvent): Promise<boolean>;
+    /**
+     * Returns whether a page being visited as part of a request event is
+     * configured to be protected by login.
+     *
+     * See {@link SvelteKitSessionServerOptions.loginProtectedPageEndpoints}.
+     *
+     * @param event the request event
+     * @returns true or false
+     */
+    isLoginPageProtected(event: RequestEvent | string): boolean;
+    /**
+     * Returns whether an API call is being visited as part of a request event is
+     * configured to be protected by login.
+     *
+     * See {@link SvelteKitSessionServerOptions.loginProtectedApiEndpoints}.
+     *
+     * @param event the request event
+     * @returns true or false
+     */
+    isLoginApiProtected(event: RequestEvent | string): boolean;
+    /**
+     * Returns whether a page being visited as part of a request event is
+     * configured to be protected by 2FA.
+     *
+     * See {@link SvelteKitSessionServerOptions.factor2ProtectedPageEndpoints}.
+     *
+     * @param event the request event
+     * @returns true or false
+     */
+    isFactor2PageProtected(event: RequestEvent | string): boolean;
+    /**
+     * Returns whether an API call is being visited as part of a request event is
+     * configured to be protected by 2FA.
+     *
+     * See {@link SvelteKitSessionServerOptions.factor2ProtectedApiEndpoints}.
+     *
+     * @param event the request event
+     * @returns true or false
+     */
+    isFactor2ApiProtected(event: RequestEvent | string): boolean;
+    /**
+     * Returns whether a page being visited as part of a request event is
+     * configured to be protected as admin only.
+     *
+     * See {@link SvelteKitSessionServerOptions.adminPageEndpoints}.
+     *
+     * @param event the request event
+     * @returns true or false
+     */
+    isAdminPageEndpoint(event: RequestEvent | string): boolean;
+    /**
+     * Returns whether an AP call being visited as part of a request event is
+     * configured to be protected as admin only.
+     *
+     * See {@link SvelteKitSessionServerOptions.adminApiEndpoints}.
+     *
+     * @param event the request event
+     * @returns true or false
+     */
+    isAdminApiEndpoint(event: RequestEvent | string): boolean;
+    /**
+     * Creates an anonymous session, setting the `Set-Cookue` headers
+     * in the reply.
+     *
+     * An anonymous sessiin is a session cookie that is not associated
+     * with a user (`userid` is undefined).  It can be used to persist
+     * data between sessions just like a regular user session ID.
+     *
+     * @param request the Fastify request
+     * @param reply the Fastify reply
+     * @param data session data to save
+     * @returns the session cookie value
+     */
+    createAnonymousSession(event: RequestEvent, data?: {
+        [key: string]: any;
+    }): Promise<string>;
+    /**
+     * Sets locals based on session and CSRF cookies.
+     *
+     * Sets things like `locals.user`.  You can call this if you need them
+     * updated based on cookie settings and a page load hasn't been done
+     * (ie the hooks haven't run).
+     *
+     * @param event the Sveltekit request event.
+     */
+    refreshLocals(event: RequestEvent): Promise<void>;
+    csrfProtectionEnabled(): boolean;
+    getCsrfToken(event: RequestEvent): string | undefined;
+    getUser(event: RequestEvent): User | undefined;
+    /**
+     * Returns the data stored along with the session server-side, with the
+     * given name
+     * @param event the Sveltekit request event
+     * @param name tjhe data name to return
+     * @returns an object or undefined.
+     */
+    getSessionData(event: RequestEvent, name: string): Promise<{
+        [key: string]: any;
+    } | undefined>;
+    /**
+     * Updates or sets the given field in the session `data` field.
+     *
+     * The `data` field in the session record is assumed to be JSON
+     *
+     * @param event the Sveltekit request event
+     * @param name the name of the field to set
+     * @param value the value to set it to.
+     */
+    updateSessionData(event: RequestEvent, name: string, value: any): Promise<void>;
+    updateManySessionData(event: RequestEvent, dataArray: {
+        dataName: string;
+        value: any;
+    }[]): Promise<void>;
+    /**
+     * Deletes the given field from the session `data` field.
+     *
+     * The `data` field in the session record is assumed to be JSON
+     *
+     * @param event the Sveltekit request event
+     * @param name the name of the field to set
+     */
+    deleteSessionData(event: RequestEvent, name: string): Promise<void>;
+}
+export {};

package/dist/sveltekitsessionadapter.d.ts

@@ -0,0 +1,48 @@
+import { RequestEvent } from '@sveltejs/kit';
+import { User } from '@crossauth/common';
+
+export declare abstract class SvelteKitSessionAdapter {
+    abstract csrfProtectionEnabled(): boolean;
+    abstract getCsrfToken(event: RequestEvent): string | undefined;
+    abstract getUser(event: RequestEvent): User | undefined;
+    /**
+     * Updates a field in the session data in the key storage record,
+     *
+     * The `data` field is assumed to be JSON.  Just the field with the given
+     * name is updated and the rest is unchanged.
+     * @param event the Sveltekit request event
+     * @param name the field within `data` to update
+     * @param value the value to set it to
+     */
+    abstract updateSessionData(event: RequestEvent, name: string, value: any): Promise<void>;
+    /**
+     * Same as `updateData` but updates many within same transaction
+     *
+     * The `data` field is assumed to be JSON.  Just the field with the given
+     * name is updated and the rest is unchanged.
+     * @param request the Fastifdy request
+     * @param dataArray data to update
+     */
+    abstract updateManySessionData(event: RequestEvent, dataArray: {
+        dataName: string;
+        value: any;
+    }[]): Promise<void>;
+    /**
+    * Deletes a field from the session data in the key storage record,
+    *
+    * The `data` field is assumed to be JSON.  Just the field with the given
+    * name is updated and the rest is unchanged.
+     * @param event the Sveltekit request event
+    * @param name the field within `data` to update
+    */
+    abstract deleteSessionData(event: RequestEvent, name: string): Promise<void>;
+    /**
+     * Return data stored in the session with key `name` or undefined if not present
+     * @param event the Sveltekit request event
+     * @param name name of the data to fetch
+     * @return an object of the data, or undefined
+     */
+    abstract getSessionData(event: RequestEvent, name: string): Promise<{
+        [key: string]: any;
+    } | undefined>;
+}