@adonisjs/auth 8.2.2 → 9.0.0-0

package/build/src/core/token_providers/database.js

@@ -0,0 +1,113 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import debug from '../../auth/debug.js';
+/**
+ * A generic implementation to read tokens from the database
+ */
+export class DatabaseTokenProvider {
+    db;
+    options;
+    constructor(
+    /**
+     * Reference to the database query builder needed to
+     * query the database for tokens
+     */
+    db, 
+    /**
+     * Options accepted
+     */
+    options) {
+        this.db = db;
+        this.options = options;
+        debug('db_token_provider: options %O', options);
+    }
+    /**
+     * Returns an instance of the query builder
+     */
+    getQueryBuilder() {
+        return this.db.connection(this.options.connection).query();
+    }
+    /**
+     * Returns an instance of the query builder for insert
+     * queries
+     */
+    getInsertQueryBuilder() {
+        return this.db.connection(this.options.connection).insertQuery();
+    }
+    /**
+     * Persists token inside the database
+     */
+    async createToken(token) {
+        const parsedToken = this.parseToken(token);
+        debug('db_token_provider: creating token %O', parsedToken);
+        await this.getInsertQueryBuilder()
+            .table(this.options.table)
+            .insert({
+            ...parsedToken,
+        });
+    }
+    /**
+     * Finds a token by series inside the database and returns an
+     * instance of it.
+     *
+     * Returns null if the token is missing or expired
+     */
+    async getTokenBySeries(series) {
+        debug('db_token_provider: reading token by series %s', series);
+        const token = await this.getQueryBuilder()
+            .from(this.options.table)
+            .where('series', series)
+            .limit(1)
+            .first();
+        if (!token) {
+            debug('db_token_provider:: token %O', token);
+            return null;
+        }
+        if (typeof token.expires_at === 'number') {
+            token.expires_at = new Date(token.expires_at);
+        }
+        if (typeof token.created_at === 'number') {
+            token.created_at = new Date(token.created_at);
+        }
+        if (typeof token.updated_at === 'number') {
+            token.updated_at = new Date(token.updated_at);
+        }
+        debug('db_token_provider:: token %O', token);
+        /**
+         * Return null when token has been expired
+         */
+        if (token.expires_at && token.expires_at instanceof Date && token.expires_at < new Date()) {
+            return null;
+        }
+        return this.prepareToken(token);
+    }
+    /**
+     * Removes a token from the database by the
+     * series number
+     */
+    async deleteTokenBySeries(series) {
+        debug('db_token_provider: deleting token by series %s', series);
+        await this.getQueryBuilder().from(this.options.table).where('series', series).del();
+    }
+    /**
+     * Updates token hash and expiry
+     */
+    async updateTokenBySeries(series, hash, expiresAt) {
+        const updatePayload = {
+            token: hash,
+            updated_at: new Date(),
+            expires_at: expiresAt,
+        };
+        debug('db_token_provider: updating token by series %s: %O', series, updatePayload);
+        await this.getQueryBuilder()
+            .from(this.options.table)
+            .where('series', series)
+            .update(updatePayload);
+    }
+}

package/build/src/core/types.d.ts

@@ -0,0 +1,178 @@
+import type { QueryClientContract } from '@adonisjs/lucid/types/database';
+import type { GuardUser } from './guard_user.js';
+import type { PROVIDER_REAL_USER } from '../auth/symbols.js';
+import type { LucidModel, LucidRow } from '@adonisjs/lucid/types/model';
+/**
+ * A token represents an opaque token issued to a client
+ * to perform a specific task.
+ *
+ * The raw value of a token is only visible at the time of
+ * issuing it and one must persist hash to the database.
+ */
+export interface TokenContract {
+    /**
+     * Token type to uniquely identify a bucket of tokens
+     */
+    readonly type: string;
+    /**
+     * The plain text value. Only exists when the token is first
+     * created
+     */
+    value?: string;
+    /**
+     * Additional metadata associated with the token.
+     */
+    metaData?: Record<string, any>;
+    /**
+     * The token hash for persisting the token in a database
+     */
+    hash: string;
+    /**
+     * A unique readable series counter to find the token inside the
+     * database.
+     */
+    series: string;
+    /**
+     * Timestamp when the token was first persisted
+     */
+    createdAt: Date;
+    /**
+     * Timestamp when the token was updated
+     */
+    updatedAt: Date;
+    /**
+     * Timestamp when the token will expire
+     */
+    expiresAt?: Date;
+    /**
+     * Verifies the raw text value against the hash
+     */
+    verify(value: string): boolean;
+}
+/**
+ * The UserProvider is used to lookup a user for authentication
+ */
+export interface UserProviderContract<RealUser> {
+    [PROVIDER_REAL_USER]: RealUser;
+    /**
+     * Creates a user object that guards can use for
+     * authentication.
+     */
+    createUserForGuard(user: RealUser): Promise<GuardUser<RealUser>>;
+    /**
+     * Find a user by uid. The uid could be one or multiple fields
+     * to unique identify a user.
+     *
+     * This method is called when finding a user for login
+     */
+    findByUid(value: string | number): Promise<GuardUser<RealUser> | null>;
+    /**
+     * Find a user by unique primary id. This method is called when
+     * authenticating user from their session.
+     */
+    findById(value: string | number): Promise<GuardUser<RealUser> | null>;
+}
+/**
+ * The TokenProvider is used to lookup/persist tokens during authentication
+ */
+export interface TokenProviderContract<Token> {
+    /**
+     * Returns a token by the series counter, or null when token is
+     * missing
+     */
+    getTokenBySeries(series: string): Promise<Token | null>;
+    /**
+     * Deletes a token by the series counter
+     */
+    deleteTokenBySeries(series: string): Promise<void>;
+    /**
+     * Updates a token by the series counter
+     */
+    updateTokenBySeries(series: string, hash: string, expiresAt: Date): Promise<void>;
+    /**
+     * Creates a new token and persists it to the database
+     */
+    createToken(token: Token): Promise<void>;
+}
+/**
+ * A lucid model that can be used during authentication
+ */
+export type LucidAuthenticatable = LucidModel & {
+    new (): LucidRow & {
+        /**
+         * Verify the plain text password against the user password
+         * hash
+         */
+        verifyPasswordForAuth(plainTextPassword: string): Promise<boolean>;
+    };
+};
+/**
+ * Options accepted by the Lucid user provider
+ */
+export type LucidUserProviderOptions<Model extends LucidAuthenticatable> = {
+    /**
+     * Optionally define the connection to use when making database
+     * queries
+     */
+    connection?: string;
+    /**
+     * Optionally define the query client instance to use for making
+     * database queries.
+     *
+     * When both "connection" and "client" are defined, the client will
+     * be given the preference.
+     */
+    client?: QueryClientContract;
+    /**
+     * Model to use for authentication
+     */
+    model: () => Promise<{
+        default: Model;
+    }>;
+    /**
+     * An array of uids to use when finding a user for login. Make
+     * sure all fields can be used to uniquely lookup a user.
+     */
+    uids: Extract<keyof InstanceType<Model>, string>[];
+};
+/**
+ * Options accepted by the Database user provider
+ */
+export type DatabaseUserProviderOptions<RealUser extends Record<string, any>> = {
+    /**
+     * Optionally define the connection to use when making database
+     * queries
+     */
+    connection?: string;
+    /**
+     * Database table to query to find the user
+     */
+    table: string;
+    /**
+     * Column name to read the hashed password
+     */
+    passwordColumnName: string;
+    /**
+     * An array of uids to use when finding a user for login. Make
+     * sure all fields can be used to uniquely lookup a user.
+     */
+    uids: Extract<keyof RealUser, string>[];
+    /**
+     * The name of the id column to unique identify the user.
+     */
+    id: string;
+};
+/**
+ * Options accepted by the Database token provider
+ */
+export type DatabaseTokenProviderOptions = {
+    /**
+     * Optionally define the connection to use when making database
+     * queries
+     */
+    connection?: string;
+    /**
+     * Database table to query to find the user
+     */
+    table: string;
+};

package/build/{adonis-typings/auth.js → src/core/types.js}

@@ -1,8 +1,9 @@
 /*
  * @adonisjs/auth
  *
- * (c) Harminder Virk <virk@adonisjs.com>
+ * (c) AdonisJS
  *
  * For the full copyright and license information, please view the LICENSE
  * file that was distributed with this source code.
  */
+export {};

package/build/src/core/user_providers/database.d.ts

@@ -0,0 +1,78 @@
+import type { Hash } from '@adonisjs/core/hash';
+import type { Database } from '@adonisjs/lucid/database';
+import { GuardUser } from '../guard_user.js';
+import { PROVIDER_REAL_USER } from '../../auth/symbols.js';
+import type { DatabaseUserProviderOptions, UserProviderContract } from '../types.js';
+/**
+ * Database user represents a guard user used by authentication guards
+ * to perform authentication.
+ */
+declare class DatabaseUser<RealUser extends Record<string, any>> extends GuardUser<RealUser> {
+    #private;
+    constructor(realUser: RealUser, hasher: Hash, options: {
+        id: string;
+        passwordColumnName: string;
+    });
+    /**
+     * @inheritdoc
+     */
+    getId(): string | number;
+    /**
+     * @inheritdoc
+     */
+    verifyPassword(plainTextPassword: string): Promise<boolean>;
+}
+/**
+ * Database user provider is used to lookup user for authentication
+ * using the Database query builder.
+ */
+export declare abstract class BaseDatabaseUserProvider<RealUser extends Record<string, any>> implements UserProviderContract<RealUser> {
+    /**
+     * Reference to the database query builder needed to
+     * query the database for users
+     */
+    protected db: Database;
+    /**
+     * Hasher is used to verify plain text passwords
+     */
+    protected hasher: Hash;
+    /**
+     * Options accepted
+     */
+    protected options: DatabaseUserProviderOptions<RealUser>;
+    [PROVIDER_REAL_USER]: RealUser;
+    constructor(
+    /**
+     * Reference to the database query builder needed to
+     * query the database for users
+     */
+    db: Database, 
+    /**
+     * Hasher is used to verify plain text passwords
+     */
+    hasher: Hash, 
+    /**
+     * Options accepted
+     */
+    options: DatabaseUserProviderOptions<RealUser>);
+    /**
+     * Returns an instance of the query builder
+     */
+    protected getQueryBuilder(): import("@adonisjs/lucid/types/querybuilder").DatabaseQueryBuilderContract<any>;
+    /**
+     * Returns an instance of the "DatabaseUser" that guards
+     * can use for authentication
+     */
+    createUserForGuard(user: RealUser): Promise<DatabaseUser<RealUser>>;
+    /**
+     * Finds a user by id by query the configured database
+     * table
+     */
+    findById(value: string | number): Promise<DatabaseUser<RealUser> | null>;
+    /**
+     * Finds a user using one of the pre-configured unique
+     * ids, via the configured model.
+     */
+    findByUid(value: string | number): Promise<DatabaseUser<RealUser> | null>;
+}
+export {};

package/build/src/core/user_providers/database.js

@@ -0,0 +1,117 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { RuntimeException } from '@poppinss/utils';
+import debug from '../../auth/debug.js';
+import { GuardUser } from '../guard_user.js';
+import { PROVIDER_REAL_USER } from '../../auth/symbols.js';
+/**
+ * Database user represents a guard user used by authentication guards
+ * to perform authentication.
+ */
+class DatabaseUser extends GuardUser {
+    #options;
+    #hasher;
+    constructor(realUser, hasher, options) {
+        super(realUser);
+        this.#hasher = hasher;
+        this.#options = options;
+    }
+    /**
+     * @inheritdoc
+     */
+    getId() {
+        const id = this.realUser[this.#options.id];
+        if (!id) {
+            throw new RuntimeException(`Invalid user object. The value of column "${this.#options.id}" is undefined or null`);
+        }
+        return id;
+    }
+    /**
+     * @inheritdoc
+     */
+    async verifyPassword(plainTextPassword) {
+        const password = this.realUser[this.#options.passwordColumnName];
+        if (!password) {
+            throw new RuntimeException(`Cannot verify password during login. The value of column "${this.#options.passwordColumnName}" is undefined or null`);
+        }
+        return this.#hasher.verify(password, plainTextPassword);
+    }
+}
+/**
+ * Database user provider is used to lookup user for authentication
+ * using the Database query builder.
+ */
+export class BaseDatabaseUserProvider {
+    db;
+    hasher;
+    options;
+    constructor(
+    /**
+     * Reference to the database query builder needed to
+     * query the database for users
+     */
+    db, 
+    /**
+     * Hasher is used to verify plain text passwords
+     */
+    hasher, 
+    /**
+     * Options accepted
+     */
+    options) {
+        this.db = db;
+        this.hasher = hasher;
+        this.options = options;
+        debug('db_user_provider: options %O', options);
+    }
+    /**
+     * Returns an instance of the query builder
+     */
+    getQueryBuilder() {
+        return this.db.connection(this.options.connection).query();
+    }
+    /**
+     * Returns an instance of the "DatabaseUser" that guards
+     * can use for authentication
+     */
+    async createUserForGuard(user) {
+        if (!user || typeof user !== 'object') {
+            throw new RuntimeException(`Invalid user object. It must be a database row object from the "${this.options.table}" table`);
+        }
+        debug('db_user_provider: converting user object to guard user %O', user);
+        return new DatabaseUser(user, this.hasher, this.options);
+    }
+    /**
+     * Finds a user by id by query the configured database
+     * table
+     */
+    async findById(value) {
+        const query = this.getQueryBuilder().from(this.options.table);
+        debug('db_user_provider: finding user by id %s', value);
+        const user = await query.where(this.options.id, value).limit(1).first();
+        if (!user) {
+            return null;
+        }
+        return this.createUserForGuard(user);
+    }
+    /**
+     * Finds a user using one of the pre-configured unique
+     * ids, via the configured model.
+     */
+    async findByUid(value) {
+        const query = this.getQueryBuilder().from(this.options.table);
+        this.options.uids.forEach((uid) => query.orWhere(uid, value));
+        debug('db_user_provider: finding user by uids, uids: %O, value: %s', this.options.uids, value);
+        const user = await query.limit(1).first();
+        if (!user) {
+            return null;
+        }
+        return this.createUserForGuard(user);
+    }
+}

package/build/src/core/user_providers/lucid.d.ts

@@ -0,0 +1,61 @@
+import { GuardUser } from '../guard_user.js';
+import { PROVIDER_REAL_USER } from '../../auth/symbols.js';
+import type { UserProviderContract, LucidAuthenticatable, LucidUserProviderOptions } from '../types.js';
+/**
+ * Lucid user represents a guard user, used by authentication guards
+ * to perform authentication.
+ */
+declare class LucidUser<RealUser extends InstanceType<LucidAuthenticatable>> extends GuardUser<RealUser> {
+    /**
+     * @inheritdoc
+     */
+    getId(): string | number;
+    /**
+     * @inheritdoc
+     */
+    verifyPassword(plainTextPassword: string): Promise<boolean>;
+}
+/**
+ * Lucid user provider is used to lookup user for authentication
+ * using a Lucid model.
+ */
+export declare abstract class BaseLucidUserProvider<UserModel extends LucidAuthenticatable> implements UserProviderContract<InstanceType<UserModel>> {
+    /**
+     * Lucid provider options
+     */
+    protected options: LucidUserProviderOptions<UserModel>;
+    [PROVIDER_REAL_USER]: InstanceType<UserModel>;
+    /**
+     * Reference to the lazily imported model
+     */
+    protected model?: UserModel;
+    constructor(
+    /**
+     * Lucid provider options
+     */
+    options: LucidUserProviderOptions<UserModel>);
+    /**
+     * Imports the model from the provider, returns and caches it
+     * for further operations.
+     */
+    protected getModel(): Promise<UserModel>;
+    /**
+     * Returns an instance of the query builder
+     */
+    protected getQueryBuilder(model: UserModel): import("@adonisjs/lucid/types/model").ModelQueryBuilderContract<UserModel, InstanceType<UserModel>>;
+    /**
+     * Returns an instance of the "LucidUser" that guards
+     * can use for authentication
+     */
+    createUserForGuard(user: InstanceType<UserModel>): Promise<LucidUser<InstanceType<UserModel>>>;
+    /**
+     * Finds a user by id using the configured model.
+     */
+    findById(value: string | number): Promise<LucidUser<InstanceType<UserModel>> | null>;
+    /**
+     * Finds a user using one of the pre-configured unique
+     * ids, via the configured model.
+     */
+    findByUid(value: string | number): Promise<LucidUser<InstanceType<UserModel>> | null>;
+}
+export {};

package/build/src/core/user_providers/lucid.js

@@ -0,0 +1,122 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { RuntimeException } from '@poppinss/utils';
+import debug from '../../auth/debug.js';
+import { GuardUser } from '../guard_user.js';
+import { PROVIDER_REAL_USER } from '../../auth/symbols.js';
+/**
+ * Lucid user represents a guard user, used by authentication guards
+ * to perform authentication.
+ */
+class LucidUser extends GuardUser {
+    /**
+     * @inheritdoc
+     */
+    getId() {
+        const id = this.realUser.$primaryKeyValue;
+        /**
+         * Ensure id exists
+         */
+        if (!id) {
+            const model = this.realUser.constructor;
+            const modelName = model.name;
+            const primaryKey = model.primaryKey;
+            throw new RuntimeException(`Cannot use "${modelName}" model for authentication. The value of column "${primaryKey}" is undefined or null`);
+        }
+        return id;
+    }
+    /**
+     * @inheritdoc
+     */
+    async verifyPassword(plainTextPassword) {
+        return this.realUser.verifyPasswordForAuth(plainTextPassword);
+    }
+}
+/**
+ * Lucid user provider is used to lookup user for authentication
+ * using a Lucid model.
+ */
+export class BaseLucidUserProvider {
+    options;
+    /**
+     * Reference to the lazily imported model
+     */
+    model;
+    constructor(
+    /**
+     * Lucid provider options
+     */
+    options) {
+        this.options = options;
+        debug('lucid_user_provider: options %O', options);
+    }
+    /**
+     * Imports the model from the provider, returns and caches it
+     * for further operations.
+     */
+    async getModel() {
+        if (this.model) {
+            return this.model;
+        }
+        const importedModel = await this.options.model();
+        this.model = importedModel.default;
+        debug('lucid_user_provider: using model %O', this.model);
+        return this.model;
+    }
+    /**
+     * Returns an instance of the query builder
+     */
+    getQueryBuilder(model) {
+        return model.query({
+            client: this.options.client,
+            connection: this.options.connection,
+        });
+    }
+    /**
+     * Returns an instance of the "LucidUser" that guards
+     * can use for authentication
+     */
+    async createUserForGuard(user) {
+        const model = await this.getModel();
+        if (user instanceof model === false) {
+            throw new RuntimeException(`Invalid user object. It must be an instance of the "${model.name}" model`);
+        }
+        debug('lucid_user_provider: converting user object to guard user %O', user);
+        return new LucidUser(user);
+    }
+    /**
+     * Finds a user by id using the configured model.
+     */
+    async findById(value) {
+        debug('lucid_user_provider: finding user by id %s', value);
+        const model = await this.getModel();
+        const user = await model.find(value, {
+            client: this.options.client,
+            connection: this.options.connection,
+        });
+        if (!user) {
+            return null;
+        }
+        return new LucidUser(user);
+    }
+    /**
+     * Finds a user using one of the pre-configured unique
+     * ids, via the configured model.
+     */
+    async findByUid(value) {
+        const query = this.getQueryBuilder(await this.getModel());
+        this.options.uids.forEach((uid) => query.orWhere(uid, value));
+        debug('lucid_user_provider: finding user by uids, uids: %O, value: %s', this.options.uids, value);
+        const user = await query.limit(1).first();
+        if (!user) {
+            return null;
+        }
+        return new LucidUser(user);
+    }
+}