@adonisjs/auth 8.2.3 → 9.0.0-1

package/build/src/auth/user_providers/main.d.ts

@@ -0,0 +1,15 @@
+import { BaseLucidUserProvider } from '../../core/user_providers/lucid.js';
+import { BaseDatabaseUserProvider } from '../../core/user_providers/database.js';
+import type { LucidAuthenticatable, UserProviderContract } from '../../core/types.js';
+/**
+ * Using lucid models to find users for session
+ * auth
+ */
+export declare class LucidUserProvider<UserModel extends LucidAuthenticatable> extends BaseLucidUserProvider<UserModel> implements UserProviderContract<InstanceType<UserModel>> {
+}
+/**
+ * Using database query builder to find users for
+ * session auth
+ */
+export declare class DatabaseUserProvider<User extends Record<string, any>> extends BaseDatabaseUserProvider<User> implements UserProviderContract<User> {
+}

package/build/src/auth/user_providers/main.js

@@ -0,0 +1,22 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { BaseLucidUserProvider } from '../../core/user_providers/lucid.js';
+import { BaseDatabaseUserProvider } from '../../core/user_providers/database.js';
+/**
+ * Using lucid models to find users for session
+ * auth
+ */
+export class LucidUserProvider extends BaseLucidUserProvider {
+}
+/**
+ * Using database query builder to find users for
+ * session auth
+ */
+export class DatabaseUserProvider extends BaseDatabaseUserProvider {
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Guard user represents a user independent of the storage
+ * provider. It contains a standard set of properties
+ * used by authentication guards to interact with
+ * a user.
+ *
+ * Think of it as a bridge between a user and the authentication
+ * guard.
+ */
+export declare abstract class GuardUser<RealUser> {
+    protected realUser: RealUser;
+    constructor(realUser: RealUser);
+    /**
+     * Verifies the plain text password against the user password
+     * hash
+     */
+    abstract verifyPassword(plainTextPassword: string): Promise<boolean>;
+    /**
+     * Returns a value to uniquely identify the user.
+     */
+    abstract getId(): number | string;
+    /**
+     * Returns the original provider specific user object.
+     */
+    getOriginal(): RealUser;
+}

package/build/src/core/guard_user.js

@@ -0,0 +1,29 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+/**
+ * Guard user represents a user independent of the storage
+ * provider. It contains a standard set of properties
+ * used by authentication guards to interact with
+ * a user.
+ *
+ * Think of it as a bridge between a user and the authentication
+ * guard.
+ */
+export class GuardUser {
+    realUser;
+    constructor(realUser) {
+        this.realUser = realUser;
+    }
+    /**
+     * Returns the original provider specific user object.
+     */
+    getOriginal() {
+        return this.realUser;
+    }
+}

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

@@ -0,0 +1,89 @@
+import type { TokenContract } from './types.js';
+/**
+ * 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 declare abstract class Token implements TokenContract {
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series: string;
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value: string | undefined;
+    /**
+     * Hash reference to the token hash
+     */
+    hash: string;
+    /**
+     * Token type to uniquely identify a bucket of tokens
+     */
+    abstract readonly type: string;
+    /**
+     * Arbitary meta-data associated with the token
+     */
+    metaData?: Record<string, any>;
+    /**
+     * Timestamp when the token will expire
+     */
+    expiresAt?: Date;
+    /**
+     * Date/time when the token instance was created
+     */
+    createdAt: Date;
+    /**
+     * Date/time when the token was updated
+     */
+    updatedAt: Date;
+    constructor(
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series: string, 
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value: string | undefined, 
+    /**
+     * Hash reference to the token hash
+     */
+    hash: string);
+    /**
+     * Define metadata for the token
+     */
+    setMetaData(metaData: Record<string, any>): this;
+    /**
+     * Verifies the value of a token against the pre-defined hash
+     */
+    verify(value: string): boolean;
+    /**
+     * Define the token expiresAt timestamp from a duration. The value
+     * value must be a number in seconds or a string expression.
+     */
+    setExpiry(duration: string | number): void;
+    /**
+     * Creates token value, series, and hash
+     */
+    static seed(size?: number): {
+        series: string;
+        value: string;
+        hash: string;
+    };
+    /**
+     * Decodes a publicly shared token and return the series
+     * and the token value from it.
+     *
+     * Returns null when unable to decode the token because of
+     * invalid format or encoding.
+     */
+    static decode(value: string): null | {
+        series: string;
+        value: string;
+    };
+}

package/build/src/core/token.js

@@ -0,0 +1,114 @@
+/*
+ * @adonisjs/auth
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { createHash } from 'node:crypto';
+import string from '@adonisjs/core/helpers/string';
+import { base64, safeEqual } from '@adonisjs/core/helpers';
+/**
+ * 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 class Token {
+    series;
+    value;
+    hash;
+    /**
+     * Arbitary meta-data associated with the token
+     */
+    metaData;
+    /**
+     * Timestamp when the token will expire
+     */
+    expiresAt;
+    /**
+     * Date/time when the token instance was created
+     */
+    createdAt = new Date();
+    /**
+     * Date/time when the token was updated
+     */
+    updatedAt = new Date();
+    constructor(
+    /**
+     * Series is a random number stored inside the database as it is
+     */
+    series, 
+    /**
+     * Value is a random number only available at the time of issuing
+     * the token. Afterwards, the value is undefined.
+     */
+    value, 
+    /**
+     * Hash reference to the token hash
+     */
+    hash) {
+        this.series = series;
+        this.value = value;
+        this.hash = hash;
+    }
+    /**
+     * Define metadata for the token
+     */
+    setMetaData(metaData) {
+        this.metaData = metaData;
+        return this;
+    }
+    /**
+     * Verifies the value of a token against the pre-defined hash
+     */
+    verify(value) {
+        const newHash = createHash('sha256').update(value).digest('hex');
+        return safeEqual(this.hash, newHash);
+    }
+    /**
+     * Define the token expiresAt timestamp from a duration. The value
+     * value must be a number in seconds or a string expression.
+     */
+    setExpiry(duration) {
+        /**
+         * Defining a date object and adding seconds since the
+         * creation of the token
+         */
+        this.expiresAt = new Date();
+        this.expiresAt.setSeconds(this.createdAt.getSeconds() + string.seconds.parse(duration));
+    }
+    /**
+     * Creates token value, series, and hash
+     */
+    static seed(size = 30) {
+        const series = string.random(15);
+        const value = string.random(size);
+        const hash = createHash('sha256').update(value).digest('hex');
+        return { series, value: `${base64.urlEncode(series)}.${base64.urlEncode(value)}`, hash };
+    }
+    /**
+     * Decodes a publicly shared token and return the series
+     * and the token value from it.
+     *
+     * Returns null when unable to decode the token because of
+     * invalid format or encoding.
+     */
+    static decode(value) {
+        const [series, ...tokenValue] = value.split('.');
+        if (!series || tokenValue.length === 0) {
+            return null;
+        }
+        const decodedSeries = base64.urlDecode(series);
+        const decodedValue = base64.urlDecode(tokenValue.join('.'));
+        if (!decodedSeries || !decodedValue) {
+            return null;
+        }
+        return {
+            series: decodedSeries,
+            value: decodedValue,
+        };
+    }
+}

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

@@ -0,0 +1,77 @@
+import type { Database } from '@adonisjs/lucid/database';
+import type { DatabaseTokenProviderOptions, TokenProviderContract } from '../types.js';
+/**
+ * The representation of a token inside the database
+ */
+type DatabaseTokenRow = {
+    series: string;
+    user_id: string | number;
+    type: string;
+    token: string;
+    created_at: Date;
+    updated_at: Date;
+    expires_at: Date | null;
+};
+/**
+ * A generic implementation to read tokens from the database
+ */
+export declare abstract class DatabaseTokenProvider<Token> implements TokenProviderContract<Token> {
+    /**
+     * Reference to the database query builder needed to
+     * query the database for tokens
+     */
+    protected db: Database;
+    /**
+     * Options accepted
+     */
+    protected options: DatabaseTokenProviderOptions;
+    constructor(
+    /**
+     * Reference to the database query builder needed to
+     * query the database for tokens
+     */
+    db: Database, 
+    /**
+     * Options accepted
+     */
+    options: DatabaseTokenProviderOptions);
+    /**
+     * Should parse token to a database token row
+     */
+    protected abstract parseToken(token: Token): DatabaseTokenRow;
+    /**
+     * Abstract method to prepare a token from the database
+     * row
+     */
+    protected abstract prepareToken(dbRow: DatabaseTokenRow): Token;
+    /**
+     * Returns an instance of the query builder
+     */
+    protected getQueryBuilder(): import("@adonisjs/lucid/types/querybuilder").DatabaseQueryBuilderContract<DatabaseTokenRow>;
+    /**
+     * Returns an instance of the query builder for insert
+     * queries
+     */
+    protected getInsertQueryBuilder(): import("@adonisjs/lucid/types/querybuilder").InsertQueryBuilderContract<any[]>;
+    /**
+     * Persists token inside the database
+     */
+    createToken(token: Token): Promise<void>;
+    /**
+     * Finds a token by series inside the database and returns an
+     * instance of it.
+     *
+     * Returns null if the token is missing or expired
+     */
+    getTokenBySeries(series: string): Promise<Token | null>;
+    /**
+     * Removes a token from the database by the
+     * series number
+     */
+    deleteTokenBySeries(series: string): Promise<void>;
+    /**
+     * Updates token hash and expiry
+     */
+    updateTokenBySeries(series: string, hash: string, expiresAt: Date): Promise<void>;
+}
+export {};

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 {};